The Calendar API free-busy query returns occupied time intervals for requested calendars. It should not be treated as general permission to read event titles, descriptions, or guest lists. Design scheduling features around the least information they actually need.
Specify the requested interval
Use freebusy.query with the intended calendar identifiers and explicit timeMin and timeMax boundaries in the documented RFC3339 format. Review the response time-zone option; Google’s reference says the default is UTC when none is specified.
Review limits and individual errors
The reference documents calendar expansion up to fifty calendars and group expansion up to one hundred identifiers. Check the applicable request settings and returned errors rather than assuming an arbitrarily large group resolves successfully in one query.
Inspect errors for each calendar and group, not only the overall HTTP status. An inaccessible or failed calendar must remain unknown; it should not be interpreted as having no busy periods.
Verify the scheduling interpretation
Check returned busy intervals against a controlled authorized calendar. Google’s reference defines the start as inclusive and the end as exclusive. Keep those boundaries clear when comparing adjacent appointments. A period outside returned busy blocks is a result within this query’s access and time scope, not a guarantee that a person is willing or available to meet. Working hours, travel, and other unqueried calendars can still matter. Choose a supported narrow availability scope where appropriate and review the method’s current authorization requirements. The completed feature should report known availability information honestly without converting missing data into free time or requesting event-detail access solely for a simple conflict check.
References
- Freebusy: query | Google Calendar | Google for Developers
- Choose Google Calendar API scopes | Google for Developers
Reviewed against the linked official product guidance on November 4, 2026. Features, limits, screen labels, and access can vary by account, platform, region, and organization policy.