Skip to main content

Actions

The ballerinax/googleapis.gcalendar package exposes the following clients:

ClientPurpose
ClientProvides full access to Google Calendar API v3: calendars, events, ACL rules, calendar list, free/busy, and colors.

Client

Provides full access to Google Calendar API v3: calendars, events, ACL rules, calendar list, free/busy, and colors.

Configuration

FieldTypeDefaultDescription
authhttp:BearerTokenConfig|OAuth2RefreshTokenGrantConfigRequiredOAuth 2.0 refresh token configuration or a bearer token for authentication.
httpVersionhttp:HttpVersionHTTP_2_0HTTP protocol version to use.
timeoutdecimal30Request timeout in seconds.
retryConfighttp:RetryConfig()Retry configuration for failed requests.
secureSockethttp:ClientSecureSocket()SSL/TLS configuration.
proxyhttp:ProxyConfig()Proxy server configuration.
validationbooleantrueEnable constraint validation on request/response records.
laxDataBindingbooleantrueAllow unknown fields in response payloads without returning an error.

Initializing the client

import ballerinax/googleapis.gcalendar as gcalendar;

configurable string clientId = ?;
configurable string clientSecret = ?;
configurable string refreshToken = ?;

gcalendar:Client calendarClient = check new ({
auth: {
clientId: clientId,
clientSecret: clientSecret,
refreshToken: refreshToken
}
});

Operations

Calendar management

Create a calendar

Creates a new secondary calendar in the authenticated user's Google account.

Parameters:

NameTypeRequiredDescription
payloadgcalendar:CalendarYesCalendar resource containing at minimum the summary (title) field.

Returns: gcalendar:Calendar|error

Sample code:

gcalendar:Calendar newCalendar = check calendarClient->/calendars.post({
summary: "Software Project"
});

Sample response:

{
"kind": "calendar#calendar",
"id": "[email protected]",
"summary": "Software Project",
"timeZone": "UTC",
"conferenceProperties": {"allowedConferenceSolutionTypes": ["hangoutsMeet"]}
}
Get a calendar

Returns metadata for the calendar with the specified ID.

Parameters:

NameTypeRequiredDescription
calendarIdstringYesCalendar identifier. Use "primary" for the authenticated user's primary calendar.

Returns: gcalendar:Calendar|error

Sample code:

gcalendar:Calendar calendar = check calendarClient->/calendars/["[email protected]"];

Sample response:

{
"kind": "calendar#calendar",
"id": "[email protected]",
"summary": "Software Project",
"timeZone": "America/New_York"
}
Update a calendar

Replaces the calendar resource with the provided payload (full update).

Parameters:

NameTypeRequiredDescription
calendarIdstringYesCalendar identifier.
payloadgcalendar:CalendarYesUpdated calendar resource.

Returns: gcalendar:Calendar|error

Sample code:

gcalendar:Calendar updated = check calendarClient->/calendars/["[email protected]"].put({
summary: "Software Project – Q1",
timeZone: "America/New_York"
});

Sample response:

{
"kind": "calendar#calendar",
"id": "[email protected]",
"summary": "Software Project – Q1",
"timeZone": "America/New_York"
}
Patch a calendar

Updates selected fields of a calendar (partial update: unset fields are unchanged).

Parameters:

NameTypeRequiredDescription
calendarIdstringYesCalendar identifier.
payloadgcalendar:CalendarYesPartial calendar resource with only the fields to update.

Returns: gcalendar:Calendar|error

Sample code:

gcalendar:Calendar patched = check calendarClient->/calendars/["[email protected]"].patch({
description: "Tracking milestones for the Q1 software project."
});

Sample response:

{
"kind": "calendar#calendar",
"id": "[email protected]",
"summary": "Software Project – Q1",
"description": "Tracking milestones for the Q1 software project.",
"timeZone": "America/New_York"
}
Delete a calendar

Permanently deletes a secondary calendar. The primary calendar cannot be deleted.

Parameters:

NameTypeRequiredDescription
calendarIdstringYesCalendar identifier of the secondary calendar to delete.

