# 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