Manage working locations for Google Calendar users

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 to public.
Set the transparency field to'transparent'.
Set the event's start and end 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 a buildingId 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 the resources.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.

primary is a keyword to access the primary calendar of the currently signed-in user. To retrieve events on a different calendar, set the calendarId parameter to an email address. This lets you read working location events on the calendars of other users you have at minimum free/busy access to. Secondary calendars can't have working location events.

/**
 * 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.