The fields of the [Events resources](https://developers.google.com/workspace/calendar/v3/reference/events)
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](https://developers.google.com/workspace/calendar/v3/reference/events#extendedProperties).
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](https://developers.google.com/workspace/calendar/v3/reference/events/insert),
[update](https://developers.google.com/workspace/calendar/v3/reference/events/update), and
[patch](https://developers.google.com/workspace/calendar/v3/reference/events/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](https://developers.google.com/workspace/calendar/v3/reference/events/list) request.
Set the field
[privateExtendedProperty](https://developers.google.com/workspace/calendar/v3/reference/events/list#privateExtendedProperty)
or
[sharedExtendedProperty](https://developers.google.com/workspace/calendar/v3/reference/events/list#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.