/ 
Google-RestApi-2.1.0
River stage zero No dependents
/ Google::RestApi::CalendarApi3

NAME

Google::RestApi::CalendarApi3 - API to Google Calendar API V3.

SYNOPSIS

Basic Setup

use Google::RestApi;
use Google::RestApi::CalendarApi3;

# Create the REST API instance
my $rest_api = Google::RestApi->new(
  config_file => '/path/to/config.yaml',
);

# Create the Calendar API instance
my $cal_api = Google::RestApi::CalendarApi3->new(api => $rest_api);

Working with Calendars

# Create a new calendar
my $calendar = $cal_api->create_calendar(summary => 'My New Calendar');

# Get an existing calendar (e.g. primary)
my $primary = $cal_api->calendar(id => 'primary');
my $metadata = $primary->get();

# Update calendar metadata
$primary->update(summary => 'Updated Name', description => 'New description');

# List all calendars for the user
my @calendars = $cal_api->list_calendars();

Working with Events

my $calendar = $cal_api->calendar(id => 'primary');

# Create a timed event
my $event = $calendar->event()->create(
  summary => 'Team Meeting',
  start   => { dateTime => '2026-03-01T10:00:00-05:00' },
  end     => { dateTime => '2026-03-01T11:00:00-05:00' },
);

# Quick add an event using natural language
my $quick = $calendar->event()->quick_add(text => 'Lunch with Bob tomorrow at noon');

# List events
my @events = $calendar->events();

# Get/update/delete an event
my $details = $event->get();
$event->update(summary => 'Updated Meeting');
$event->delete();

Access Control (ACL)

# List ACL rules on a calendar
my @rules = $calendar->acl_rules();

# Create an ACL rule
my $acl = $calendar->acl()->create(
  role       => 'reader',
  scope_type => 'user',
  scope_value => 'user@example.com',
);

# Delete an ACL rule
$acl->delete();

Calendar List, Colors, and Settings

# Calendar list (user's view of calendars)
my $cl = $cal_api->calendar_list(id => 'primary');
my $info = $cl->get();

# Get available colors
my $colors = $cal_api->colors();
my $all = $colors->get();

# Get a setting
my $setting = $cal_api->settings(id => 'timezone');
my $value = $setting->value();

DESCRIPTION

Google::RestApi::CalendarApi3 provides a Perl interface to the Google Calendar API V3. It enables calendar management including:

  • Calendar CRUD operations (create, get, update, delete)

  • Event management (create, get, update, delete, quick add)

  • Access control (ACL) management

  • Calendar list management (user's view of calendars)

  • Colors and settings (read-only)

  • Free/busy queries

It is assumed that you are familiar with the Google Calendar API: https://developers.google.com/calendar/api/v3/reference

Architecture

The API uses a hierarchical object model where child objects delegate API calls to their parent:

CalendarApi3 (top-level)
  |-- calendar(id => ...)       -> Calendar
  |     |-- event(id => ...)    -> Event
  |     |-- acl(id => ...)      -> Acl
  |-- calendar_list(id => ...)  -> CalendarList
  |-- colors()                  -> Colors
  |-- settings(id => ...)       -> Settings

Each object provides CRUD operations appropriate to its resource type.

NAVIGATION

SUBROUTINES

new(%args)

Creates a new CalendarApi3 instance.

my $cal_api = Google::RestApi::CalendarApi3->new(api => $rest_api);

%args consists of:

  • api Google::RestApi: Required. A configured RestApi instance.

  • endpoint <string>: Optional. Override the default Calendar API endpoint.

api(%args)

Low-level method to make API calls. You would not normally call this directly unless making a Google API call not currently supported by this framework.

%args consists of:

  • uri <string>: Path segments to append to the Calendar endpoint.

  • %args: Additional arguments passed to Google::RestApi's api() (content, params, method, etc).

Returns the response hash from the Google API.

calendar(%args)

Returns a Calendar object for the given calendar ID.

my $cal = $cal_api->calendar(id => 'primary');
my $cal = $cal_api->calendar(id => 'user@gmail.com');

%args consists of:

  • id <string>: Required. The calendar ID (e.g. 'primary' or an email address).

calendar_list(%args)

Returns a CalendarList object for managing the user's view of calendars.

my $cl = $cal_api->calendar_list(id => 'primary');

%args consists of:

  • id <string>: Optional. The calendar ID. Required for get/update/delete.

colors()

Returns a Colors object for querying available calendar and event colors.

my $colors = $cal_api->colors();
my $all = $colors->get();

settings(%args)

Returns a Settings object for querying user settings.

my $setting = $cal_api->settings(id => 'timezone');
my $value = $setting->value();

%args consists of:

  • id <string>: Optional. The setting ID. Required for get/value.

create_calendar(%args)

Creates a new calendar.

my $cal = $cal_api->create_calendar(summary => 'My Calendar');

%args consists of:

  • summary <string>: Required. The name for the calendar.

Returns a Calendar object for the created calendar.

list_calendars(%args)

Lists all calendars visible to the user.

my @calendars = $cal_api->list_calendars();
my @calendars = $cal_api->list_calendars(max_pages => 2);

max_pages limits the number of pages fetched (default 0 = unlimited). Supports page_callback, see "PAGE CALLBACKS" in Google::RestApi.

Returns a list of calendar hashrefs with id and summary.

freebusy(%args)

Queries free/busy information for a set of calendars.

my $result = $cal_api->freebusy(
  time_min => '2026-03-01T00:00:00Z',
  time_max => '2026-03-02T00:00:00Z',
  items    => [{ id => 'primary' }],
);

%args consists of:

  • time_min <string>: Required. Start of the time range (RFC3339).

  • time_max <string>: Required. End of the time range (RFC3339).

  • items <arrayref>: Required. List of calendar IDs to query.

rest_api()

Returns the underlying Google::RestApi instance.

SEE ALSO

AUTHORS

  • Robin Murray mvsjes@cpan.org

COPYRIGHT

Copyright (c) 2019-2026 Robin Murray. All rights reserved.

This program is free software; you may redistribute it and/or modify it under the same terms as Perl itself.