Manage working locations

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 to some Google Calendar users. For more details, go to Turn working location on or off for users.

Read user 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.

Note: The ability to add or update working locations is still in development. Working hours cannot currently be managed programmatically.

Google Apps Script code sample

Google Apps Script is a JavaScript-based cloud scripting language that lets you build simple 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

  1. Create a script by going to script.google.com/create.

Enable the Google Calendar API

  1. On the left pane next to Services, click Add a service .
  2. Select Google Calendar API and click Add.
  3. Once 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.

Update the Google Cloud project

The ability to read working locations is only available to Google Cloud projects in the Developer Preview Program. You need to update the Google Cloud project number of the Apps Script project to retrieve working location events.

  1. On the left side of the editor, click Project Settings .
  2. Under Google Cloud Platform (GCP) Project, click Change project.
  3. Enter the project number of the Google Cloud project that's in the Developer Preview Program, and click Set project.
  4. On the left side, select Editor to navigate back to the code editor.

Run the script to read working locations

The following code sample shows how to read working location events on your calendar.

  1. Paste the following into the script editor.

    /**
     * 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);
      }
    }
    
    /**
     * 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);
      }
    }
    
    /**
     * 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.homeOffice) {
          return 'Home';
        }
        if (workingLocation.officeLocation) {
          return workingLocation.officeLocation.label;
        }
        if (workingLocation.customLocation) {
          return workingLocation.customLocation.label;
        }
      }
      return 'No Location';
    }
    
  2. Above the code editor, select the function to run from the dropdown menu, and click Run.

  3. In the first execution, it prompts you to authorize access. Review and allow Apps Script to access your calendar.

  4. You can inspect the results of the script execution in the Execution Log that appears at the bottom of the window.