> For the complete documentation index, see [llms.txt](https://docs.coupler.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coupler.io/sources/category/project-management/google-calendar.md).

# Google Calendar

Export Google Calendar events and availability to Google Sheets, Excel, or BigQuery automatically via Coupler.io.

Google Calendar is a time-management and scheduling tool that lets you create events, manage multiple calendars, and track availability. Connecting it to Coupler.io lets you export your calendar data automatically — no manual downloads or CSV exports needed.

## Why connect Google Calendar to Coupler.io?

* **Automate reporting** — pull events and availability data into Google Sheets, Excel, or BigQuery on a schedule
* **Visualize your calendar** — send data to Looker Studio or Power BI to build time-tracking and capacity dashboards
* **Analyze with AI** — route calendar data to ChatGPT, Claude, Gemini, or other AI destinations to summarize schedules, identify patterns, or generate insights
* **Combine data sources** — use Append or Join transformations to merge calendar data with CRM, project, or HR data for richer analysis

## Prerequisites

* A Google account with access to the calendars you want to export
* Read access to any shared or team calendars you plan to pull from

## Quick start

{% hint style="success" %}
If you want to pull events from multiple calendars (for example, a team calendar and a personal one), set up separate sources in the same data flow and use the **Append** transformation to combine them into one dataset.
{% endhint %}

## How to connect

{% stepper %}
{% step %}
**Create a new data flow and add Google Calendar as a source.** In Coupler.io, click **Add data flow**, then search for and select **Google Calendar**.
{% endstep %}

{% step %}
**Authorize your Google account.** Click **Sign in with Google** and grant Coupler.io permission to read your calendar data. You'll be redirected back automatically after authorizing.
{% endstep %}

{% step %}
**Choose a data entity.** Select what you want to export: **List of my calendars**, **List of events**, or **Report: busy time for user**. If you choose Events or the Free/Busy report, you'll also need to select which calendar(s) to pull from and set a date range using the date pickers.
{% endstep %}

{% step %}
**Choose a destination.** Select where you want your data to land — Google Sheets, Excel, BigQuery, Looker Studio, or an AI destination like ChatGPT, Claude, or Gemini.
{% endstep %}

{% step %}
**Run your data flow.** Click **Run** to execute a manual run and confirm your data loads correctly before setting up a schedule.
{% endstep %}
{% endstepper %}

## Google Calendar data overview

Google Calendar exposes three types of data in Coupler.io: your calendar list, individual events, and a free/busy availability report. The most commonly used entity is **List of events**, which returns detailed information about each event in a calendar during the date range you specify.

## Entities overview

| Entity                     | Best for                                                   |
| -------------------------- | ---------------------------------------------------------- |
| List of my calendars       | Auditing all calendars in an account, getting calendar IDs |
| List of events             | Time tracking, meeting analysis, schedule reporting        |
| Report: busy time for user | Capacity planning, availability analysis                   |

## Available fields

#### Event fields

| Field                   | Description                                        |
| ----------------------- | -------------------------------------------------- |
| `id`                    | Unique event identifier                            |
| `summary`               | Event title/name                                   |
| `description`           | Event description or notes                         |
| `location`              | Location or conference link                        |
| `status`                | Event status (confirmed, tentative, cancelled)     |
| `start.dateTime`        | Event start time (with timezone)                   |
| `end.dateTime`          | Event end time (with timezone)                     |
| `start.date`            | Start date for all-day events                      |
| `end.date`              | End date for all-day events                        |
| `created`               | Timestamp when event was created                   |
| `updated`               | Timestamp of last update                           |
| `organizer.email`       | Email of the event organizer                       |
| `organizer.displayName` | Display name of the organizer                      |
| `attendees`             | List of attendees and their RSVP status            |
| `recurrence`            | Recurrence rule (for recurring events)             |
| `colorId`               | Color label assigned to the event                  |
| `htmlLink`              | Direct link to the event in Google Calendar        |
| `transparency`          | Whether the event blocks time (opaque/transparent) |
| `visibility`            | Public, private, or default visibility             |

#### Calendar fields

| Field         | Description                                          |
| ------------- | ---------------------------------------------------- |
| `id`          | Calendar ID (used when configuring event extraction) |
| `summary`     | Calendar name                                        |
| `description` | Calendar description                                 |
| `timeZone`    | Timezone set for the calendar                        |
| `accessRole`  | Your access level (owner, writer, reader)            |
| `primary`     | Whether this is your primary calendar                |

#### Free/Busy report fields

| Field      | Description            |
| ---------- | ---------------------- |
| `calendar` | Calendar ID            |
| `start`    | Start of a busy period |
| `end`      | End of a busy period   |

## Common field combinations

* **Time tracking**: `summary`, `start.dateTime`, `end.dateTime`, `colorId` — calculate event duration and categorize by color label
* **Meeting analysis**: `summary`, `attendees`, `organizer.email`, `start.dateTime` — analyze who organizes meetings and who attends
* **Capacity planning**: Use the Free/Busy report across multiple calendars to identify availability windows
* **Schedule reporting**: `summary`, `location`, `start.dateTime`, `status` — filter for confirmed events and track what's on the agenda

## Use cases by role

{% tabs %}
{% tab title="Operations" %}

* Export team calendars to Google Sheets to track meeting load and identify over-scheduled periods
* Use the Free/Busy report across multiple calendars to plan resourcing and avoid scheduling conflicts
* Append events from multiple team calendars into a single dataset for a unified team schedule view
  {% endtab %}

{% tab title="Finance & HR" %}

* Pull events with `colorId` labels to categorize time by project or client and feed into billing reports
* Export recurring events to calculate average meeting hours per week for capacity cost analysis
* Join calendar data with employee records in BigQuery to correlate meeting time with productivity metrics
  {% endtab %}

{% tab title="Marketers" %}

* Export campaign-related calendar events to Looker Studio to overlay marketing activities with performance data
* Send calendar data to ChatGPT or Gemini to generate weekly schedule summaries or content planning insights
* Track promotional event schedules by pulling events filtered by a specific calendar dedicated to campaigns
  {% endtab %}
  {% endtabs %}

## Platform-specific notes

* The **earliest date you can pull events from is 4 weeks ago** — this is a platform limit, not a Coupler.io restriction
* **Recurring events** may show the original creation date rather than the actual occurrence date within your selected range — use date filters carefully and verify results
* The `summary` field contains the event title; there is no separate "name" column
* Times are returned with timezone information in `start.dateTime` — if you see times offset by an hour, check for daylight saving time differences between the calendar timezone and your destination
* The `attendees` field returns structured data; use advanced filters or transformation formulas to extract specific attendee information
* To split structured fields like `summary` (when it contains delimited data), use regex formulas in Coupler.io's transformation step

## Google Calendar common issues

### Connection issues

<details>

<summary>Data flow runs forever with no output</summary>

If your data flow hangs indefinitely without returning data, try the following:

1. Cancel the run and check that you've selected a valid calendar in the source settings
2. Confirm your Google account authorization is still active — disconnect and reconnect your account if needed
3. Narrow your date range and try running again
4. If the issue persists, contact Coupler.io support with your data flow ID

</details>

<details>

<summary>Error when connecting to a shared or team calendar</summary>

Make sure the Google account you authorized has at least **Reader** access to the calendar. If you're pulling from a shared calendar (e.g., a team or resource calendar), the account owner may need to grant you explicit access in Google Calendar settings before Coupler.io can read it.

</details>

### Missing data

<details>

<summary>Future events are not showing up</summary>

If only past or today's events appear, check your **End date** setting. The end date must be set to a future date to include upcoming events. Use the date picker to set it as far forward as needed — Coupler.io supports future date ranges.

</details>

<details>

<summary>Events older than 4 weeks are missing</summary>

This is a hard limit from the Google Calendar API. **You cannot pull events from more than 4 weeks ago** in a single run.

As a workaround, use the **Append** mode in your destination settings so each scheduled run adds new rows rather than overwriting existing ones. This lets you build a historical archive over time.

</details>

<details>

<summary>Recurring events show the wrong date</summary>

Recurring events can show the original creation date instead of the actual occurrence date within your selected date range. This is a known behavior. To work around it, use the **Updated since** parameter to filter for recently updated events, or verify results against your calendar directly. This is one of the most commonly reported issues — if your use case depends on accurate recurring event dates, test carefully before relying on this data.

</details>

<details>

<summary>Blank or empty rows in the export</summary>

Blank rows typically appear when some events have missing fields (such as no description or location). To remove them, apply an advanced filter in Coupler.io to exclude rows where a required field — like `summary` — is empty.

</details>

<details>

<summary>Fewer rows than expected (import seems truncated)</summary>

If you're on a free plan, row limits apply and your data may be truncated. Try narrowing your date range to reduce the dataset size. If you need more rows, consider upgrading your plan or splitting the export into multiple date windows using separate data flows.

</details>

### Permission errors

<details>

<summary>"Got an unexpected keyword argument" error with advanced filters</summary>

This error can occur when using certain field names (like `attendees`) in advanced filters. Not all event fields support direct filtering through the advanced filter interface. If you need to filter on attendee data, export the full dataset and apply filtering in your destination (e.g., using Google Sheets formulas or BigQuery queries).

</details>

### Data discrepancies

<details>

<summary>Times are off by one hour compared to Google Calendar</summary>

This is usually caused by a **daylight saving time (DST) mismatch**. The `start.dateTime` field includes timezone information, but conversions in your destination may not account for DST correctly. Check that your destination's timezone settings match your calendar's timezone. If using Google Sheets, verify any `DATETIME` conversion formulas explicitly handle the correct UTC offset for your region.

</details>

<details>

<summary>Event data in Coupler.io doesn't match what's in Google Calendar</summary>

If you see fewer events than expected, confirm:

* The correct calendar is selected as the source
* Your date range covers the period you're checking
* The events were created by (or shared with) the authorized Google account
* Cancelled events may be filtered out by default — check if the missing events have a cancelled status in Google Calendar

</details>

## Google Calendar FAQ

<details>

<summary>Can I export event names as a column?</summary>

Yes. Event names (titles) are exported under the **`summary`** column — not "name" or "title". When you pull the List of events entity, you'll see a `summary` field for each row containing the event title.

</details>

<details>

<summary>Will editing the spreadsheet change my Google Calendar?</summary>

No. Coupler.io is a one-way data export. Editing your Google Sheets, Excel, or any other destination will never affect the events in your Google Calendar.

</details>

<details>

<summary>Why can I only pull data from the last 4 weeks?</summary>

This is a limitation of the Google Calendar API, not Coupler.io. The earliest available date for event extraction is 4 weeks ago. To maintain a longer history, enable **Append mode** in your destination settings so each run adds new data on top of previously exported rows rather than overwriting them.

</details>

<details>

<summary>Can I pull future calendar events?</summary>

Yes. Set your **End date** to a future date using the date picker. Coupler.io supports future date ranges, so you can pull upcoming events as far ahead as you need.

</details>

<details>

<summary>Why do recurring events show the wrong date?</summary>

Recurring events often return the original creation date rather than the actual occurrence date within your selected date range. This is a known behavior of the Google Calendar API. Double-check recurring event dates against your calendar, and use the **Updated since** filter to catch recently modified events if needed.

</details>

<details>

<summary>Why are times off by one hour from what I see in Google Calendar?</summary>

This is usually a daylight saving time (DST) issue. The `start.dateTime` field includes timezone information, but if your destination applies a static UTC offset, it won't account for DST shifts. Check your timezone settings in your destination and adjust any date conversion formulas to use the correct local offset.

</details>

<details>

<summary>Can I pull data from multiple calendars at once?</summary>

For the **Free/Busy report**, yes — you can specify multiple calendars in one source. For **Events**, each source is limited to one calendar. To combine events from multiple calendars, add multiple sources to the same data flow and use the **Append** transformation to merge them into one dataset.

</details>

<details>

<summary>How do I filter events to only those with attendees?</summary>

The `attendees` field doesn't support direct filtering through the advanced filter interface — using it there will throw an error. Instead, export all events and filter on the `attendees` column in your destination using a formula (e.g., in Google Sheets) or a query (e.g., in BigQuery).

</details>

<details>

<summary>Can I use Google Calendar data in AI tools like ChatGPT or Claude?</summary>

Yes. Coupler.io supports AI destinations including **ChatGPT, Claude, Gemini, Perplexity, Cursor, and OpenClaw**. You can route your calendar data directly to these tools to generate schedule summaries, identify patterns, or answer questions about your events.

</details>

<details>

<summary>How do I categorize events by type using color labels?</summary>

Each event has a `colorId` field that corresponds to the color label set in Google Calendar. You can use this field in a calculated column or formula to assign categories — for example, mapping `colorId=3` to "Client Meeting" or `colorId=4` to "Focus Time".

</details>

{% hint style="info" %}
For a full list of available fields and what they contain, see the [Data Overview](#google-calendar-data-overview) article. For setup tips and avoiding common mistakes, check [Best Practices](https://docs.coupler.io/sources/category/project-management/google-calendar/best-practices.md). Running into an error? See [Common Issues](#google-calendar-common-issues).
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.coupler.io/sources/category/project-management/google-calendar.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
