Get a calendar

Google Apps Script has a built-in CalendarApp class, a library for working with Google Calendar.

This article explains how to use the CalendarApp class to get a CalendarApp.Calendar object, the starting point for many other operations.

Because GAS accesses Google Calendar, you need to grant permissions the first time you run the script.

Overview of the methods on this page

If you just want to know which method to use, select a tab from the tab list to see a sample of that method.

/** @type { CalendarApp.Calendar[] }  */
const calendars = CalendarApp.getAllCalendars();

/** @type { CalendarApp.Calendar[] }  */
const calendars = CalendarApp.getAllOwnedCalendars();

const CALENDAR_ID = "___ID_of_the_calendar_to_get___"

/** @type { CalendarApp.Calendar | null }  */
const calendar = CalendarApp.getCalendarById(CALENDAR_ID);

const CALENDAR_NAME = "To-do list"

/** @type { CalendarApp.Calendar[] }  */
const calendars = CalendarApp.getCalendarsByName(CALENDAR_NAME);

Get all calendars, regardless of who created them

Google Calendar shows both the calendars you own and the calendars that other users created and you subscribed to.

To get all of them, use the CalendarApp.getAllCalendars method.

Method to use

/**
 * @return { CalendarApp.Calendar[] } All calendars that the user owns or is subscribed to
 */
CalendarApp.getAllCalendars;

Sample code

/** All calendars */
const calendars = CalendarApp.getAllCalendars();

console.log(`Got ${calendars.length} calendars`);

for (const calendar of calendars) {
  console.log(`The calendar name is "${calendar.getName()}"`);
}

Get all calendars you own

To get only the calendars you own, excluding calendars that other users created and you subscribed to, use the CalendarApp.getAllOwnedCalendars method.

Method to use

/**
 * @return { CalendarApp.Calendar[] } All calendars you own
 */
CalendarApp.getAllOwnedCalendars;

Sample code

/** All calendars you own */
const calendars = CalendarApp.getAllOwnedCalendars();

console.log(`Got ${calendars.length} calendars`);

for (const calendar of calendars) {
  console.log(`The calendar name is "${calendar.getName()}"`);
}

Get a calendar by ID

You can get one specific calendar by specifying its ID.

Use the CalendarApp.getCalendarById method.

Method to use

/**
 * @return { CalendarApp.Calendar | null } Target calendar
 */
CalendarApp.getCalendarById;

If no calendar with that ID exists, if the user running the script can’t access the calendar, or if the user hasn’t subscribed to the calendar, null is returned.

Sample code

/** Calendar ID */
const CALENDAR_ID = '___ID_of_the_calendar_to_get___';

function myFunction() {
  /** Target calendar */
  const calendar = CalendarApp.getCalendarById(CALENDAR_ID);

  if (!calendar) {
    console.log('The calendar was not found');
    return;
  }

  console.log(`The calendar name is "${calendar.getName()}"`);
}

Get calendars by name

You can get specific calendars by specifying their name.

Use the CalendarApp.getCalendarsByName method.

Method to use

/**
 * @return { CalendarApp.Calendar[] } Target calendars
 */
CalendarApp.getCalendarsByName;

The method looks for calendars with a matching name among the calendars you own or are subscribed to. The name match isn’t case-sensitive.

Because calendar names can be duplicated, the method returns an array of calendars.

If there are two calendars with the same name, you get both of them.

Sample code

/** Calendar name */
const CALENDAR_NAME = 'To-do list';

/** Target calendars */
const calendars = CalendarApp.getCalendarsByName(CALENDAR_NAME);

console.log(`There are ${calendars.length} calendars named ${CALENDAR_NAME}`);