Extended properties

The fields of the Events resource cover the most common data associated with an event, such as location and start time, but applications might need to store additional metadata specific to their use case. The Google Calendar API lets you set hidden key-value pairs with an event, called extended properties. Extended properties make it easy to store application-specific data for an event without using an external database.

Visibility

There are two types of extended properties available: private and shared. Shared properties are visible and editable by all attendees of an event, while private properties are set on one attendee's local copy of the event. More concretely, private properties are specific to the calendarId and eventId used in the request, while shared properties appear regardless of the calendarId used in the request.

Add and update properties

Extended properties are set on the Events resource, and like other fields can be set in events.insert, events.update, and events.patch requests. Using patch requests is the preferred method, as it lets you manipulate some properties while leaving others untouched. Adding a new property with the same key overwrites any existing property with that key. The following example shows setting a private property:

PATCH https://www.googleapis.com/calendar/v3/calendars/calendarId/events/eventId

{
  "extendedProperties": {
    "private": {
      "petsAllowed": "yes"
    }
  }
}

Delete properties

Any properties not included in an update request are deleted, but a better approach is to make a patch request to set the value to null. The following example shows deleting a private property:

PATCH https://www.googleapis.com/calendar/v3/calendars/calendarId/events/eventId

{
  "extendedProperties": {
    "private": {
      "petsAllowed": null
    }
  }
}

Search properties

You can search events based on the values of their extended properties using an events.list request. Set the field privateExtendedProperty or sharedExtendedProperty to a constraint in the format propertyName=value, which searches against private and shared properties respectively. The following example returns events with the private property petsAllowed=yes:

GET https://www.googleapis.com/calendar/v3/calendars/calendarId/events
    ?privateExtendedProperty=petsAllowed%3Dyes

You can repeat these fields multiple times and the constraints are evaluated with OR logic, so events only need to match one of the constraints to be returned. The following example finds events with either the private property petsAllowed=yes or isOutside=yes:

GET https://www.googleapis.com/calendar/v3/calendars/calendarId/events
    ?privateExtendedProperty=petsAllowed%3Dyes
    &privateExtendedProperty=isOutside%3Dyes

Constraints on private and shared properties are evaluated with AND logic, so events must match both sets of constraints to be returned. The following example finds events with the private property petsAllowed=yes and the public property createdBy=myApp:

GET https://www.googleapis.com/calendar/v3/calendars/calendarId/events
    ?privateExtendedProperty=petsAllowed%3Dyes
    &sharedExtendedProperty=createdBy%3DmyApp

Limits

1. The maximum size of a property key is 44 characters; properties with longer keys are silently dropped.
2. The maximum size of a property value is 1024 characters; properties with longer values are silently truncated.
3. An event can have up to 300 properties totaling up to 32 KB in size (key size plus value size). These 300 properties include shared and private properties, across all copies of the event.