Smart Device Management API

The SDM API is a REST API that provides various methods to view traits and execute trait commands for management of Google Nest devices. Use the access token granted during the authorization process with each API call.

Traits

The SDM API uses a trait-based model for device information and functionality. Check the individual device guides to see what traits are available for a device:

Methods

See the API Reference for complete details on all the methods available for the SDM API.

executeCommand

Executes a command to an authorized device.

Use a POST call to execute a command. For example, to change the thermostat mode:

POST /enterprises/project-id/devices/device-id:executeCommand
{
  "command" : "sdm.devices.commands.ThermostatMode.SetMode",
  "params" : {
    "mode" : "HEAT"
  }
}

Further examples of commands can be found in each individual trait reference page. See the complete trait listing for more information.

get

Gets information about an authorized structure or device.

A GET call returns a single response with current fields and values for all traits available for a structure or device that the user has authorized and a `parentRelations' object, which represents the parent resource of the current resource, either a structure or room.

For example, a Nest Thermostat might return the following:

GET /enterprises/project-id/devices/device-id
{
  "name" : "enterprises/project-id/devices/device-id",
  "type" : "sdm.devices.types.THERMOSTAT",
  "assignee" : "enterprises/project-id/structures/structure-id/rooms/room-id",
  "traits" : {
    "sdm.devices.traits.Connectivity" : {
      "status" : "ONLINE"
    },
    "sdm.devices.traits.Fan" : {
      "timerMode" : "ON",
      "timerTimeout" : "2019-05-10T03:22:54Z"
    },
    "sdm.devices.traits.Humidity" : {
      "ambientHumidityPercent" : 35.0
    },
    "sdm.devices.traits.Info" : {
      "customName" : "My device"
    },
    "sdm.devices.traits.Settings" : {
      "temperatureScale" : "CELSIUS"
    },
    "sdm.devices.traits.Temperature" : {
      "ambientTemperatureCelsius" : 23.0
    },
    "sdm.devices.traits.ThermostatEco" : {
      "availableModes" : ["MANUAL_ECO", "OFF"],
      "mode" : "MANUAL_ECO",
      "heatCelsius" : 20.0,
      "coolCelsius" : 22.0
    },
    "sdm.devices.traits.ThermostatHvac" : {
      "status" : "HEATING"
    },
    "sdm.devices.traits.ThermostatMode" : {
      "availableModes" : ["HEAT", "COOL", "HEATCOOL", "OFF"],
      "mode" : "COOL"
    },
    "sdm.devices.traits.ThermostatTemperatureSetpoint" : {
      "heatCelsius" : 20.0,
      "coolCelsius" : 22.0
    }
  },
  "parentRelations" : [
    {
      "parent" : "enterprises/project-id/structures/structure-id/rooms/room-id",
      "displayName" : "Lobby"
    }
  ]
}

list

Lists authorized structures, rooms, or devices.

To list all structures, rooms, or devices authorized under a single access token, make a GET call against the appropriate resource endpoint:

GET /enterprises/project-id/structures
GET /enterprises/project-id/structures/structure-id/rooms
GET /enterprises/project-id/devices

Google Assistant integrations

Once a device is authorized for SDM, Google becomes aware of the device in Home Graph and manages its state directly. If you have Google Assistant integration as part of your Commercial offering:

Errors

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