In Google Calendar, users can specify a working location so people know their location when sending invitations to an event. This feature is only available on primary calendars, and to some Google Calendar users. For more details, go to Turn working location on or off for users.
Read working locations
You can read user working locations in the
Events
resource of the Calendar API.
To list working location events, use the
events.list
method, specifying
['workingLocation']
in the
eventTypes
field. Then,
in the returned Event
objects, inspect that the
eventType
field has the value
'workingLocation'
, and refer to the
workingLocationProperties
field for details about the working location set by the user in
Google Calendar.
Create and update working locations
To create a working location event, you create an instance of the
Events
resource with the following
required fields:
- Set
eventType
to'workingLocation'
. - Include the
workingLocationProperties
field. - Set the
visibility
field topublic
. - Set the
transparency
field to'transparent'
. Set the event's
start
andend
fields to be either:- A timed event (with start and end times specified);
- An all-day event (with start and end dates specified) which spans exactly one day.
All-day working location events cannot span multiple days, but timed events can.
If you update the working location event, the event must maintain these required fields.
The following fields are optional but recommended for the best user experience
when inserting an
officeLocation
:
workingLocationProperties.officeLocation.buildingId
: This should match abuildingId
in the organization's resources database. This helps users benefit from all Calendar features, for example room suggestions.workingLocationProperties.officeLocation.label
: This is the label that's shown on the Calendar Web and mobile clients. You can fetch building IDs and building labels using theresources.buildings.list
method.
If you set more than one working location event on a given day, Calendar only displays one of the events according to the rules below.
Creating and updating working location events through the batch endpoints isn't supported.
How to show overlapping working location events
A user can have multiple working location events on their calendar at the same time which overlap, meaning that any given time could have multiple working locations set for it. In circumstances when only a single location can be shown to the user, they should be shown that location consistently across multiple applications. When doing this, use the following guidelines to choose which event to show:
- Timed events take precedence over all-day events.
- Single events take precedence over recurring events and their exceptions.
- Events which start later take precedence over events which start earlier.
- Events with shorter durations take precedence over those with longer durations.
- More recently created events take precedence over events that were created earlier.
- Partially overlapping events should be shown as two different events each with their own working location.
Google Apps Script code sample
Google Apps Script is a JavaScript-based cloud scripting language that lets you build business applications that integrate with Google Workspace. Scripts are developed in a browser-based code editor, and they are stored and run on Google's servers. See also Google Apps Script quickstart to start using Apps Script to send requests to the Google Calendar API.
The following instructions describe how to read working locations using the Google Calendar API as an advanced service in Google Apps Script. For a complete list of Google Calendar API resources and methods, see the reference documentation.
Create the script
- Create a script by going to script.google.com/create.
Enable the Google Calendar API
- On the left pane next to Services, click Add a service .
- Select Google Calendar API and click Add.
- After enabled, the API appears on the left pane. Available methods and classes in the API can be listed using the Calendar keyword in the editor.
(Optional) Update the Google Cloud project
Each Google Apps Script project has an associated Google Cloud project. Your script can use the default project that Google Apps Script automatically creates. If you want to use a custom Google Cloud project, take the following steps to update the project associated with your script.
- On the left side of the editor, click Project Settings .
- Under Google Cloud Platform (GCP) Project, click Change project.
- Enter the project number of the Google Cloud project that's in the Developer Preview Program, and click Set project.
- On the left side, select Editor to navigate back to the code editor.
Add code to the script
The following code sample shows how to create, read, and list working location events on your primary calendar.
Paste the following into the script editor.
/** * Creates a working location event. * See https://developers.google.com/calendar/api/v3/reference/events/insert */ function createWorkingLocationEvent() { const calendarId = 'primary'; const requiredArgs = { start: { date: "2023-06-01" }, end: { date: "2023-06-02" }, eventType: "workingLocation", visibility: "public", transparency: "transparent", workingLocationProperties: { type: 'customLocation', customLocation: { label: "a custom location" } } } try { var event = Calendar.Events.insert(requiredArgs, calendarId); console.log('%s: %s', event.start.date, parseWorkingLocation(event)); } catch (exception) { console.log(exception.message); } } /** * Reads the working location event with the given eventId. * See https://developers.google.com/calendar/api/v3/reference/events/get */ function readWorkingLocationEvent() { const calendarId = 'primary'; // Replace with a valid eventId. const eventId = "sample-event-id"; try { const event = Calendar.Events.get(calendarId, eventId); console.log('%s: %s', event.start.date, parseWorkingLocation(event)); } catch (exception) { console.log(exception.message); } } /** * Lists working location events for given dates. * See https://developers.google.com/calendar/api/v3/reference/events/list */ function listWorkingLocationEvents() { const calendarId = 'primary' // Query parameters for the list request. const optionalArgs = { eventTypes: ['workingLocation'], showDeleted: false, singleEvents: true, timeMax: '2023-04-01T00:00:00+01:00', timeMin: '2023-03-27T00:00:00+01:00', } try { var response = Calendar.Events.list(calendarId, optionalArgs ); response.items.forEach(event => console.log('%s: %s', event.start.date, parseWorkingLocation(event))); } catch (exception) { console.log(exception.message); } } /** * Parses working location properties of an event into a string. * See https://developers.google.com/calendar/api/v3/reference/events#resource */ function parseWorkingLocation(event) { if(event.eventType != "workingLocation") { throw new Error("'" + event.summary +"' is not a working location event."); } const workingLocation = event.workingLocationProperties; if (workingLocation) { if (workingLocation.type === 'homeOffice') { return 'Home'; } if (workingLocation.type === 'officeLocation') { return workingLocation.officeLocation.label; } if (workingLocation.type === 'customLocation') { return workingLocation.customLocation.label; } } return 'No Location'; }
Run the code sample
- Above the code editor, select the function to run from the drop-down menu, and click Run.
- In the first execution, it prompts you to authorize access. Review and allow Apps Script to access your calendar.
- You can inspect the results of the script execution in the Execution Log that appears at the bottom of the window.