Extended properties

The fields of the Events resources cover the most common data associated with an event, such as location, start time, etc, but applications may want to store additional metadata specific to their use case. The Calendar API provides the ability to 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 having to utilize 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 will be shown regardless of the calendarId used in the request.

Add & update properties

Extended properties are set on the Events resource, and like other fields can be set in insert, update, and patch requests. Using patch requests is the preferred method, as it allows you to manipulate some properties while leaving others untouched. Adding a new property with the same key will overwrite any existing properties with the same 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 will be 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 on 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 OR'ed together, 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

Be aware that constraints on private and shared properties are AND'ed together however, so events must match both sets of constraints in order 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's key is 44 characters, and properties with longer keys will be silently dropped.
2. The maximum size of a property's value is 1024 characters, and properties with longer values will be silently truncated.
3. An event can have up to 300 properties totaling up to 32kB in size (keys size + value size). These 300 properties include shared and private properties, across all "copies" of the event.