Package google.home.graph.v1

Index

HomeGraphApiService

Google HomeGraph API service. The HomeGraph service provides support for storing and querying first-party and third-party devices, rooms and structures, and the relationships among them and their state in the home. It stores entities and their relationships in the home.

DeleteAgentUser

rpc DeleteAgentUser(DeleteAgentUserRequest) returns (Empty)

Unlinks an agent user from Google. As a result, all data related to this user will be deleted.

Here is how the agent user is created in Google:

  1. When a user opens their Google Home App, they can begin linking a 3p partner.
  2. User is guided through the OAuth process.
  3. After entering the 3p credentials, Google gets the 3p OAuth token and uses it to make a Sync call to the 3p partner and gets back all of the user's data, including agent_user_id and devices.
  4. Google creates the agent user and stores a mapping from the agent_user_id -> Google ID mapping. Google also stores all of the user's devices under that Google ID.

The mapping from agent_user_id to Google ID is many to many, since one Google user can have multiple 3p accounts, and multiple Google users can map to one agent_user_id (e.g., a husband and wife share one Nest account username/password).

The third-party user's identity is passed in as agent_user_id. The agent is identified by the JWT signed by the partner's service account.

Note: Special characters (except "/") in agent_user_id must be URL-encoded.

Authorization Scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/homegraph

For more information, see the OAuth 2.0 Overview.

Query

rpc Query(QueryRequest) returns (QueryResponse)

Gets the device states for the devices in QueryRequest. The third-party user's identity is passed in as agent_user_id. The agent is identified by the JWT signed by the third-party partner's service account.

Authorization Scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/homegraph

For more information, see the OAuth 2.0 Overview.

ReportState

rpc ReportState(ReportStateRequest) returns (ReportStateResponse)

Reports device state. Called by an agent when the device state of a third-party user changes.

Authorization Scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/homegraph

For more information, see the OAuth 2.0 Overview.

ReportStateAndNotification

rpc ReportStateAndNotification(ReportStateAndNotificationRequest) returns (ReportStateAndNotificationResponse)

Reports device state and optionally sends device notifications. Called by an agent when the device state of a third-party changes or the agent wants to send a notification about the device. See Implement Report State for more information. This method updates a predefined set of states for a device, which all devices have according to their prescribed traits (for example, a light will have the OnOff trait that reports the state on as a boolean value). A new state may not be created and an INVALID_ARGUMENT code will be thrown if so. It also optionally takes in a list of Notifications that may be created, which are associated to this state change.

The third-party user's identity is passed in as agent_user_id. The agent is identified by the JWT signed by the partner's service account.

Authorization Scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/homegraph

For more information, see the OAuth 2.0 Overview.

RequestSyncDevices

rpc RequestSyncDevices(RequestSyncDevicesRequest) returns (RequestSyncDevicesResponse)

Requests a SYNC call from Google to a 3p partner's home control agent for a user.

The third-party user's identity is passed in as agent_user_id (see RequestSyncDevicesRequest) and forwarded back to the agent. The agent is identified by the API key or JWT signed by the partner's service account.

Authorization Scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/homegraph

For more information, see the OAuth 2.0 Overview.

Sync

rpc Sync(SyncRequest) returns (SyncResponse)

Gets all the devices associated with the given third-party user. The third-party user's identity is passed in as agent_user_id. The agent is identified by the JWT signed by the third-party partner's service account.

Authorization Scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/homegraph

For more information, see the OAuth 2.0 Overview.

AgentDeviceId

Third-party partner's device ID for one device.

Fields
id

string

Third-party partner's device ID.

DeleteAgentUserRequest

Request type for the DeleteAgentUser call.

Fields
request_id

string

Request ID used for debugging.

agent_user_id

string

Required. Third-party user ID.

Device

Third-party partner's device definition.

Fields
id

string

Third-party partner's device ID.

type

string

Hardware type of the device (e.g. light, outlet, etc).

traits[]

string

Traits supported by the device.

name

DeviceNames

Name of the device given by the third party. This includes names given to the device via third party device manufacturer's app, model names for the device, etc.

will_report_state

bool

Indicates whether the state of this device is being reported to Google through ReportStateAndNotification call.

room_hint

string

If the third-party partner's cloud configuration includes placing devices in rooms, the name of the room can be provided here.

structure_hint

string

As in roomHint, for structures that users set up in the partner's system.

device_info

DeviceInfo

Device manufacturer, model, hardware version, and software version.

attributes

Struct

Attributes for the traits supported by the device.

custom_data

string

Custom JSON data provided by the manufacturer and attached to QUERY and EXECUTE requests in AoG.

DeviceInfo

Device information.

Fields
manufacturer

string

Device manufacturer.

model

string

Device model.

hw_version

string

Device hardware version.

sw_version

string

Device software version.

DeviceNames

Different names for the device.

Fields
name

string

Primary name of the device, generally provided by the user.

nicknames[]

string

Additional names provided by the user for the device.

default_names[]

string

List of names provided by the partner rather than the user, often manufacturer names, SKUs, etc.

DeviceState

Deprecated. Use states and notifications instead.

Fields
id

string

Required. Foreign device ID.

traits

Struct

Required.

QueryRequest

