Manage focus time, out of office, and working location events

This page explains how to use the Google Calendar API to create events that show the status of Google Calendar users. Status events describe where users are or what they're doing, including whether they're in focus time, out of office, or working from a certain location.

In Google Calendar, users can create focus time, out of office and working location events to indicate their custom status and location. These features are only available on primary calendars, and to some Google Calendar users.

For more details, go to Use focus time in Google Calendar and Turn working location on or off for users.

Read and list Calendar status events

You can read and list Calendar status events in the Events resource of the Calendar API.

To read a status event, use the events.get method, specifying the eventId of the event.

To list status events, use the events.list method, specifying one or more of the following values in the eventTypes field:

'focusTime'
'outOfOffice'
'workingLocation'

Then, in the returned Event objects, inspect that the eventType field has the requested value, and refer to the corresponding field for details about the status created by the user in Google Calendar:

Subscribe to changes on status events

You can subscribe to changes on status events in the Events resource of the Calendar API.

Use the events.watch method, specifying the calendarId of the Calendar to subscribe to and one or more of the following values in the eventTypes field:

'focusTime'
'outOfOffice'
'workingLocation'

Create and update Calendar status events

To create a status event, you create an instance of the Events resource using the events.insert method, setting the required fields for the event type.

If you update the status event using events.update method, the event must maintain the required fields.

Create focus time

To create a focus time event:

Set eventType to 'focusTime'.
Include the focusTimeProperties field.
Set the transparency field to 'opaque'.
Set the event's start and end fields to be a timed event (with start and end times specified).
Focus times cannot be all-day events.

For feature details, go to Use focus time in Google Calendar

Create out of office

To create an out of office event:

Set eventType to 'outOfOffice'.
Include the outOfOfficeProperties field.
Set the transparency field to 'opaque'.
Set the event's start and end fields to be a timed event (with start and end times specified).
Out of office events cannot be all-day events.

For feature details, go to Show when you're out of office

Create working location

To create a working location event:

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.

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.

Creating and updating working location events through the batch endpoints isn't supported.

For feature details, go to Set your working hours & location and Turn working location on or off for users

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.

Create status events in Google Apps Script

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 manage status events 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 and set up the script

Create a script by going to script.google.com/create.
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 status events on your primary calendar.

Paste the following into the code editor.

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

/** Creates a focus time event. */
function createFocusTime() {
  const event = {
    start: { dateTime: '2023-11-14T10:00:00+01:00' },
    end: { dateTime: '2023-11-14T12:00:00+01:00' },
    eventType: 'focusTime',
    focusTimeProperties: {
      chatStatus: 'doNotDisturb',
      autoDeclineMode: 'declineOnlyNewConflictingInvitations',
      declineMessage: 'Declined because I am in focus time.',
    }
  }
  createEvent(event);
}

/** Creates an out of office event. */
function createOutOfOffice() {
  const event = {
    start: { dateTime: '2023-11-15T10:00:00+01:00' },
    end: { dateTime: '2023-11-15T18:00:00+01:00' },
    eventType: 'outOfOffice',
    outOfOfficeProperties: {
      autoDeclineMode: 'declineOnlyNewConflictingInvitations',
      declineMessage: 'Declined because I am on vacation.',
    }
  }
  createEvent(event);
}

/** Creates a working location event. */
function createWorkingLocation() {
  const event = {
    start: { date: "2023-06-01" },
    end: { date: "2023-06-02" },
    eventType: "workingLocation",
    visibility: "public",
    transparency: "transparent",
    workingLocationProperties: {
      type: 'customLocation',
      customLocation: { label: "a custom location" },
    }
  }
  createEvent(event);
}

/**
  * Creates a Calendar event.
  * See https://developers.google.com/calendar/api/v3/reference/events/insert
  */
function createEvent(event) {
  const calendarId = 'primary';

  try {
    var response = Calendar.Events.insert(event, calendarId);
    var event = (response.eventType === 'workingLocation') ? parseWorkingLocation(response) : response;
    console.log(event);
  } catch (exception) {
    console.log(exception.message);
  }
}

/**
  * Reads the event with the given eventId.
  * See https://developers.google.com/calendar/api/v3/reference/events/get
  */
function readEvent() {
  const calendarId = 'primary';

  // Replace with a valid eventId.
  const eventId = "sample-event-id";

  try {
    var response = Calendar.Events.get(calendarId, eventId);
    var event = (response.eventType === 'workingLocation') ? parseWorkingLocation(response) : response;
    console.log(event);
  } catch (exception) {
    console.log(exception.message);
  }
}

/** Lists focus time events. */
function listFocusTimes() {
  listEvents('focusTime');
}

/** Lists out of office events. */
function listOutOfOffices() {
  listEvents('outOfOffice');
}

/** Lists working location events. */
function listWorkingLocations() {
  listEvents('workingLocation');
}

/**
  * Lists events with the given event type.
  * See https://developers.google.com/calendar/api/v3/reference/events/list
  */
function listEvents(eventType = 'default') {
  const calendarId = 'primary'

  // Query parameters for the list request.
  const optionalArgs = {
    eventTypes: [eventType],
    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(eventType === 'workingLocation' ? parseWorkingLocation(event) : 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.");
  }

  var location = 'No Location';
  const workingLocation = event.workingLocationProperties;
  if (workingLocation) {
    if (workingLocation.type === 'homeOffice') {
      location = 'Home';
    }
    if (workingLocation.type === 'officeLocation') {
      location = workingLocation.officeLocation.label;
    }
    if (workingLocation.type === 'customLocation') {
      location = workingLocation.customLocation.label;
    }
  }
  return `${event.start.date}: ${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.