Returns: error?

Sample code:

check calendarClient->/calendars/["[email protected]"].delete();
Clear a calendar

Deletes all events from a primary calendar. Only applicable to primary calendars.

Parameters:

NameTypeRequiredDescription
calendarIdstringYesCalendar identifier. Must be "primary" for the authenticated user's primary calendar.

Returns: error?

Sample code:

check calendarClient->/calendars/["primary"]/clear.post({});

Event management

List events on a calendar

Returns events on the specified calendar, with optional filters for time range, search query, and sync tokens.

Parameters:

NameTypeRequiredDescription
calendarIdstringYesCalendar identifier. Use "primary" for the authenticated user's primary calendar.
queries*CalendarEventsListQueriesNoOptional query parameters including timeMin, timeMax, q (search text), singleEvents, orderBy, and maxResults.

Returns: gcalendar:Events|error

Sample code:

gcalendar:Events events = check calendarClient->/calendars/["primary"]/events(
timeMin = "2024-01-01T00:00:00Z",
timeMax = "2024-01-31T23:59:59Z",
singleEvents = true,
orderBy = "startTime"
);

Sample response:

{
"kind": "calendar#events",
"summary": "primary",
"items": [
{
"id": "eventabc123",
"summary": "Team Meeting",
"start": {"dateTime": "2024-01-15T10:00:00Z"},
"end": {"dateTime": "2024-01-15T11:00:00Z"},
"status": "confirmed"
}
]
}
Create an event

Creates a new event on the specified calendar.

Parameters:

NameTypeRequiredDescription
calendarIdstringYesCalendar identifier.
payloadgcalendar:EventYesEvent resource. At minimum, start and end must be specified.
queries*CalendarEventsInsertQueriesNoOptional query parameters including sendUpdates (all, externalOnly, none) and conferenceDataVersion.

Returns: gcalendar:Event|error

Sample code:

gcalendar:Event newEvent = check calendarClient->/calendars/["primary"]/events.post({
summary: "Code Review",
description: "Review sprint 3 pull requests",
location: "Conference Room A",
start: {
dateTime: "2024-01-15T10:00:00Z",
timeZone: "UTC"
},
end: {
dateTime: "2024-01-15T11:00:00Z",
timeZone: "UTC"
},
attendees: [
{email: "[email protected]"},
{email: "[email protected]"}
],
reminders: {
useDefault: false,
overrides: [
{method: "popup", minutes: 15},
{method: "email", minutes: 30}
]
}
});

Sample response:

{
"kind": "calendar#event",
"id": "eventabc123",
"summary": "Code Review",
"description": "Review sprint 3 pull requests",
"location": "Conference Room A",
"status": "confirmed",
"htmlLink": "https://www.google.com/calendar/event?eid=...",
"created": "2024-01-10T08:00:00.000Z",
"start": {"dateTime": "2024-01-15T10:00:00Z", "timeZone": "UTC"},
"end": {"dateTime": "2024-01-15T11:00:00Z", "timeZone": "UTC"}
}
Get an event

Returns the event with the specified ID from the given calendar.

Parameters:

NameTypeRequiredDescription
calendarIdstringYesCalendar identifier.
eventIdstringYesEvent identifier.

Returns: gcalendar:Event|error

Sample code:

gcalendar:Event event = check calendarClient->/calendars/["primary"]/events/["eventabc123"];

Sample response:

{
"kind": "calendar#event",
"id": "eventabc123",
"summary": "Code Review",
"status": "confirmed",
"start": {"dateTime": "2024-01-15T10:00:00Z", "timeZone": "UTC"},
"end": {"dateTime": "2024-01-15T11:00:00Z", "timeZone": "UTC"},
"attendees": [
{"email": "[email protected]", "responseStatus": "accepted"},
{"email": "[email protected]", "responseStatus": "needsAction"}
]
}
Update an event

Replaces an existing event with the provided resource (full update).

Parameters:

