2025 Growth Unified Hits Major Growth Milestones with 6.5x usage & 4.5x revenue growth
Unified.to
All articles

How to Integrate with Google Calendar API: A Step-by-Step Guide for Developers

February 26, 2026

If you only need Google Calendar, you can integrate it directly.

If your roadmap includes Outlook, iCloud, Calendly, Teams, Zoom, recordings, or broader workflows across CRM, ATS, and AI features, direct integration becomes much more expensive over time. The Google Calendar API itself is powerful, but you still have to set up Google Cloud, configure OAuth, manage scopes, refresh tokens, renew webhook channels, handle incremental sync, and then repeat similar work for every other calendar and meeting integration you support. Google's Calendar API is REST-based, supports client libraries, and exposes core resources like Events and Freebusy. (Google for Developers)

This guide walks through both paths:

  • how to integrate Google Calendar directly
  • where direct integration gets harder in production
  • how to support Google Calendar through Unified
  • why Unified becomes easier once you need more than one calendar or meeting integration

What the Google Calendar API lets you do

Google Calendar gives you programmatic access to common calendar operations, including reading events, creating and updating events, checking free/busy availability, and subscribing to change notifications. Google documents the API as RESTful and available through both direct HTTP calls and official client libraries. (Google for Developers)

For most product teams, the core operations are:

  • list upcoming events
  • create events with attendees
  • update or delete events
  • query availability
  • watch for changes
  • retrieve only changed records using sync tokens

Google supports all of those directly. (Google for Developers)

Before you start

For a direct integration, you need:

  • a Google Cloud project
  • the Google Calendar API enabled
  • an OAuth consent screen configured
  • OAuth client credentials for your app type
  • the right scopes for your use case

Google's current quickstarts route setup through Google Auth platform > Branding for the consent screen and Google Auth platform > Clients for client credentials. (Google for Developers)

Step 1: Create a Google Cloud project and enable the API

In Google Cloud Console:

  1. Create a new project.
  2. Go to APIs & Services > Library.
  3. Search for Google Calendar API.
  4. Click Enable.

Google's overview and quickstarts still use this setup flow. (Google for Developers)

Google requires an OAuth consent screen before you can issue OAuth client credentials for end-user access.

In the current console flow:

  1. Go to Google Auth platform > Branding.
  2. Enter your app name and support email.
  3. Choose your audience, typically Internal for Workspace-only apps or External for public apps.
  4. Add contact information.
  5. Configure data access and scopes as needed.

Google's quickstarts now explicitly reference the Google Auth platform setup flow, including Branding, Audience, and Data Access. (Google for Developers)

Step 3: Create OAuth client credentials

Next:

  1. Go to Google Auth platform > Clients.
  2. Create an OAuth client.
  3. Choose the application type:
    • Web application
    • Desktop app
    • Android
    • iOS
  4. For web apps, add:
    • authorized JavaScript origins
    • authorized redirect URIs

Google's quickstarts and OAuth docs confirm that each platform should have its own OAuth client ID. (Google for Developers)

Step 4: Choose the right scopes

Scopes are where many integrations go wrong.

Google's Calendar auth guide recommends configuring OAuth carefully and choosing scopes that match the exact level of access you need. Google also notes that some scopes are sensitive and can trigger a more involved review process. (Google for Developers)

A practical way to think about scopes:

  • use a read-only scope if you only need to show events or availability
  • use an event write scope if you create or modify events
  • use broader calendar scopes only when you truly need them

For this guide, a simple starting point is:

https://www.googleapis.com/auth/calendar.readonly

for reading events, then expand later if you need writes.

Step 5: Install the client library

For Python, Google's quickstart uses the official client libraries.

pip install --upgrade google-api-python-client google-auth-httplib2 google-auth-oauthlib

Google's Python quickstart and related examples use those packages for desktop-style OAuth and API calls. (Google for Developers)

Step 6: Authenticate and list events

A minimal Python example looks like this:

import datetime
import os.path

from google.auth.transport.requests import Request
from google.oauth2.credentials import Credentials
from google_auth_oauthlib.flow import InstalledAppFlow
from googleapiclient.discovery import build

SCOPES = ["https://www.googleapis.com/auth/calendar.readonly"]

