Event types

This page explains the eventType property, and specifications of event types available in the Google Calendar API.

Google Calendar lets users create generic events, as well as events that are designed for specific use cases and with custom properties.

You can discover the event type in the following places in the API:

All events return an eventType.
Set eventType when creating or updating an event resource. If unset, the API uses 'default'.
Specify eventTypes in an events.list call to list events of specific types. If no type is specified, the API returns all event types.
Specify eventTypes in an events.watch call to subscribe to updates on events of specific types. If no type is specified, the request subscribes to all event types.

Default event

Events with the default event type are created and used as one of the main resources of the Calendar API. They support a wide range of properties to further customize the event.

See Create events to start working with Calendar events.

Birthday

Birthdays are special all-day events with an annual recurrence.

Users can manually create birthday events on Calendar. In addition, the birthday information syncs with Calendar when users add a person and include their birthday and other significant dates in Google Contacts. Users' own birthdays also sync to Calendar from their Google Account profile.

The Calendar API supports events.get, events.instances, and events.list methods for reading birthday events. You can set eventTypes to 'birthday' to list only birthday events. If no type is specified, the response lists birthdays alongside all other event types.

In the returned Event objects, inspect the birthdayProperties field for more details about this special event. birthdayProperties has the following fields:

type: Type of this special event, whether it's a birthday, an anniversary, or another significant date.
customTypeName: User-specified label for this special event. This is populated if type is set to 'custom'.
contact: Resource name of the contact this special event is linked to, if any. This has the format 'people/c12345' and can be used to fetch contact details from the People API.

The API lets you create birthday events using the events.insert method with the following specifications:

eventType is set to 'birthday'.
start and end fields must define an all-day event that spans exactly one day.
visibility field value must be 'private'.
transparency field value must be 'transparent'.
Must have an annual recurrence, which means that the recurrence field must be 'RRULE:FREQ=YEARLY'. Birthday events falling on February 29 must have the following recurrence rule: 'RRULE:FREQ=YEARLY;BYMONTH=2;BYMONTHDAY=-1'.
Can have a colorId, summary, and reminders.
Can have birthdayProperties. If specified, type must be 'birthday', and both customTypeName and contact must be empty.
Cannot have any other event properties.

The API lets you update the colorId, summary, and reminders of birthday events using the events.update and events.patch methods. You can also update start and end fields to change the event date. In this case, the new values must define an all-day event that spans exactly one day. Timing details of a birthday event cannot be updated if the event is linked to a contact, or its type is 'self'.

The Calendar API doesn't allow creating birthday events with custom birthdayProperties, or updating these properties. Significant dates can be edited with the People API, and the changes sync with Calendar. Similarly, users can edit their own birthday on their Google Account profile, and it syncs with Calendar.

Requests that try to create or update a birthday in an unsupported way fail. In this case, inspect the error message to identify the issue.

The API supports the events.import operation for birthday events; however, the event is imported as a default event. In other words, the eventType will be 'default'.

The API supports the events.watch method to subscribe to changes on birthday events on Calendar. You can set eventTypes to 'birthday' to subscribe to updates on birthday events. If no type is specified, the request subscribes to all event types, including birthdays.

You can delete birthday events using the events.delete method of the Calendar API. Deleting a birthday event from Calendar doesn't affect data on Google Contacts or Google Account profile.

Changing the organizer of a birthday event using the events.move or events.update methods is not supported.

Events from Gmail

Events automatically generated from Gmail have the 'fromGmail' event type.

The Calendar API doesn't allow creating this event type using the events.insert method.

The API lets you update the colorId, reminders, visibility, transparency, status, attendees, private, and shared extended properties using the events.update and events.patch methods.

The API supports the events.get and events.list methods for reading events from Gmail. You can set eventTypes to 'fromGmail' to list only events generated from Gmail. If no type is specified, events from Gmail are listed alongside all other event types.

The API supports the events.watch method to subscribe to changes on events from Gmail on Calendar. If no type is specified, the request subscribes to all event types, including 'fromGmail'.

You can delete events from Gmail using the events.delete method of the Calendar API.

Changing the organizer of an event from Gmail using the events.move or events.update methods is not supported.

Focus time, out of office, and working location

