Query Google Calendar Free/Busy Status

Overview

This reference file describes the getFreeBusy() function from Get Free/Busy Status, which queries busy time slots across one or more Google Calendars for availability checking and conflict detection. Useful for finding available meeting times or checking if someone is free during a specific time range.

Required Parameters

The following parameters are required to use the function:

1. timeMin (string)

   • Start datetime in RFC3339 format with timezone offset
   • Example: '2025-12-15T09:00:00-08:00' or '2025-12-15T17:00:00Z'
   • Important: Fetch the user's timezone first (per SKILL.md guidelines) and use it to construct the datetime

2. timeMax (string)

   • End datetime in RFC3339 format with timezone offset
   • Example: '2025-12-15T17:00:00-08:00'
   • Must be after timeMin

3. calendarToken (string)

   • Your Google Calendar API authentication token
   • Must have calendar.freebusy scope permission

Optional Parameters

4. calendars (array, optional)
   • Array of calendar IDs to check
   • Default: ['primary'] (checks only the user's primary calendar)
   • Example: ['primary', 'work@company.com']

How to Run the Code

Basic Usage

IMPORTANT: Do NOT generate or define the getFreeBusy function. The function already exists in Get Free/Busy Status and must be imported.

To execute this function, use the following code:

import { getFreeBusy } from 'Get Free/Busy Status';

const result = await getFreeBusy(
  '2025-12-15T09:00:00-08:00',      // timeMin
  '2025-12-15T17:00:00-08:00',      // timeMax
  process.env.GOOGLE_CALENDAR_TOKEN // calendarToken
);

console.log('Free/busy result:', result);
// Output: { timeMin: '...', timeMax: '...', calendars: {...}, allFree: true/false, queriedAt: '...' }

With Multiple Calendars

Remember: Always import the function from the existing script file. Do not generate it.

Check availability across multiple calendars:

import { getFreeBusy } from 'Get Free/Busy Status';

const result = await getFreeBusy(
  '2025-12-16T08:00:00-05:00',
  '2025-12-16T18:00:00-05:00',
  process.env.GOOGLE_CALENDAR_TOKEN,
  ['primary', 'work@company.com']   // calendars array (optional)
);

console.log(`All calendars free: ${result.allFree}`);
console.log(JSON.stringify(result, null, 2));

Return Value

The function returns a Promise that resolves to an object with the following structure:

{
  "timeMin": "2025-12-15T09:00:00-08:00",
  "timeMax": "2025-12-15T17:00:00-08:00",
  "calendars": {
    "primary": {
      "busySlots": [
        {
          "start": "2025-12-15T10:00:00-08:00",
          "end": "2025-12-15T11:00:00-08:00"
        }
      ],
      "busyCount": 1,
      "errors": []
    }
  },
  "allFree": false,
  "queriedAt": "2025-12-02T18:30:00.000Z"
}

Key Fields:

• allFree: Boolean indicating if all calendars are free during the time range
• busySlots: Array of busy time periods with start and end times
• busyCount: Number of busy periods (0 means free)
• errors: Any errors for specific calendars

How It Works

The function queries Google Calendar's free/busy API:

1. Validates Input: Ensures timeMin and timeMax are provided
2. Queries API: POSTs to https://www.googleapis.com/calendar/v3/freeBusy with time range and calendar list
3. Processes Response: Extracts busy slots for each calendar and calculates busyCount
4. Returns Results: Returns object with allFree flag, busy time periods, and calendar statuses