Accessing Google Calendar using the php API

Google provides a good UI for their calendars for manual use, and calendars can easily be embedded in other sites, but being able to access them programmatically adds another dimension of usefulness.

Many of Google’s services have API’s in various languages.  These notes relate to using the Google Calendar API v3 with php.

Scenario

I wanted to use a php script to grab data from a Google Calendar, either to write to a file or serve up as part of a web page.

Warning

Firstly, a word of warning.  I wasted some time looking at old documentation.  There are multiple versions of documentation that apparently relate to the same thing but with differing information.  Old documentation has not been updated or removed and there is no indication that it is old.

If you want to use the php API, DO NOT use the instructions at https://developers.google.com/google-apps/calendar/  These point to old code on http://google-api-php-client.googlecode.com/ which is deprecated.

The place to look is https://developers.google.com/api-client-library/ and the code is on github at https://github.com/google/google-api-php-client

[Looking at https://developers.google.com/api-client-library/php/guide/migration, it seems the github version is 1.0.0 of the php library for the Calendar v3 API]

Setup

Follow the instructions at https://developers.google.com/api-client-library/php/start/get_started to create a project in the Google Developer’s Console and install the client library.

Authentication and Authorization

The API key approach does not provide access to private data.  In my application, I do want to access private data so we need the OAuth 2.0 approach.  This is not as complicated as it sounds!

There are three different types of client id’s that can be used:

• Web application client IDs
• Installed application client IDs
• Service Account client IDs

Although the notes warn you of the importance of choosing the right type, they don’t provide guidance. See here or here (but beware of following other links from that page to old documentation)

For my purposes, I want an automated process to access some calendars, so a Service Account is most appropriate.

Create a Service Account

In Google Developer Console select your project, then ‘API’s & Auth’, then ‘Credentials’, then ‘Create New Client ID’ and choose ‘Service Account’.  You will be prompted to save the private key for the id. Make sure you do save it since it can’t be downloaded later (although you can generate new keys).

You will need the ‘Client ID’ and ‘Email Address’ in the next steps.

Sharing the Calendar

The Client ID, Email Address and Private Key File will be used by the php script to authenticate to the calendar service, but it needs to be authorized to access private data.  Just because we can connect to the service doesn’t mean it should give us whatever data we ask for!  We need to share the calendar that we want to access with the Service Account ID we have just created.

Log in to the Calendar using the normal web GUI. Locate the calendar on the left panel under ‘My Calendars’, hover over it to reveal the dropdown arrow, then select ‘Share this Calendar’.  Under the ‘Share with specific people’ section, enter the Email Address from the previous step and check it has enough access for your intended use.  For me, that means ‘See all event details’. Then click ‘Add Person’, then ‘Save’.

The calendar is now shared with the service account, so our php script can access it.

Before closing the calendar, go to the ‘Calendar Details’ link, and look for the ‘Calendar Address’ section.  You need to copy the Calendar ID – looks like an email address: long string of random stuff @ group.calendar.google.com

PHP script

At long last, we’re ready to start some coding.

See: https://developers.google.com/api-client-library/php/guide/aaa_oauth2_service

And the example here: https://github.com/google/google-api-php-client/blob/master/examples/service-account.php

Putting all the pieces together, we need the Client ID, Email Address, Private Key File and Calendar ID to plug into this script.  Hopefully it works…  Note that many errors result in a 404 status and the error message is not very useful.

I didn’t find much documentation for the PHP API, but the code is easy to read at https://github.com/google/google-api-php-client/blob/master/src/Google/Service/Calendar.php

Listing Events

To explore the API in the Developer Console, click on ‘API’s & Auth’, then ‘API’, and select the Calendar API.  See the section on calendar.events.list   Some useful options include:

• singleEvents – convert recurring events to single events
• timeMax, timeMin – for searching by the start time of events
• fields – to control which fields are returned

Sample Code

(Edited based on comments and questions – last update Jan 8, 2015)

#!/usr/bin/php
<?php

require_once "Google/Client.php";
require_once "Google/Service/Calendar.php";

// Service Account info
$client_id = 'replace with Service Account Client Id';
$service_account_name = 'replace with Service Account Email Address';
$key_file_location = 'replace with Service Account Private Key filename';

// Calendar id
$calName = 'replace with Calendar ID';


$client = new Google_Client();
$client->setApplicationName("Calendar test");

$service = new Google_Service_Calendar($client);

$key = file_get_contents($key_file_location);
$cred = new Google_Auth_AssertionCredentials(
 $service_account_name,
 array('https://www.googleapis.com/auth/calendar.readonly'),
 $key
);

$client->setAssertionCredentials($cred);

$cals = $service->calendarList->listCalendarList();
print_r($cals);
//exit;

// Convert recurring events to single events
// Look for events in the next week - now to now+1week
$params = array(
 'singleEvents' => TRUE,
 'timeMin' => (new DateTime())->format(DateTime::RFC3339),
 'timeMax' => (new DateTime())->add(new DateInterval('P1W'))->format(DateTime::RFC3339),
);
$events = $service->events->listEvents($calName, $params);

foreach ($events->getItems() as $event) {
 echo "Summary:  ", $event->getSummary(), "\n";
 echo "Location: ", $event->getLocation(), "\n";
 echo "Start:    ", fmt_gdate($event->getStart()), "\n";
 echo "End:      ", fmt_gdate($event->getEnd()), "\n";
}

function fmt_gdate( $gdate ) {
  if ($val = $gdate->getDateTime()) {
    return (new DateTime($val))->format( 'd/m/Y H:i' );
  } else if ($val = $gdate->getDate()) {
    return (new DateTime($val))->format( 'd/m/Y' ) . ' (all day)';
  }
}

Tagged: API, Google Calendar, OAuth2, PHP, Service Account