Google Calendar

Google Calendar API

The Google Calendar API lets you manage calendars, events, access control, settings, and free/busy information. It supports creating events, subscribing to calendars, querying availability, and receiving push notifications for changes.

GitHub OpenAPI

Documentation

📖
Documentation
https://developers.google.com/workspace/calendar/api/guides/overview
📖
Authentication
https://developers.google.com/workspace/calendar/api/auth
📖
GettingStarted
https://developers.google.com/workspace/calendar/api/quickstart/python

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/google-calendar/refs/heads/main/openapi/openapi.yml

Schemas & Data

📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/google-calendar/refs/heads/main/json-schema/json-schema.yml

Other Resources

🔗
JSONLD
https://raw.githubusercontent.com/api-evangelist/google-calendar/refs/heads/main/json-ld/json-ld.jsonld

OpenAPI Specification

openapi.yml Raw ↑ 
openapi: 3.1.0
info:
  title: Google Calendar API
  description: >-
    The Google Calendar API provides RESTful access to Google Calendar data.
    It enables managing calendars, events, access control lists, settings,
    and free/busy information.
  version: v3
  contact:
    name: Google
    url: https://developers.google.com/workspace/calendar/api/guides/overview
servers:
  - url: https://www.googleapis.com/calendar/v3
paths:
  /calendars:
    post:
      operationId: createCalendar
      summary: Google Calendar Create calendar
      description: Creates a secondary calendar.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Calendar'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Calendar'
      tags:
        - Calendars
  /calendars/{calendarId}:
    get:
      operationId: getCalendar
      summary: Google Calendar Get calendar
      description: Returns metadata for a calendar.
      parameters:
        - name: calendarId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Calendar'
      tags:
        - Calendars
    put:
      operationId: updateCalendar
      summary: Google Calendar Update calendar
      description: Updates metadata for a calendar.
      parameters:
        - name: calendarId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Calendar'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Calendar'
      tags:
        - Calendars
    delete:
      operationId: deleteCalendar
      summary: Google Calendar Delete calendar
      description: Deletes a secondary calendar.
      parameters:
        - name: calendarId
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Successful deletion
      tags:
        - Calendars
  /calendars/{calendarId}/events:
    get:
      operationId: listEvents
      summary: Google Calendar List events
      description: Returns events on the specified calendar.
      parameters:
        - name: calendarId
          in: path
          required: true
          schema:
            type: string
        - name: maxResults
          in: query
          schema:
            type: integer
        - name: pageToken
          in: query
          schema:
            type: string
        - name: timeMin
          in: query
          schema:
            type: string
            format: date-time
        - name: timeMax
          in: query
          schema:
            type: string
            format: date-time
        - name: q
          in: query
          schema:
            type: string
        - name: singleEvents
          in: query
          schema:
            type: boolean
        - name: orderBy
          in: query
          schema:
            type: string
            enum: [startTime, updated]
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Events'
      tags:
        - Calendars
    post:
      operationId: createEvent
      summary: Google Calendar Create event
      description: Creates an event.
      parameters:
        - name: calendarId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Event'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Event'
      tags:
        - Calendars
  /calendars/{calendarId}/events/{eventId}:
    get:
      operationId: getEvent
      summary: Google Calendar Get event
      description: Returns an event.
      parameters:
        - name: calendarId
          in: path
          required: true
          schema:
            type: string
        - name: eventId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Event'
      tags:
        - Calendars
    put:
      operationId: updateEvent
      summary: Google Calendar Update event
      description: Updates an event.
      parameters:
        - name: calendarId
          in: path
          required: true
          schema:
            type: string
        - name: eventId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Event'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Event'
      tags:
        - Calendars
    patch:
      operationId: patchEvent
      summary: Google Calendar Patch event
      description: Updates an event with patch semantics.
      parameters:
        - name: calendarId
          in: path
          required: true
          schema:
            type: string
        - name: eventId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Event'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Event'
      tags:
        - Calendars
    delete:
      operationId: deleteEvent
      summary: Google Calendar Delete event
      description: Deletes an event.
      parameters:
        - name: calendarId
          in: path
          required: true
          schema:
            type: string
        - name: eventId
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Successful deletion
      tags:
        - Calendars
  /calendars/{calendarId}/events/quickAdd:
    post:
      operationId: quickAddEvent
      summary: Google Calendar Quick add event
      description: Creates an event based on a simple text string.
      parameters:
        - name: calendarId
          in: path
          required: true
          schema:
            type: string
        - name: text
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Event'
      tags:
        - Calendars
  /calendars/{calendarId}/acl:
    get:
      operationId: listAcl
      summary: Google Calendar List ACL rules
      description: Returns the rules in the access control list for the calendar.
      parameters:
        - name: calendarId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Acl'
      tags:
        - Calendars
    post:
      operationId: insertAcl
      summary: Google Calendar Insert ACL rule
      description: Creates an access control rule.
      parameters:
        - name: calendarId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AclRule'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AclRule'
      tags:
        - Calendars
  /users/me/calendarList:
    get:
      operationId: listCalendarList
      summary: Google Calendar List calendar list
      description: Returns the calendars on the user's calendar list.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CalendarList'
      tags:
        - Users
    post:
      operationId: insertCalendarList
      summary: Google Calendar Insert calendar to list
      description: Inserts an existing calendar into the user's calendar list.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CalendarListEntry'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CalendarListEntry'
      tags:
        - Users
  /users/me/settings:
    get:
      operationId: listSettings
      summary: Google Calendar List settings
      description: Returns all user settings for the authenticated user.
      responses:
        '200':
          description: Successful response
      tags:
        - Users
  /freeBusy:
    post:
      operationId: queryFreeBusy
      summary: Google Calendar Query free/busy
      description: Returns free/busy information for a set of calendars.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FreeBusyRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FreeBusyResponse'
      tags:
        - freeBusy
  /colors:
    get:
      operationId: getColors
      summary: Google Calendar Get colors
      description: Returns the color definitions for calendars and events.
      responses:
        '200':
          description: Successful response
      tags:
        - Colors