You can use the Calendar API to create and manage events that show the status of Calendar users.

These features are only available on primary calendars, and to some Calendar users. See Manage focus time, out of office, and working location events to learn more.

Explore event types in Apps Script

Apps Script is a JavaScript-based cloud scripting language that lets you build business applications that integrate with Google Workspace. Scripts are developed in a browser-based code editor, and they are stored and run on Google's servers. See also Apps Script quickstart to start using Apps Script to send requests to the Calendar API.

The following instructions describe how to read and manage events using the Calendar API as an advanced service in Apps Script. For a complete list of Calendar API resources and methods, see the reference documentation.

Create and set up the script

Create a script by going to script.google.com/create.
On the left pane next to Services, click Add a service .
Select Calendar API and click Add.
After you enable the API, it appears on the left pane. You can list available methods and classes in the API by typing Calendar in the editor.

(Optional) Update the Cloud project

Each Apps Script project has an associated Cloud project. Your script can use the default project that Apps Script automatically creates. If you want to use a custom Cloud project, see Switch to a different standard Cloud project. After setting the Cloud project, select Editor on the left side to navigate back to the code editor.

Add code to the script

The following code sample shows how to list, read, and create events with different eventType values.

Paste the following into the code editor.

const CALENDAR_ID = 'CALENDAR_ID' || 'primary';

/** Lists default events. */
function listDefaultEvents() {
  listEvents('default');
}

/** Lists birthday events. */
function listBirthdays() {
  listEvents('birthday');
}

/** Lists events from Gmail. */
function listEventsFromGmail() {
  listEvents('fromGmail');
}

/**
  * Lists events with the given event type. If no type is specified, lists all events.
  * See https://developers.google.com/workspace/calendar/api/v3/reference/events/list
  */
function listEvents(eventType = undefined) {
  // Query parameters for the list request.
  const optionalArgs = {
    eventTypes: eventType ? [eventType] : undefined,
    singleEvents: true,
    timeMax: '2024-07-30T00:00:00+01:00',
    timeMin: '2024-07-29T00:00:00+01:00',
  }
  try {
    var response = Calendar.Events.list(CALENDAR_ID, optionalArgs);
    response.items.forEach(event => console.log(event));
  } catch (exception) {
    console.log(exception.message);
  }
}

/**
  * Reads the event with the given eventId.
  * See https://developers.google.com/workspace/calendar/api/v3/reference/events/get
  */
function readEvent() {
  try {
    var response = Calendar.Events.get(CALENDAR_ID, 'EVENT_ID');
    console.log(response);
  } catch (exception) {
    console.log(exception.message);
  }
}

/** Creates a default event. */
function createDefaultEvent() {
  const event = {
    start: { dateTime: '2024-07-30T10:30:00+01:00'},
    end: { dateTime: '2024-07-30T12:30:00+01:00'},
    description: 'Created from Apps Script.',
    eventType: 'default',
    summary: 'Sample event',
  }
  createEvent(event);
}

/** Creates a birthday event. */
function createBirthday() {
  const event = {
    start: { date: '2024-01-29' },
    end: { date: '2024-01-30' },
    eventType: 'birthday',
    recurrence: ["RRULE:FREQ=YEARLY"],
    summary: "My friend's birthday",
    transparency: "transparent",
    visibility: "private",
  }
  createEvent(event);
}

/**
  * Creates a Calendar event.
  * See https://developers.google.com/workspace/calendar/api/v3/reference/events/insert
  */
function createEvent(event) {

  try {
    var response = Calendar.Events.insert(event, CALENDAR_ID);
    console.log(response);
  } catch (exception) {
    console.log(exception.message);
  }
}

Replace the following:

CALENDAR_ID: Email address of the calendar to retrieve and create events on. This constant is initially set to 'primary', which is a keyword to access the primary calendar of the signed-in user. Changing this value lets you read events on the calendars of other users you have access to.
EVENT_ID: ID of the event. You can call events.list to retrieve event IDs.

Run the code sample

Above the code editor, select the function to run from the drop-down menu, and click Run.
The first time you run the script, you are prompted to authorize access. Review and allow Apps Script to access your calendar.
You can inspect the results of the script execution in the Execution log that appears at the bottom of the window.