Calendars

A collection of all existing calendars. See also Calendars vs CalendarList.

For a list of methods for this resource, see the end of this page.

Resource representations

{
  "kind": "calendar#calendar",
  "etag": etag,
  "id": string,
  "summary": string,
  "description": string,
  "location": string,
  "timeZone": string,
  "dataOwner": string,
  "conferenceProperties": {
    "allowedConferenceSolutionTypes": [
      string
    ]
  },
  "labelProperties": {
    "eventLabels": [
      {
        "id": string,
        "backgroundColor": string,
        "name": string
      }
    ]
  },
  "autoAcceptInvitations": boolean,
  "workingHours": {
    "workingHoursEnabled": boolean,
    "availableTimes": [
      {
        "dayOfWeek": string,
        "periodStart": integer,
        "periodEnd": integer
      }
    ]
  }
}
Property name Value Description Notes
autoAcceptInvitations boolean Whether this calendar automatically accepts invitations. Only valid for resource calendars.
conferenceProperties nested object Conferencing properties for this calendar, for example what types of conferences are allowed.
conferenceProperties.allowedConferenceSolutionTypes[] list The types of conference solutions that are supported for this calendar.

The possible values are:

  • "eventHangout"
  • "eventNamedHangout"
  • "hangoutsMeet"
Optional.
dataOwner string The email of the owner of the calendar. Set only for secondary calendars. Read-only.
description string Description of the calendar. Optional. writable
etag etag ETag of the resource.
id string Identifier of the calendar. To retrieve IDs call the calendarList.list() method.
kind string Type of the resource ("calendar#calendar").
labelProperties nested object Label properties defined on this calendar. If specified, overwrites the existing label properties. If not specified, the label properties remain unchanged. writable
labelProperties.eventLabels[] list Event labels defined on this calendar. If this is present when updating the calendar, it will replace the existing event labels.

Extend the list to add a new event label, and remove entities from the list to delete a label from calendar.

Each calendar can have a maximum of 200 labels.

 writable
labelProperties.eventLabels[].backgroundColor string Background color of the label in hexadecimal format, such as "#039be5". Events with this label are displayed in this color. Required. writable
labelProperties.eventLabels[].id string The ID of the label. Optional when inserting a new label. If not provided, a unique ID will be generated. Required when updating a label.

If provided, the ID must be unique within the calendar and follow UUID format.

 writable
labelProperties.eventLabels[].name string Name of the label. Optional.

If provided this must have at most 50 characters.

 writable
location string Geographic location of the calendar as free-form text. Optional. writable
summary string Title of the calendar. writable
timeZone string The time zone of the calendar. (Formatted as an IANA Time Zone Database name, e.g. "Europe/Zurich".) Optional. writable
workingHours object Represents the information about the user's working hours. Only available for primary calendars of Google Workspace users. To update the working hours, the entire working hours object must be passed. If not specified (or passed as null or an empty object), the existing working hours remain unchanged. To disable working hours or clear the schedule, set workingHoursEnabled to false (and omit availableTimes or pass an empty list). writable
workingHours.availableTimes[] list Working hours. Each availability period represents the user's working hours block during one day. writable
workingHours.availableTimes[].dayOfWeek string Day of the week. Required. Possible values are:
  • "monday"
  • "tuesday"
  • "wednesday"
  • "thursday"
  • "friday"
  • "saturday"
  • "sunday"
writable
workingHours.availableTimes[].periodEnd integer Period end, in minutes from the start of the day, exclusive. Required. writable
workingHours.availableTimes[].periodStart integer Period start, in minutes from the start of the day, inclusive. Required. writable
workingHours.workingHoursEnabled boolean Whether the working hours are enabled for this calendar. Cannot be set to true when availableTimes is empty. writable

Methods

clear
Clears a primary calendar. This operation deletes all events associated with the primary calendar of an account.
delete
Deletes a secondary calendar. Use calendars.clear for clearing all events on primary calendars.
get
Returns metadata for a calendar.
insert
Creates a secondary calendar.

The authenticated user for the request is made the data owner of the new calendar.

patch
Updates metadata for a calendar. This method supports patch semantics. Note that each patch request consumes three quota units; prefer using a get followed by an update. The field values you specify replace the existing values. Fields that you don't specify in the request remain unchanged. Array fields, if specified, overwrite the existing arrays; this discards any previous array elements.
transferOwnership
Transfers a secondary calendar between users within a Google Workspace organization. Requires user authentication with Manage Calendars administrator privilege, and one of the following authorization scopes:
  • https://www.googleapis.com/auth/calendar
  • https://www.googleapis.com/auth/calendar.calendars
In the request, set useAdminAccess to true. The secondary calendar must be active to be transferred. Transferring disabled or deleted calendars isn't supported.
update
Updates metadata for a calendar.