Request type for the Query call. This should be the same format as the Actions on Google action.devices.QUERY request with the exception of the extra agent_user_id and no intent and customData fields.

Fields
request_id

string

Request ID used for debugging.

agent_user_id

string

Required. Third-party user ID.

inputs[]

QueryRequestInput

Required. Inputs containing third-party partner's device IDs for which to get the device states.

QueryRequestInput

Device ID inputs to QueryRequest.

Fields
payload

QueryRequestPayload

Payload containing third-party partner's device IDs.

QueryRequestPayload

Payload containing device IDs.

Fields
devices[]

AgentDeviceId

Third-party partner's device IDs for which to get the device states.

QueryResponse

Response type for the Query call. This should follow the same format as the Actions on Google action.devices.QUERY response.

Example

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "devices": {
      "123": {
        "on": true,
        "online": true
      },
      "456": {
        "on": true,
        "online": true,
        "brightness": 80,
        "color": {
          "name": "cerulean",
          "spectrumRGB": 31655
        }
      }
    }
  }
}
Fields
request_id

string

Request ID used for debugging. Copied from the request.

payload

QueryResponsePayload

Device states for the devices given in the request.

QueryResponsePayload

Payload containing device states information.

Fields
devices

map<string, Struct>

States of the devices. Map of third-party device ID to struct of device states.

ReportStateAndNotificationDevice

The states and notifications specific to a device.

Fields
states

Struct

States of devices to update.

notifications

Struct

Notifications metadata for devices.

ReportStateAndNotificationRequest

Request type for the ReportStateAndNotification call. It may include States, Notifications, or both. This request uses globally unique flattened state names instead of namespaces based on traits to align with the existing QUERY and EXECUTE APIs implemented by 90+ Smart Home partners. States and notifications are defined per device_id (for example, "123" and "456" in the following example).

Example

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "agent_user_id": "1234",
  "payload": {
    "devices": {
      "states": {
        "123": {
          "on": true
        },
        "456": {
          "on": true,
          "brightness": 10
        }
      },
    }
  }
}
Fields
request_id

string

Request ID used for debugging.

event_id

string

Unique identifier per event (for example, a doorbell press).

agent_user_id

string

Required. Third-party user ID.

follow_up_token

string

Token to maintain state in the follow up notification response.

payload

StateAndNotificationPayload

State of devices to update and notification metadata for devices. For example, if a user turns a light on manually, a state update should be sent so that the information is always the current status of the device. Notifications are independent from the state and its piece of the payload should contain everything necessary to notify the user. Although it may be related to a state change, it does not need to be. For example, if a device can turn on/off and change temperature, the states reported would include both "on" and "70 degrees" but the 3p may choose not to send any notification for that, or to only say that the "the room is heating up", keeping state and notification independent.

ReportStateAndNotificationResponse

Response type for the ReportStateAndNotification call.

Fields
request_id

string

Request ID copied from ReportStateAndNotificationRequest.

ReportStateRequest

Request type for ReportState call.

Deprecated. Use ReportStateAndNotificationRequest instead.

Fields
request_id

string

Request ID used for debugging.

agent_user_id

string

Required. Third-party user ID.

devices[]

DeviceState

Required. State of devices to update.

ReportStateResponse

Response type for ReportState call.

Deprecated. Use ReportStateAndNotificationResponse instead.

Fields
request_id

string

Request ID copied from ReportStateRequest.

RequestSyncDevicesRequest

Request type for the RequestSyncDevices call.

Fields
agent_user_id

string

Required. Third-party user ID issued by agent's third-party identity provider.

async

bool

Optional. If set, the request will be added to a queue and a response will be returned immediately. The queue allows for de-duplication of simultaneous requests.

RequestSyncDevicesResponse

Response type for the RequestSyncDevices call. Intentionally empty upon success. An HTTP response code is returned with more details upon failure.

StateAndNotificationPayload

Payload containing the state and notification information for devices.

Fields
devices

ReportStateAndNotificationDevice

The devices for updating state and sending notifications.

SyncRequest

Request type for the Sync call. This should follow the same format as the Actions on Google action.devices.SYNC request with the exception of the extra agent_user_id and no intent field.

Fields
request_id

string

Request ID used for debugging.

agent_user_id

string

Required. Third-party user ID.

SyncResponse

Response type for the Sync call. This should follow the same format as the Actions on Google action.devices.SYNC response.

Example

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "agentUserId": "1836.15267389",
    "devices": [{
      "id": "123",
      "type": "action.devices.types.OUTLET",
      "traits": [
        "action.devices.traits.OnOff"
      ],
      "name": {
        "defaultNames": ["My Outlet 1234"],
        "name": "Night light",
        "nicknames": ["wall plug"]
      },
      "willReportState": false,
      "deviceInfo": {
        "manufacturer": "lights-out-inc",
        "model": "hs1234",
        "hwVersion": "3.2",
        "swVersion": "11.4"
      },
      "customData": {
        "fooValue": 74,
        "barValue": true,
        "bazValue": "foo"
      }
    }]
  }
}
Fields
request_id

string

Request ID used for debugging. Copied from the request.

payload

SyncResponsePayload

Devices associated with the third-party user.

SyncResponsePayload

Payload containing device information.

Fields
agent_user_id

string

Third-party user ID

devices[]

Device

Devices associated with the third-party user.