NameTypeRequiredDescription
calendarIdstringYesCalendar identifier.
eventIdstringYesEvent identifier.
payloadgcalendar:EventYesUpdated event resource.
queries*CalendarEventsUpdateQueriesNoOptional query parameters including sendUpdates.

Returns: gcalendar:Event|error

Sample code:

gcalendar:Event updatedEvent = check calendarClient->/calendars/["primary"]/events/["eventabc123"].put({
summary: "Design Review",
start: {dateTime: "2024-01-16T14:00:00Z", timeZone: "UTC"},
end: {dateTime: "2024-01-16T15:00:00Z", timeZone: "UTC"}
});

Sample response:

{
"kind": "calendar#event",
"id": "eventabc123",
"summary": "Design Review",
"status": "confirmed",
"start": {"dateTime": "2024-01-16T14:00:00Z", "timeZone": "UTC"},
"end": {"dateTime": "2024-01-16T15:00:00Z", "timeZone": "UTC"}
}
Patch an event

Updates selected fields of an event (partial update: unspecified fields are unchanged).

Parameters:

NameTypeRequiredDescription
calendarIdstringYesCalendar identifier.
eventIdstringYesEvent identifier.
payloadgcalendar:EventYesPartial event resource with only the fields to update.

Returns: gcalendar:Event|error

Sample code:

gcalendar:Event patched = check calendarClient->/calendars/["primary"]/events/["eventabc123"].patch({
summary: "Team Meeting – Weekly Sync",
location: "Zoom"
});

Sample response:

{
"kind": "calendar#event",
"id": "eventabc123",
"summary": "Team Meeting – Weekly Sync",
"location": "Zoom",
"status": "confirmed",
"start": {"dateTime": "2024-01-15T10:00:00Z", "timeZone": "UTC"},
"end": {"dateTime": "2024-01-15T11:00:00Z", "timeZone": "UTC"}
}
Delete an event

Deletes an event from the specified calendar.

Parameters:

NameTypeRequiredDescription
calendarIdstringYesCalendar identifier.
eventIdstringYesEvent identifier.
queries*CalendarEventsDeleteQueriesNoOptional query parameters including sendUpdates.

Returns: error?

Sample code:

check calendarClient->/calendars/["primary"]/events/["eventabc123"].delete();
Quick-add an event

Creates an event based on a simple text string using natural language parsing.

Parameters:

NameTypeRequiredDescription
calendarIdstringYesCalendar identifier.
queries*CalendarEventsQuickAddQueriesYesMust include text: a free-text string describing the event (e.g., "Lunch with Alice tomorrow at noon").

Returns: gcalendar:Event|error

Sample code:

gcalendar:Event quickEvent = check calendarClient->/calendars/["primary"]/events/quickAdd(
text = "Project Beta Release on January 31 at 9am"
);

Sample response:

{
"kind": "calendar#event",
"id": "quickeventxyz",
"summary": "Project Beta Release",
"status": "confirmed",
"start": {"dateTime": "2024-01-31T09:00:00Z"},
"end": {"dateTime": "2024-01-31T10:00:00Z"}
}
Import an event

Imports an event using an iCalendar-format payload. Used to add a private copy of an existing event to a calendar.

Parameters:

NameTypeRequiredDescription
calendarIdstringYesCalendar identifier.
payloadgcalendar:EventYesEvent resource. Must include iCalUID and start/end fields.

Returns: gcalendar:Event|error

Sample code:

gcalendar:Event imported = check calendarClient->/calendars/["primary"]/events/'import({
iCalUID: "[email protected]",
summary: "Imported Conference",
start: {dateTime: "2024-02-10T09:00:00Z", timeZone: "UTC"},
end: {dateTime: "2024-02-10T17:00:00Z", timeZone: "UTC"}
});

Sample response:

{
"kind": "calendar#event",
"id": "importedeventabc",
"iCalUID": "[email protected]",
"summary": "Imported Conference",
"status": "confirmed",
"start": {"dateTime": "2024-02-10T09:00:00Z", "timeZone": "UTC"},
"end": {"dateTime": "2024-02-10T17:00:00Z", "timeZone": "UTC"}
}
List instances of a recurring event