def main():
    creds = None

    if os.path.exists("token.json"):
        creds = Credentials.from_authorized_user_file("token.json", SCOPES)

    if not creds or not creds.valid:
        if creds and creds.expired and creds.refresh_token:
            creds.refresh(Request())
        else:
            flow = InstalledAppFlow.from_client_secrets_file(
                "credentials.json", SCOPES
            )
            creds = flow.run_local_server(port=0)

        with open("token.json", "w") as token:
            token.write(creds.to_json())

    service = build("calendar", "v3", credentials=creds)

    now = datetime.datetime.utcnow().isoformat() + "Z"
    events_result = service.events().list(
        calendarId="primary",
        timeMin=now,
        maxResults=10,
        singleEvents=True,
        orderBy="startTime"
    ).execute()

    events = events_result.get("items", [])

    for event in events:
        start = event["start"].get("dateTime", event["start"].get("date"))
        print(start, event.get("summary", "(no title)"))

if __name__ == "__main__":
    main()

This pattern matches Google's quickstart flow: obtain OAuth credentials, build the Calendar service, then call events.list. Google's reference confirms the events.list endpoint and the primary calendar keyword. (Google for Developers)

Step 7: Create an event

To create an event, use events.insert.

Google's reference documents events.insert on:

POST https://www.googleapis.com/calendar/v3/calendars/{calendarId}/events

and allows primary as the calendar ID for the currently logged-in user's primary calendar. (Google for Developers)

Example:

event_body = {
    "summary": "Customer Onboarding Call",
    "description": "Kickoff with the customer success team.",
    "start": {
        "dateTime": "2026-04-02T10:00:00-04:00",
        "timeZone": "America/New_York"
    },
    "end": {
        "dateTime": "2026-04-02T10:30:00-04:00",
        "timeZone": "America/New_York"
    },
    "attendees": [
        {"email": "customer@example.com"}
    ]
}

created = service.events().insert(
    calendarId="primary",
    body=event_body,
    sendUpdates="all"
).execute()

print(created["id"])

Step 8: Update or delete an event

For updates, Google supports both events.update and events.patch.

The important nuance is that update replaces the full resource, while patch supports partial updates. Google also notes that patch consumes more quota units than a normal update. (Google for Developers)

Partial update example:

service.events().patch(
    calendarId="primary",
    eventId=event_id,
    body={"summary": "Updated Onboarding Call"}
).execute()

Delete example:

service.events().delete(
    calendarId="primary",
    eventId=event_id,
    sendUpdates="all"
).execute()

Step 9: Query free/busy availability

For scheduling products, freebusy.query is often more important than raw event reads.

Google documents the free/busy endpoint as:

POST https://www.googleapis.com/calendar/v3/freeBusy

It returns busy intervals for a set of calendars. (Google for Developers)

Example:

body = {
    "timeMin": "2026-04-02T00:00:00Z",
    "timeMax": "2026-04-03T00:00:00Z",
    "timeZone": "America/New_York",
    "items": [{"id": "primary"}]
}

availability = service.freebusy().query(body=body).execute()
print(availability)

One subtle point: free/busy gives you busy blocks, not ready-made free slots. Your application still has to compute the complement and then rank candidate windows.

Step 10: Subscribe to changes with webhooks

Google supports change notifications through watch channels.

For events, the reference endpoint is:

POST https://www.googleapis.com/calendar/v3/calendars/{calendarId}/events/watch

Google's watch method lets you register a webhook endpoint to receive notifications when event resources change. (Google for Developers)

Example structure:

channel = {
    "id": "your-unique-channel-id",
    "type": "web_hook",
    "address": "https://yourdomain.com/webhooks/google-calendar"
}

response = service.events().watch(
    calendarId="primary",
    body=channel
).execute()

Important caveat: Google's webhook notifications tell you that something changed, not the full changed event payload. In practice, your webhook handler usually triggers a follow-up read or incremental sync.

Step 11: Use sync tokens for incremental sync

If you are maintaining local state, full re-downloads are wasteful.

Google's incremental sync guide explains that you should store the nextSyncToken returned by a list request and then pass it back as syncToken on later requests to retrieve only changed resources. Google also notes that deleted entries are always included in incremental sync so clients can remove them locally. If a sync token expires, Google returns 410 GONE and you must perform a fresh full sync. (Google for Developers)

This is one of the main reasons a direct integration gets more complex in production than it looks in a quickstart.

Common production issues with direct Google Calendar integrations

The Google Calendar API is workable. The real challenge is everything around it.

