---

name: google-calendar description: Manage Google Calendar events - create, list, update, and delete events. Use when you need to check schedules, create meetings, or automate calendar management. Requires OAuth2 setup.

Google Calendar API

Manage calendar events via Google Calendar API.

Setup (OAuth2)

1. Create project: https://console.cloud.google.com
2. Enable Calendar API: APIs & Services → Enable APIs → Google Calendar API
3. Create OAuth credentials: APIs & Services → Credentials → Create OAuth Client ID
4. Download JSON → save as ~/.config/google/credentials.json
5. Get refresh token using oauth2 flow (see below)

Quick Auth (using gcalcli)

Easiest setup using gcalcli:

pip install gcalcli
gcalcli init  # Opens browser for OAuth

Or use gcloud:

gcloud auth application-default login --scopes=https://www.googleapis.com/auth/calendar

API Basics

ACCESS_TOKEN=$(gcloud auth application-default print-access-token)

curl -s "https://www.googleapis.com/calendar/v3/users/me/calendarList" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" | jq '.items[] | {id, summary}'

List Calendars

curl -s "https://www.googleapis.com/calendar/v3/users/me/calendarList" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" | jq '.items[] | {id, summary}'

Primary calendar ID is usually your email or primary.

List Events

CALENDAR_ID="primary"
TIME_MIN=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
TIME_MAX=$(date -u -d "+7 days" +"%Y-%m-%dT%H:%M:%SZ")

curl -s "https://www.googleapis.com/calendar/v3/calendars/${CALENDAR_ID}/events?timeMin=${TIME_MIN}&timeMax=${TIME_MAX}&singleEvents=true&orderBy=startTime" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" | jq '.items[] | {summary, start: .start.dateTime, end: .end.dateTime}'

Get Today's Events

TODAY=$(date -u +"%Y-%m-%dT00:00:00Z")
TOMORROW=$(date -u -d "+1 day" +"%Y-%m-%dT00:00:00Z")

curl -s "https://www.googleapis.com/calendar/v3/calendars/primary/events?timeMin=${TODAY}&timeMax=${TOMORROW}&singleEvents=true&orderBy=startTime" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" | jq '.items[] | {summary, start: .start.dateTime}'

Create Event

curl -s -X POST "https://www.googleapis.com/calendar/v3/calendars/primary/events" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "summary": "Meeting Title",
    "description": "Meeting description",
    "start": {
      "dateTime": "2024-01-15T10:00:00",
      "timeZone": "Europe/Paris"
    },
    "end": {
      "dateTime": "2024-01-15T11:00:00",
      "timeZone": "Europe/Paris"
    }
  }' | jq '{id, summary, htmlLink}'

Create Event with Attendees

curl -s -X POST "https://www.googleapis.com/calendar/v3/calendars/primary/events?sendUpdates=all" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "summary": "Team Meeting",
    "start": {"dateTime": "2024-01-15T14:00:00", "timeZone": "Europe/Paris"},
    "end": {"dateTime": "2024-01-15T15:00:00", "timeZone": "Europe/Paris"},
    "attendees": [
      {"email": "person1@example.com"},
      {"email": "person2@example.com"}
    ],
    "conferenceData": {
      "createRequest": {"requestId": "meet-'$(date +%s)'"}
    }
  }' | jq

Add sendUpdates=all to send email invites.

Create All-Day Event

curl -s -X POST "https://www.googleapis.com/calendar/v3/calendars/primary/events" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "summary": "Holiday",
    "start": {"date": "2024-01-15"},
    "end": {"date": "2024-01-16"}
  }'

Use date (not dateTime) for all-day events.

Update Event

EVENT_ID="event_id_here"

curl -s -X PATCH "https://www.googleapis.com/calendar/v3/calendars/primary/events/${EVENT_ID}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "summary": "Updated Title",
    "description": "Updated description"
  }'

Delete Event

curl -s -X DELETE "https://www.googleapis.com/calendar/v3/calendars/primary/events/${EVENT_ID}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

Add Google Meet

curl -s -X POST "https://www.googleapis.com/calendar/v3/calendars/primary/events?conferenceDataVersion=1" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "summary": "Video Call",
    "start": {"dateTime": "2024-01-15T10:00:00", "timeZone": "Europe/Paris"},
    "end": {"dateTime": "2024-01-15T11:00:00", "timeZone": "Europe/Paris"},
    "conferenceData": {
      "createRequest": {
        "requestId": "'$(uuidgen)'",
        "conferenceSolutionKey": {"type": "hangoutsMeet"}
      }
    }
  }' | jq '.conferenceData.entryPoints[0].uri'

Free/Busy Query

curl -s -X POST "https://www.googleapis.com/calendar/v3/freeBusy" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "timeMin": "2024-01-15T00:00:00Z",
    "timeMax": "2024-01-15T23:59:59Z",
    "items": [{"id": "primary"}]
  }' | jq '.calendars.primary.busy'

Quick Add (Natural Language)

curl -s -X POST "https://www.googleapis.com/calendar/v3/calendars/primary/events/quickAdd?text=Lunch%20with%20John%20tomorrow%20at%20noon" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" | jq

Rate Limits

• 1,000,000 queries/day (default)
• 100 requests/100 seconds/user