Returns instances of the specified recurring event, with optional time-range filters.

Parameters:

NameTypeRequiredDescription
calendarIdstringYesCalendar identifier.
eventIdstringYesRecurring event identifier.
queries*CalendarEventsInstancesQueriesNoOptional query parameters including timeMin, timeMax, maxResults, and pageToken.

Returns: gcalendar:Events|error

Sample code:

gcalendar:Events instances = check calendarClient->/calendars/["primary"]/events/["recurringEventId"]/instances(
timeMin = "2024-01-01T00:00:00Z",
timeMax = "2024-03-31T23:59:59Z"
);

Sample response:

{
"kind": "calendar#events",
"items": [
{
"id": "recurringEventId_20240108",
"summary": "Weekly Standup",
"start": {"dateTime": "2024-01-08T09:00:00Z"},
"end": {"dateTime": "2024-01-08T09:30:00Z"},
"recurringEventId": "recurringEventId"
},
{
"id": "recurringEventId_20240115",
"summary": "Weekly Standup",
"start": {"dateTime": "2024-01-15T09:00:00Z"},
"end": {"dateTime": "2024-01-15T09:30:00Z"},
"recurringEventId": "recurringEventId"
}
]
}
Move an event to another calendar

Moves an event to a different calendar: the event is removed from the source calendar and added to the destination.

Parameters:

NameTypeRequiredDescription
calendarIdstringYesSource calendar identifier.
eventIdstringYesEvent identifier.
queries*CalendarEventsMoveQueriesYesMust include destination: the calendar ID to move the event to. Optionally include sendUpdates.

Returns: gcalendar:Event|error

Sample code:

gcalendar:Event movedEvent = check calendarClient->/calendars/["primary"]/events/["eventabc123"]/move(
destination = "[email protected]"
);

Sample response:

{
"kind": "calendar#event",
"id": "eventabc123",
"summary": "Code Review",
"status": "confirmed",
"organizer": {"email": "[email protected]", "self": true},
"start": {"dateTime": "2024-01-15T10:00:00Z", "timeZone": "UTC"},
"end": {"dateTime": "2024-01-15T11:00:00Z", "timeZone": "UTC"}
}

ACL management

List ACL rules for a calendar

Returns the rules in the access control list for the specified calendar.

Parameters:

NameTypeRequiredDescription
calendarIdstringYesCalendar identifier.
queries*CalendarAclListQueriesNoOptional query parameters including maxResults, pageToken, syncToken, and showDeleted.

Returns: gcalendar:Acl|error

Sample code:

gcalendar:Acl aclList = check calendarClient->/calendars/["[email protected]"]/acl();

Sample response:

{
"kind": "calendar#acl",
"items": [
{
"kind": "calendar#aclRule",
"id": "user:[email protected]",
"scope": {"type": "user", "value": "[email protected]"},
"role": "owner"
},
{
"kind": "calendar#aclRule",
"id": "user:[email protected]",
"scope": {"type": "user", "value": "[email protected]"},
"role": "reader"
}
]
}
Create an ACL rule

Creates an access control rule granting a user or group access to the specified calendar.

Parameters:

NameTypeRequiredDescription
calendarIdstringYesCalendar identifier.
payloadgcalendar:AclRuleYesACL rule resource specifying scope (type + value) and role (reader, writer, or owner).
queries*CalendarAclInsertQueriesNoOptional query parameters including sendNotifications.

Returns: gcalendar:AclRule|error

Sample code:

gcalendar:AclRule rule = check calendarClient->/calendars/["[email protected]"]/acl.post({
scope: {
'type: "user",
value: "[email protected]"
},
role: "reader"
});

Sample response:

{
"kind": "calendar#aclRule",
"id": "user:[email protected]",
"scope": {"type": "user", "value": "[email protected]"},
"role": "reader"
}
Get an ACL rule

Returns the access control rule with the specified ID for the given calendar.

Parameters:

NameTypeRequiredDescription
calendarIdstringYesCalendar identifier.
ruleIdstringYesACL rule identifier.

Returns: gcalendar:AclRule|error

Sample code:

gcalendar:AclRule aclRule = check calendarClient->/calendars/["[email protected]"]/acl/["user:[email protected]"];

Sample response:

{
"kind": "calendar#aclRule",
"id": "user:[email protected]",
"scope": {"type": "user", "value": "[email protected]"},
"role": "reader"
}
Update an ACL rule

Replaces an ACL rule with the provided resource (full update).

Parameters:

NameTypeRequiredDescription
calendarIdstringYesCalendar identifier.
ruleIdstringYesACL rule identifier.
payloadgcalendar:AclRuleYesUpdated ACL rule resource.

Returns: gcalendar:AclRule|error

Sample code:

gcalendar:AclRule updated = check calendarClient->/calendars/["[email protected]"]/acl/["user:[email protected]"].put({
scope: {
'type: "user",
value: "[email protected]"
},
role: "writer"
});

Sample response:

{
"kind": "calendar#aclRule",
"id": "user:[email protected]",
"scope": {"type": "user", "value": "[email protected]"},
"role": "writer"
}
Patch an ACL rule

Updates selected fields of an ACL rule (partial update).

Parameters:

NameTypeRequiredDescription
calendarIdstringYesCalendar identifier.
ruleIdstringYesACL rule identifier.
payloadgcalendar:AclRuleYesPartial ACL rule resource with only the fields to update.

Returns: gcalendar:AclRule|error

Sample code:

gcalendar:AclRule patched = check calendarClient->/calendars/["[email protected]"]/acl/["user:[email protected]"].patch({
role: "owner"
});

Sample response:

{
"kind": "calendar#aclRule",
"id": "user:[email protected]",
"scope": {"type": "user", "value": "[email protected]"},
"role": "owner"
}
Delete an ACL rule

Deletes an ACL rule, revoking the associated user's or group's access to the calendar.

Parameters:

NameTypeRequiredDescription
calendarIdstringYesCalendar identifier.
ruleIdstringYesACL rule identifier.

Returns: error?

Sample code:

check calendarClient->/calendars/["[email protected]"]/acl/["user:[email protected]"].delete();

Calendar list

List calendars on the user's calendar list

Returns all calendars present on the authenticated user's calendar list.

Parameters:

NameTypeRequiredDescription
queries*CalendarCalendarListListQueriesNoOptional query parameters including minAccessRole, showHidden, showDeleted, maxResults, and pageToken.

Returns: gcalendar:CalendarList|error

Sample code:

gcalendar:CalendarList calList = check calendarClient->/users/me/calendarList();

Sample response:

{
"kind": "calendar#calendarList",
"items": [
{
"kind": "calendar#calendarListEntry",
"id": "[email protected]",
"summary": "[email protected]",
"primary": true,
"accessRole": "owner"
},
{
"kind": "calendar#calendarListEntry",
"id": "[email protected]",
"summary": "Software Project",
"accessRole": "owner"
}
]
}
Add a calendar to the user's calendar list

Inserts an existing calendar into the authenticated user's calendar list so it appears in their Google Calendar UI.

Parameters:

NameTypeRequiredDescription
payloadgcalendar:CalendarListEntryYesCalendarListEntry resource. Must include id (the calendar identifier to subscribe to).
queries*CalendarCalendarListInsertQueriesNoOptional query parameters including colorRgbFormat.

Returns: gcalendar:CalendarListEntry|error

Sample code:

gcalendar:CalendarListEntry entry = check calendarClient->/users/me/calendarList.post({
id: "[email protected]"
});

Sample response:

{
"kind": "calendar#calendarListEntry",
"id": "[email protected]",
"summary": "Software Project",
"accessRole": "reader",
"selected": true
}
Get a calendar from the user's calendar list

Returns a specific calendar from the authenticated user's calendar list.

Parameters:

NameTypeRequiredDescription
calendarIdstringYesCalendar identifier.

Returns: gcalendar:CalendarListEntry|error