components:
  schemas:
    Calendar:
      type: object
      properties:
        kind:
          type: string
        etag:
          type: string
        id:
          type: string
        summary:
          type: string
        description:
          type: string
        location:
          type: string
        timeZone:
          type: string
    Event:
      type: object
      properties:
        kind:
          type: string
        etag:
          type: string
        id:
          type: string
        status:
          type: string
        htmlLink:
          type: string
        created:
          type: string
          format: date-time
        updated:
          type: string
          format: date-time
        summary:
          type: string
        description:
          type: string
        location:
          type: string
        start:
          $ref: '#/components/schemas/EventDateTime'
        end:
          $ref: '#/components/schemas/EventDateTime'
        attendees:
          type: array
          items:
            $ref: '#/components/schemas/EventAttendee'
        recurrence:
          type: array
          items:
            type: string
    EventDateTime:
      type: object
      properties:
        date:
          type: string
          format: date
        dateTime:
          type: string
          format: date-time
        timeZone:
          type: string
    EventAttendee:
      type: object
      properties:
        email:
          type: string
        displayName:
          type: string
        responseStatus:
          type: string
          enum: [needsAction, declined, tentative, accepted]
        optional:
          type: boolean
    Events:
      type: object
      properties:
        kind:
          type: string
        etag:
          type: string
        summary:
          type: string
        nextPageToken:
          type: string
        items:
          type: array
          items:
            $ref: '#/components/schemas/Event'
    AclRule:
      type: object
      properties:
        kind:
          type: string
        etag:
          type: string
        id:
          type: string
        role:
          type: string
          enum: [none, freeBusyReader, reader, writer, owner]
        scope:
          type: object
          properties:
            type:
              type: string
            value:
              type: string
    Acl:
      type: object
      properties:
        kind:
          type: string
        etag:
          type: string
        items:
          type: array
          items:
            $ref: '#/components/schemas/AclRule'
    CalendarListEntry:
      type: object
      properties:
        kind:
          type: string
        etag:
          type: string
        id:
          type: string
        summary:
          type: string
        description:
          type: string
        timeZone:
          type: string
        backgroundColor:
          type: string
        foregroundColor:
          type: string
        selected:
          type: boolean
        primary:
          type: boolean
    CalendarList:
      type: object
      properties:
        kind:
          type: string
        etag:
          type: string
        nextPageToken:
          type: string
        items:
          type: array
          items:
            $ref: '#/components/schemas/CalendarListEntry'
    FreeBusyRequest:
      type: object
      properties:
        timeMin:
          type: string
          format: date-time
        timeMax:
          type: string
          format: date-time
        timeZone:
          type: string
        items:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
    FreeBusyResponse:
      type: object
      properties:
        kind:
          type: string
        timeMin:
          type: string
          format: date-time
        timeMax:
          type: string
          format: date-time
        calendars:
          type: object
tags:
  - name: Calendars
  - name: Colors
  - name: freeBusy
  - name: Users