In production, you usually end up owning:

  • OAuth client setup and redirect management
  • scope selection and reauthorization
  • secure storage of access and refresh tokens
  • automatic token refresh
  • webhook subscription creation and renewal
  • incremental sync logic with syncToken
  • handling 410 GONE and other edge cases
  • free/busy computation on top of raw busy blocks
  • recurring-event complexity
  • pagination, retries, and rate-limit handling

None of that is unusual. It is just the cost of a direct integration.

And if you later add Outlook, iCloud, Calendly, Teams, or Zoom, you repeat the same pattern with different auth models, object structures, webhook behavior, and availability rules.

When direct integration makes sense

A direct Google integration is a good choice when:

  • you only need Google Calendar
  • you want full control over implementation details
  • you have engineering time to own ongoing maintenance
  • calendar is a narrow feature, not a broad integration requirement

If that describes your product, direct integration can be a perfectly good decision.

How to do it with Unified instead

The calculus changes when Google Calendar is just one of several integrations you need to support.

Unified's Calendar and Meetings category is built for products that need real-time access to events, availability, recordings, and transcripts across multiple integrations, with one connection model and a normalized API surface. Across the broader platform, Unified is positioned around real-time execution against source APIs, no end-customer data stored at rest, and category-scoped unified APIs.

For Calendar and Meetings specifically, the working category model you assembled in this chat includes normalized access to:

  • calendar_event
  • busy
  • calendar_recording

along with broader scheduling, recordings, and meeting workflows across 27 Calendar & Meetings integrations. That means you are not building a Google Calendar integration in isolation. You are building one calendar integration layer that can also support other calendar and meeting integrations through the same product architecture.

The direct Google path vs Unified

With direct Google integration, you:

  1. create a Google Cloud project
  2. enable the API
  3. configure OAuth consent
  4. issue OAuth client credentials
  5. implement token storage and refresh
  6. build event reads and writes
  7. build free/busy logic
  8. build webhook lifecycle handling
  9. build incremental sync handling

With Unified, the model shifts:

  1. enable the Calendar and Meetings category
  2. authorize the customer through Unified Connect
  3. receive a connection_id
  4. use that connection_id for calendar API calls
  5. use the same approach later for Outlook, Calendly, Zoom, Teams, and other meeting integrations

That same connection-centric model is a documented part of Unified's broader platform positioning.

What gets easier with Unified

Unified does not eliminate product logic. You still own your app's scheduling rules, UI, and business workflows. But it does remove a large amount of per-integration work.

Instead of rebuilding Google-specific, Microsoft-specific, and Zoom-specific integration code, you get:

  • one authorization pattern
  • one connection identifier
  • one category-scoped API surface
  • normalized calendar and meeting objects
  • real-time data access patterns across integrations
  • a consistent webhook story, including native and virtual webhooks in the broader platform model where supported

Unified's positioning materials also emphasize usage-based pricing, no per-connection pricing, and a no-storage architecture, which matters for calendar and meeting data because those records often contain sensitive business context.

A practical way to frame the tradeoff

If your roadmap is:

  • Google Calendar only
  • simple event reads or writes
  • one-off internal tooling

direct integration is reasonable.

If your roadmap is:

  • Google Calendar now
  • Outlook next quarter
  • Calendly or Zoom after that
  • interview scheduling with ATS later
  • AI meeting summaries after that

then direct integration is usually the expensive path. You are not really building 'a Google Calendar integration.' You are starting a long series of integration projects.

That is where Unified is easier.

Instead of building integrations one by one, you integrate once at the category level and then support Google Calendar as part of a broader calendar and meetings architecture. That is exactly the product posture Unified's positioning and comparison materials describe: real-time, category-scoped integration infrastructure for SaaS teams building customer-facing features and AI workflows.

Key takeaways

  • Google Calendar direct integration is straightforward at the prototype level, but production complexity expands quickly because you own OAuth, token refresh, watch channels, incremental sync, and recurring-event edge cases. (Google for Developers)
  • Google supports the core operations you need: events.list, events.insert, events.patch, events.update, freebusy.query, and watch channels. (Google for Developers)
  • Direct integration makes sense when Google Calendar is the only integration you need.
  • Unified becomes the easier path when Google Calendar is one of several calendar or meeting integrations your product needs to support.
  • Unified's advantage is not just that it supports calendar. It is that it gives you a broader real-time Calendar and Meetings integration layer, with one connection model and no end-customer data stored at rest.

→ Start your 30-day free trial

→ Book a demo

All articles