Smart Device Management API

  • The SDM API is a REST API that lets you manage Google Nest devices by viewing their traits and executing commands.

  • All API calls should be made to the endpoint https://smartdevicemanagement.googleapis.com/v1 with the provided access token.

  • The API uses a trait-based model, and specific traits available for each device type can be found in the provided links to individual device guides.

  • You can execute commands, get device information, and list structures, rooms, or devices using the methods detailed in the API Reference.

  • Nest devices authorized through the SDM API should not be synced to Home Graph for Google Assistant integrations to avoid conflicts.

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.