Sample code:

gcalendar:CalendarListEntry entry = check calendarClient->/users/me/calendarList/["[email protected]"];

Sample response:

{
"kind": "calendar#calendarListEntry",
"id": "[email protected]",
"summary": "Software Project",
"timeZone": "America/New_York",
"accessRole": "owner",
"selected": true
}
Update a calendar list entry

Replaces a calendar list entry with the provided resource (full update). Used to update user-specific calendar display settings.

Parameters:

NameTypeRequiredDescription
calendarIdstringYesCalendar identifier.
payloadgcalendar:CalendarListEntryYesUpdated CalendarListEntry resource.

Returns: gcalendar:CalendarListEntry|error

Sample code:

gcalendar:CalendarListEntry updated = check calendarClient->/users/me/calendarList/["[email protected]"].put({
id: "[email protected]",
colorId: "9",
selected: true
});

Sample response:

{
"kind": "calendar#calendarListEntry",
"id": "[email protected]",
"summary": "Software Project",
"colorId": "9",
"selected": true,
"accessRole": "owner"
}
Patch a calendar list entry

Updates selected display properties of a calendar list entry (partial update).

Parameters:

NameTypeRequiredDescription
calendarIdstringYesCalendar identifier.
payloadgcalendar:CalendarListEntryYesPartial CalendarListEntry resource with only the fields to update.

Returns: gcalendar:CalendarListEntry|error

Sample code:

gcalendar:CalendarListEntry patched = check calendarClient->/users/me/calendarList/["[email protected]"].patch({
summaryOverride: "Project – Q1"
});

Sample response:

{
"kind": "calendar#calendarListEntry",
"id": "[email protected]",
"summary": "Software Project",
"summaryOverride": "Project – Q1",
"accessRole": "owner"
}
Remove a calendar from the user's calendar list

Removes the specified calendar from the authenticated user's calendar list (does not delete the calendar itself).

Parameters:

NameTypeRequiredDescription
calendarIdstringYesCalendar identifier to remove from the list.

Returns: error?

Sample code:

check calendarClient->/users/me/calendarList/["[email protected]"].delete();

Free/Busy

Query free/busy availability

Returns free/busy information for a set of calendars and groups within a specified time range.

Parameters:

NameTypeRequiredDescription
payloadgcalendar:FreeBusyRequestYesFreeBusyRequest resource specifying timeMin, timeMax, timeZone, and the list of items (calendars/groups to query).

Returns: gcalendar:FreeBusyResponse|error

Sample code:

gcalendar:FreeBusyResponse availability = check calendarClient->/freeBusy.post({
timeMin: "2024-01-15T09:00:00Z",
timeMax: "2024-01-15T17:00:00Z",
timeZone: "UTC",
items: [
{id: "[email protected]"},
{id: "[email protected]"}
]
});

Sample response:

{
"kind": "calendar#freeBusy",
"timeMin": "2024-01-15T09:00:00Z",
"timeMax": "2024-01-15T17:00:00Z",
"calendars": {
"[email protected]": {
"busy": [
{"start": "2024-01-15T10:00:00Z", "end": "2024-01-15T11:00:00Z"}
]
},
"[email protected]": {
"busy": []
}
}
}

Colors

Get color definitions

Returns the color definitions available for calendar and event color coding.

Returns: gcalendar:Colors|error

Sample code:

gcalendar:Colors colors = check calendarClient->/colors();

Sample response:

{
"kind": "calendar#colors",
"updated": "2012-02-14T00:00:00.000Z",
"calendar": {
"1": {"background": "#ac725e", "foreground": "#1d1d1d"},
"2": {"background": "#d06b64", "foreground": "#1d1d1d"},
"9": {"background": "#5f6368", "foreground": "#ffffff"}
},
"event": {
"1": {"background": "#a4bdfc", "foreground": "#1d1d1d"},
"2": {"background": "#7ae7bf", "foreground": "#1d1d1d"},
"11": {"background": "#dc2127", "foreground": "#ffffff"}
}
}