Advanced Calendar Service

The advanced Calendar service allows you to use the public Google Calendar API in Apps Script. Much like Apps Script's built-in Calendar service, this API allows scripts to access and modify the user's Google Calendar, including additional calendars that the user is subscribed to. In most cases, the built-in service is easier to use, but this advanced service provides a few extra features, including setting the background color for individual events.


For detailed information on this service, see the reference documentation for the public Google Calendar API. Like all advanced services in Apps Script, the advanced Calendar service uses the same objects, methods, and parameters as the public API.

Sample code

The sample code below uses version 3 of the API.

Creating events

The following example demonstrates how to create an event in the user's default calendar.

function createEvent() {
  var calendarId = 'primary';
  var start = getRelativeDate(1, 12);
  var end = getRelativeDate(1, 13);
  var event = {
    summary: 'Lunch Meeting',
    location: 'The Deli',
    description: 'To discuss our plans for the presentation next week.',
    start: {
      dateTime: start.toISOString()
    end: {
      dateTime: end.toISOString()
    attendees: [
      {email: ''},
      {email: ''}
    // Red background. Use Calendar.Colors.get() for the full list.
    colorId: 11
  event = Calendar.Events.insert(event, calendarId);
  Logger.log('Event ID: ' + event.getId());

 * Helper function to get a new Date object relative to the current date.
 * @param {number} daysOffset The number of days in the future for the new date.
 * @param {number} hour The hour of the day for the new date, in the time zone
 *     of the script.
 * @return {Date} The new date.
function getRelativeDate(daysOffset, hour) {
  var date = new Date();
  date.setDate(date.getDate() + daysOffset);
  return date;

Listing calendars

The following example demonstrates how to retrieve details about the calendars shown in the user's calendar list.

function listCalendars() {
  var calendars, pageToken;
  do {
    calendars = Calendar.CalendarList.list({
      maxResults: 100,
      pageToken: pageToken
    if (calendars.items && calendars.items.length > 0) {
      for (var i = 0; i < calendars.items.length; i++) {
        var calendar = calendars.items[i];
        Logger.log('%s (ID: %s)', calendar.summary,;
    } else {
      Logger.log('No calendars found.');
    pageToken = calendars.nextPageToken;
  } while (pageToken);

Listing events

The following example demonstrates how to list the next 10 upcoming events in the user's default calendar.

function listNext10Events() {
  var calendarId = 'primary';
  var now = new Date();
  var events = Calendar.Events.list(calendarId, {
    timeMin: now.toISOString(),
    singleEvents: true,
    orderBy: 'startTime',
    maxResults: 10
  if (events.items && events.items.length > 0) {
    for (var i = 0; i < events.items.length; i++) {
      var event = events.items[i];
      if ( {
        // All-day event.
        var start = parseDate(;
        Logger.log('%s (%s)', event.summary, start.toLocaleDateString());
      } else {
        var start = parseDate(event.start.dateTime);
        Logger.log('%s (%s)', event.summary, start.toLocaleString());
  } else {
    Logger.log('No events found.');

 * Parses an RFC 3339 date or datetime string and returns a corresponding Date
 * object. This function is provided as a workaround until Apps Script properly
 * supports RFC 3339 dates. For more information, see
 * @param {string} string The RFC 3339 string to parse.
 * @return {Date} The parsed date.
function parseDate(string) {
  var parts = string.split('T');
  parts[0] = parts[0].replace(/-/g, '/');
  return new Date(parts.join(' '));