Use the API

AI-generated Key Takeaways

• After obtaining an access token, the SDM API can be utilized to access and manage your smart devices.

• The API allows you to retrieve device and structure lists using GET calls to their respective endpoints.

• Device-specific information and control are achieved by targeting the device ID endpoint with GET and POST requests.

• Executing commands on devices, such as changing thermostat modes or generating camera streams, involves POST calls to the executeCommand endpoint with specific parameters.

• Common troubleshooting steps include refreshing expired access tokens and consulting the error code reference for other issues.

With an access token in hand and the initial device list call made, you're now ready to use the SDM API to access and control your device.

List structures and devices

Use curl to make a simple GET call to the structures endpoint:

curl -X GET 'https://smartdevicemanagement.googleapis.com/v1/enterprises/project-id/structures' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer access-token'

A successful call returns a list of structures for accounts linked to your Device Access project:

{
  "structures": [
    {
      "name": "enterprises/project-id/structures/structure-id",
      "traits": {
        "sdm.structures.traits.Info": {
          "customName": "structure-name"
        }
      }
    }
  ]
}

If you haven't done so already, make a GET call to the devices endpoint to get a list of devices:

curl -X GET 'https://smartdevicemanagement.googleapis.com/v1/enterprises/project-id/devices' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer access-token'

A successful call returns a list of devices linked to your Device Access project. Each device has its own unique list of available traits:

{
  "devices": [
    {
      "name": "enterprises/project-id/devices/device-id",
      "type": "sdm.devices.types.device-type",
      "traits": { ... },
      "parentRelations": [
        {
          "parent": "enterprises/project-id/structures/structure-id/rooms/room-id",
          "displayName": "device-room-name"
        }
      ]
    }
  ]
}

Copy the device-id for each device, you'll need that for other API calls.

Get information for a device

To get information a specific device, make a GET call to the device-id endpoint:

curl -X GET 'https://smartdevicemanagement.googleapis.com/v1/enterprises/project-id/devices/device-id' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer access-token'

The response should be similar as before, but just for the specific device:

{
  "name": "enterprises/project-id/devices/device-id",
  "type": "sdm.devices.types.device-type",
  "traits": { ... },
  "parentRelations": [
    {
      "parent": "enterprises/project-id/structures/structure-id/rooms/room-id",
      "displayName": "device-room-name"
    }
  ]
}

Execute a command

After validating your access with a successful GET call, try to execute a command depending on the type of device you have authorized:

THERMOSTAT

curl -X POST \
  'https://smartdevicemanagement.googleapis.com/v1/enterprises/project-id/devices/device-id:executeCommand' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer access-token' \
  --data-raw '{
    "command" : "sdm.devices.commands.ThermostatMode.SetMode",
    "params" : {
      "mode" : "HEAT"
    }
  }'

CAMERA

curl -X POST \
  'https://smartdevicemanagement.googleapis.com/v1/enterprises/project-id/devices/device-id:executeCommand' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer access-token' \
  --data-raw '{
    "command" : "sdm.devices.commands.CameraLiveStream.GenerateRtspStream",
    "params" : {}
  }'

If your call is successful, the following results occur:

THERMOSTAT

You receive an empty response and the physical thermostat changes its current mode to the mode specified in the command parameters.

{}

CAMERA

You receive a live stream URL and related tokens.

{
  "results" : {
    "streamUrls" : {
      "rtspUrl" : "rtsps://someurl.com/CjY5Y3VKaTZwR3o4Y19YbTVfMF...?auth=g.0.streamingToken"
    },
    "streamExtensionToken" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...",
    "streamToken" : "g.0.streamingToken",
    "expiresAt" : "2018-01-04T18:30:00.000Z"
  }
}

Troubleshooting

Unauthenticated

Access tokens for the SDM API are only valid for 1 hour. If you get an UNAUTHENTICATED response, the token has likely expired. Use your refresh token to get a new access token.

Other errors

See the Error Code Reference for the full list of Device Access error codes.