What we do
Tools
Industries
Department
How we workLet's talk →
Home/Google Calendar/Google Calendar API Integration
Google Calendar

Google Calendar API Integration: Credentials, Push Notifications and a Sync That Holds Up

The Google Calendar API lets your code read, create, update and delete events and calendars, and ask Google to ping a URL when a calendar changes. The first call is quick. The harder part is keeping an outside system in step with calendars people edit all day, without missed changes or duplicates.

Before the first request

Enable it: create or pick a Google Cloud project, then enable the Google Calendar API in it.

Google Cloud console APIs & Services Library Google Calendar API

Make a credential: an OAuth client for apps acting on a person's behalf, a service account for server jobs, or an API key for public calendars only.

Use a client library: Google publishes official ones, including google-api-python-client for Python, plus Node.js, Java, Go, .NET and PHP.

Which credential fits what you are building

Most first errors come from the wrong one of these.

You are building Use Watch out for
A page that shows a public calendar, like holidays or class times An API key It only reads calendars that are public. Anything private, or any write, needs OAuth or a service account.
An app that customers connect their own Google Calendar to OAuth 2.0 with user consent Calendar scopes are sensitive, so a public app needs Google's verification. Ask for the narrowest scope that does the job, such as events only rather than full calendar access.
A back-office job inside your own Google Workspace A service account with domain-wide delegation A Workspace admin has to grant the delegation and list the scopes. Without it, a service account can't send invitations to attendees.
A sync to one shared business calendar A service account the calendar is shared with Share the calendar with the service account's email and the right permission. It sees nothing it hasn't been given.

Google Calendar API problems that show up after launch

Every user has to reconnect after a week

How you'll know: Refresh tokens stop working seven days after people sign in.

Fix: Your OAuth consent screen is external and still in Testing, and Google expires refresh tokens for those apps after 7 days. Publish the app, and get it verified if it uses sensitive scopes.

One recurring meeting, hundreds of rows

How you'll know: Your system stores each occurrence of a weekly event, and editing the series breaks them all.

Fix: Decide which you need. singleEvents=true expands a series into instances, which suits display. For a sync, store the recurring event and its exceptions instead.

All-day events off by a day

How you'll know: A day off booked for Friday shows up on Thursday in your system.

Fix: All-day events use start.date, not start.dateTime, and have no time zone. Don't convert them through UTC.

Quota errors in a burst

How you'll know: 403 usage-limit or 429 errors when a backfill or a busy morning hits many calendars at once.

Fix: Back off exponentially and retry, spread the work out, and rely on sync tokens instead of re-reading whole calendars. Limits apply per project and per user, and you can see them in the Cloud console.

Knowing when a calendar changed, without polling

A push notification only says something changed. A sync token tells you what.

  1. 1

    Run a full sync and keep the token

    List the calendar's events once, page by page. The last page returns a nextSyncToken. Store it next to the calendar ID.

    Watch for: use the same query parameters on every later request. Sync tokens don't work with most filters, and a disallowed one returns a 400.

  2. 2

    Open a watch channel

    Call watch on the calendar's events with a unique channel id and your HTTPS address. Google needs a valid certificate on that address; self-signed ones are refused. Each calendar needs its own channel.

  3. 3

    Treat the notification as a nudge

    Google's POST has no body. The headers carry the channel ID, the resource ID and X-Goog-Resource-State: sync when the channel opens, exists when something changed. Return a 200 and queue the calendar for a sync.

  4. 4

    Fetch the changes with the token

    List events with your stored syncToken. You get everything changed since, deletions included, and a new token to store. That's how a moved or cancelled booking reaches your system.

    Watch for: a 410 Gone means Google invalidated the token. Wipe your stored copy of that calendar and run a full sync again.

  5. 5

    Renew before it expires

    Channels end, and nothing renews them for you. Open a new channel with a new id before the old one expires (they can overlap), then stop the old one with channels/stop, passing its id and resourceId.

What the Calendar API doesn't cover

The API's resources are calendars, events, access rules, settings, colors, free/busy and notification channels. There's no resource for appointment schedules, Google's booking pages. You set those up by hand in Calendar, and the bookings they take arrive as ordinary events, which your sync can read like any other.

Calendar also handles its own reminders and booking confirmations, so there's no reason to rebuild those. What it can't do is tell your job system, CRM or billing that a booking exists. n-frames builds that connection: the watch channels, the sync tokens, the renewals, and the mapping from a calendar event to a job, a visit or an invoice. Where a business runs many booking pages, we can also set them up through browser automation, because the API has no endpoint for it.

Questions people ask

Do I need to enable the Calendar API in Google Cloud before using it?

Yes. Every request belongs to a Google Cloud project, and the Calendar API has to be enabled in that project before calls succeed. Then you create the credential, an OAuth client, a service account or an API key. It's a one-time step per project.

What's a Google Calendar API key used for, versus OAuth?

An API key identifies your project and can only read public calendars. Reading someone's private events, or creating or changing anything, needs OAuth consent from that person or a Workspace service account with delegated access.

Can the Calendar API trigger something the instant an event changes?

Close to it. Register an HTTPS address with watch and Google notifies it within moments of a change. The notification has no event data, so your code then lists events with its sync token to see what changed.

Does the Calendar API let me set up an Appointment Schedules booking page?

No. Appointment schedules are set up in the Calendar interface. The API only sees the bookings afterwards, as events on the calendar. For businesses with many booking pages, n-frames sets them up with browser automation instead.

Does Google offer a Python library for the Calendar API?

Yes. google-api-python-client is Google's official client, used with google-auth and google-auth-oauthlib for credentials. Google's Python quickstart walks through the first request.

Why is the Google Calendar push notification empty?

By design. Google sends headers only, naming the channel and the resource that changed. You fetch the actual changes yourself, normally with a sync token, so the notification can never carry stale data.

How long does a Google Calendar watch channel last?

Until its expiration time, which is the shorter of what you ask for and Google's own limit. Google doesn't renew channels automatically, so a working integration opens a fresh channel before the old one ends.

Let's talk

Tell us the one thing your team does manually that eats up time. We read every message and reply within a day.