Last Updated: April 12th, 2024
Document Revision: 2.8.1
API Version: 2.8
Introduction
Starling Developer Connect (SDC) allows developers who use Starling Home Hub to write their own apps in Node.js, Python or any other modern
language to monitor and control Nest devices in their homes using a simple REST API. The SDC API is supported by Starling Home Hub
firmware version 8.0 and above.
The SDC API has some conceptual similarities with the (discontinued) Works with Nest API, and the Google Device Access API,
but there are some very important differences. Most significantly, unlike the Google APIs, the SDC API service is hosted not
in the cloud but directly by your Starling Home Hub device on your local network. As a result, the API is only reachable by other
devices that are also inside your home, on your home network. Additionally, as Starling Home Hub - once configured - remains
authenticated with the Google/Nest service, the SDC API does not require further transmission of your account credentials between apps, or
over your network. So, access to your Nest devices via the SDC API is 'secure by design' on multiple levels, and because the SDC API is hosted by
a device in your home rather than on the cloud, it can't be 'discontinued' in the way a cloud-based API like Works with Nest was.
A more detailed comparison:
|
Works with Nest API |
Device Access API |
SDC API |
Nest Accounts |
check |
close |
check |
Google Accounts |
close |
check |
check |
Access via |
Cloud |
Cloud |
Local network |
Thermostat |
Some models |
check |
check |
Temperature Sensor |
close |
close |
check |
Protect |
check |
close |
check |
Camera (pre-2021 models) |
check |
check |
check |
Camera (2021/22 models) |
close |
check |
check |
Nest × Yale Lock |
close |
close |
check |
Nest Weather Service |
close |
close |
check |
Availability |
Discontinued |
Active |
Active |
Hub Setup
The SDC API is disabled by default. To enable the API, go to the Starling app, then:
- Open the Starling Developer Connect section in the app.
- If not already active, you will be prompted to enable Password Security to set an access password for your hub.
- Select the Enable HTTP Access and/or Enable HTTPS Access checkboxes.
Access to the API requires creating an API key - one per app - with specific permissions that you set. To create
an API key for your application:
- In the My API Keys section, press Create New API Key.
- Enter a name for your app/API key, and choose the permissions appropriate for your use case.
- Press Create API Key. Your API key (a 12-character opaque alphanumeric string) will then appear under My API Keys.
To modify an existing API key's permissions or name, hover over the key in
My API Keys, then press the
edit button.
API Endpoints
The SDC API is hosted on your Starling Home Hub device itself, and so you access the API using your hub's IP address, which you can find in the Starling app
in the
Advanced Settings section. The API server runs on port 3080 (HTTP access), and 3443 (HTTPS/SSL access).
API functions
are accessed using a base path of
/api/connect/v1. Access via HTTPS must be via the
.local.starling.direct suffix to permit SSL
certificate validation.
:
- If HTTP API access is enabled, the SDC API will be available at:
http://:3080/api/connect/v1/...
- If HTTPS API access is enabled, the SDC API will be available at:
https://:3443/api/connect/v1/...
All API calls return data using a
Content-Type of
application/json. When making POST calls to the API, format your request body using a
Content-Type of
application/json (recommended) or
application/x-www-form-urlencoded.
GET /status
Returns status information for the Starling Developer Connect service, including the API version, whether the API is ready
to accept requests, and whether Starling Home Hub is currently connected to the Nest cloud service. We recommend calling this endpoint
first to check the service is ready before calling other endpoints.
Query Parameters
Field |
Type |
Value |
Required |
key |
String |
Application API key (see Hub Setup) |
Yes |
Response (Success): JSON Object
Field |
Type |
Value |
apiVersion |
Number |
Version of the SDC API supported by this hub |
apiReady |
Boolean |
True if the API service can currently accept requests, false otherwise (if for example the hub is starting up or shutting down) |
connectedToNest |
Boolean |
True if the hub is currently connected to Nest, false otherwise |
appName |
String |
Name of this app/API key, as set in the Starling app |
permissions |
Object |
Field |
Type |
Value |
read |
Boolean |
App has permission to read Nest device properties |
write |
Boolean |
App has permission to change Nest device properties |
camera |
Boolean |
App has permission to request images from cameras |
|
Response (Failure): JSON Object
See
Error Responses for details.
Example Call
GET http://:3080/api/connect/v1/status?key=pqcIHXIeiypE
Example Response
{
"apiVersion": 2.4,
"apiReady": true,
"connectedToNest": true,
"appName": "John's App",
"permissions": {
"read": true,
"write": false,
"camera": false
}
}
GET /devices
Returns a list of all connected Nest devices. The list is returned as a JSON array of objects, one
object per Nest device. For API version 2.3 and above, if enabled in the hub's configuration, also returns weather
objects corresponding to Nest's weather service readings for the corresponding Nest home.
Query Parameters
Field |
Type |
Value |
Required |
key |
String |
Application API key (see Hub Setup) |
Yes |
Response (Success): JSON Object
Field |
Type |
Value |
status |
String |
"OK" |
devices |
Array |
Field |
Type |
Value |
type |
String |
Nest device type: "thermostat", "temp_sensor", "protect", "cam", "lock", "home_away_control", "weather" |
id |
String |
Nest device ID for this device, e.g. "6416660000123456" |
where |
String |
Location of device, e.g. "Front Room", if set in the Nest app (otherwise, "") |
name |
String |
Name of the device, e.g. "Thermostat", if set in the Nest app (otherwise, ""). HomeKit accessory names are formed by appending the "name" property to the "where" property |
serialNumber |
String |
(API version 1.1 and above) Serial number of the device, e.g. "09AC01ACXXXXYYYY", as printed on the label on the back of the device (if no serial number, "") |
structureName |
String |
(API version 1.2 and above) Name of the structure (Nest home) where the device resides, e.g. "John's Home" |
supportsStreaming |
String |
(API version 2.0 and above, cameras only) True if the camera supports the SDC WebRTC Camera Stream Control APIs |
|
Response (Failure): JSON Object
See
Error Responses for details.
Example Call
GET http://:3080/api/connect/v1/devices?key=pqcIHXIeiypE
Example Response
{
"status": "OK",
"devices": [
{
"type": "thermostat",
"id": "6416660000123456",
"where": "Front Room",
"name": "Thermostat",
"serialNumber": "09AC01ACXXXXYYYY",
"structureName": "John's Home"
},
{
"type": "cam",
"id": "6416660000ABCDEF",
"where": "",
"name": "Driveway Camera",
"serialNumber": "19AA01AEXXXXYYYY",
"structureName": "John's Home",
"supportsStreaming": true
},
{
"type": "home_away_control",
"id": "12345678-0000-1111-2222-333300abcdef",
"where": "",
"name": "Home Occupied - John's Home",
"serialNumber": "",
"structureName": "John's Home"
}
]
}
GET /devices/{id}
Returns a list of all properties, and their values, of a Nest device. The list is returned as a JSON object containing one
field/value pair for each property. Device properties are returned from Starling's cache, and are accessible even if Starling Home Hub is not
connected to the Nest service (although they may not be up to date in that case). Because this call does not trigger a request to the Nest
cloud service, you may safely poll this API call at a high frequency to check for property updates without risk of exceeding Nest's server side rate limits.
Path Parameters
Field |
Type |
Value |
Required |
id |
String |
Nest device ID (as returned by GET /devices) |
Yes |
Query Parameters
Field |
Type |
Value |
Required |
key |
String |
Application API key (see Hub Setup) |
Yes |
Response (Success): JSON Object
Field |
Type |
Value |
status |
String |
"OK" |
properties |
Object |
Field |
Type |
Value |
Property Name |
Boolean, Number or String |
Property Value |
... |
... |
... |
|
See
Device Properties for a full list of properties supported by each Nest device type.
Response (Failure): JSON Object
See
Error Responses for details.
Example Call
GET http://:3080/api/connect/v1/devices/6416660000123456?key=pqcIHXIeiypE
Example Response
{
"status": "OK",
"properties": {
"type": "thermostat",
"id": "6416660000123456",
"where": "Front Room",
"name": "Thermostat",
"serialNumber": "09AC01ACXXXXYYYY",
"structureName": "John's Home",
"displayTemperatureUnits": "F",
"backplateTemperature": 22.77777777777778,
"currentTemperature": 22.77777777777778,
"targetTemperature": 17.22222222222222,
"targetHeatingThresholdTemperature": 15.22222222222222,
"targetCoolingThresholdTemperature": 24.77777777777778,
"humidityPercent": 50.545108795166016,
"hvacMode": "heat",
"hvacState": "off",
"canHeat": true,
"canCool": false,
"fanRunning": false,
"ecoMode": false
}
}
GET /devices/{id}/{property}
Returns the value of a single property of a Nest device. Device properties are returned from Starling's cache, and are accessible even if Starling Home Hub is not
connected to the Nest service (although they may not be up to date in that case). Because this call does not trigger a request to the Nest
cloud service, you may safely poll this API call at a high frequency to check for property updates without risk of exceeding Nest's server side rate limits.
Path Parameters
Field |
Type |
Value |
Required |
id |
String |
Nest device ID (as returned by GET /devices) |
Yes |
Query Parameters
Field |
Type |
Value |
Required |
key |
String |
Application API key (see Hub Setup) |
Yes |
Response (Success): JSON Object
Field |
Type |
Value |
status |
String |
"OK" |
properties |
Object |
Field |
Type |
Value |
Property Name |
Boolean, Number or String |
Property Value |
|
See
Device Properties for a full list of properties supported by each Nest device type.
Response (Failure): JSON Object
See
Error Responses for details.
Example Call
GET http://:3080/api/connect/v1/devices/6416660000123456/currentTemperature?key=pqcIHXIeiypE
Example Response
{
"status": "OK",
"properties": {
"currentTemperature": 22.77777777777778
}
}
GET /devices/{id}/snapshot
Returns a snapshot image from a specified camera. If an event (like a doorbell press, or person detection) has
occurred in the last 5 seconds, this API call returns a snapshot of that event if possible, otherwise it returns a snapshot of what the camera is
currently seeing. Because this API call results in your hub making a request to the Nest API cloud service, be aware of potential rate limits and do not call
with a frequency higher than once every 10 seconds.
Path Parameters
Field |
Type |
Value |
Required |
id |
String |
Camera device ID (as returned by GET /devices) |
Yes |
Query Parameters
Field |
Type |
Value |
Required |
key |
String |
Application API key (see Hub Setup) |
Yes |
width |
Number |
(Pre-2021 model Nest cameras only) Requested width of snapshot image in pixels, at most 1280. If not specified, the default is 640 |
No |
Response (Success): JPEG Image (MIME type image/jpeg)
Response (Failure): JSON Object
See
Error Responses for details.
Example Call
GET http://:3080/api/connect/v1/devices/12345600001111222233334444abcdef/snapshot?key=pqcIHXIeiypE
POST /devices/{id}
Sets one or more properties of a Nest device. Because this API call results in your hub making a request to the Nest API cloud service, be aware of potential rate limits and do not call
with a frequency higher than once every second.
Path Parameters
Field |
Type |
Value |
Required |
id |
String |
Nest device ID (as returned by GET /devices) |
Yes |
Query Parameters
Field |
Type |
Value |
Required |
key |
String |
Application API key (see Hub Setup) |
Yes |
Request Body: JSON Object
Field |
Type |
Value |
Property Name |
Boolean, Number or String |
Property Value |
... |
... |
... |
Response (Success): JSON Object
Field |
Type |
Value |
status |
String |
"OK" |
setStatus |
Object |
Field |
Type |
Value |
Property Name |
String |
Value |
Meaning |
"OK" |
Property changed successfully |
"READ_ONLY_PROPERTY" |
Failed - property is read-only |
"INVALID_VALUE" |
Failed - property value specified is invalid |
"PROPERTY_NOT_FOUND" |
Failed - property specified does not exist |
"NEST_SET_ERROR" |
Failed - the Nest service reported an error trying to set the property |
|
... |
... |
... |
|
See
Device Properties for a full list of properties supported by each Nest device type.
Response (Failure): JSON Object
See
Error Responses for details.
Example Call
POST http://:3080/api/connect/v1/devices/6416660000123456?key=pqcIHXIeiypE
Example Request Body
{
"targetTemperature": 22,
"hvacMode": "heat"
}
Example Response
{
"status": "OK",
"setStatus": {
"targetTemperature": "OK",
"hvacMode": "OK"
}
}
Camera Stream Control APIs
Modern Nest cameras (2021 models and later) use WebRTC for providing live video and audio streams. The Starling Developer Connect API
includes endpoints to start, maintain and stop WebRTC connections with Nest cameras which you can use to incorporate Nest camera video into your own
applications. All modern web browsers include support for WebRTC out of the box.
For a complete example showing how to show live Nest camera streams in a browser app, please visit:
https://github.com/starling-home-hub/camera-streamer
POST /devices/{id}/stream
(API version 2.0 and above, 2021 model cameras only) Initiates a WebRTC negotiation to create a live Nest camera stream (video and audio). Before calling
this endpoint, you must have created a WebRTC offer (for example, using RTCPeerConnection.createOffer in a browser) to submit to the camera. This endpoint responds with a
WebRTC answer from the camera (which should be submitted back to the browser, for example, using RTCPeerConnection.setRemoteDescription) to start the stream.
Path Parameters
Field |
Type |
Value |
Required |
id |
String |
Nest device ID (as returned by GET /devices) |
Yes |
Query Parameters
Field |
Type |
Value |
Required |
key |
String |
Application API key (see Hub Setup) |
Yes |
Request Body: JSON Object
Field |
Type |
Value |
offer |
String |
Base64-encoded WebRTC SDP offer describing the local endpoint, produced by RTCPeerConnection.createOffer() in a browser or similar |
Response (Success): JSON Object
Field |
Type |
Value |
status |
String |
"OK" |
answer |
String |
Base64-encoded WebRTC SDP answer describing the camera endpoint, to submit to RTCPeerConnection.setRemoteDescription() in a browser or similar |
streamId |
String |
Camera stream ID representing the video/audio stream just created |
Example Call
POST http://:3080/api/connect/v1/devices/6416660000123456/stream?key=pqcIHXIeiypE
Example Request Body
{
"offer": "dj0wDQpvPS0gNTE5MjQ0NDkxNDMyNTYzMjg2NyAxNjMyMDg3...",
}
Example Response
{
"status": "OK",
"answer": "dj0wDQpvPS0gMCAyIElOIElQNCAxMjcuMC4wLjENCnM9LQ0K...",
"streamId": "CiY1ZWVjZjA4My1kYTk3LTQ5ODEtOWI0MS02YTVjZDhkYzQwMWNfNRABGAU="
}
POST /devices/{id}/stream/{sid}/extend
(API version 2.0 and above, 2021 model cameras only) Active Nest camera streams created by
POST /devices/{id}/stream time out after two minutes unless extended. To
keep a stream active, you must call this endpoint repeatedly at less than two-minute intervals. (We recommend calling every 60 seconds.)
Path Parameters
Query Parameters
Field |
Type |
Value |
Required |
key |
String |
Application API key (see Hub Setup) |
Yes |
Request Body
Leave empty.
Response (Success): JSON Object
Field |
Type |
Value |
status |
String |
"OK" |
Example Call
POST http://:3080/api/connect/v1/devices/6416660000123456/stream/CiY1ZWVjZjA4My1kYTk3LTQ5ODEtOWI0MS02YTVjZDhkYzQwMWNfNRABGAU=/extend?key=pqcIHXIeiypE
Example Response
{
"status": "OK"
}
POST /devices/{id}/stream/{sid}/stop
(API version 2.0 and above, 2021 model cameras only) Stops an active Nest camera stream created by
POST /devices/{id}/stream.
Path Parameters
Query Parameters
Field |
Type |
Value |
Required |
key |
String |
Application API key (see Hub Setup) |
Yes |
Request Body
Leave empty.
Response (Success): JSON Object
Field |
Type |
Value |
status |
String |
"OK" |
Example Call
POST http://:3080/api/connect/v1/devices/6416660000123456/stream/CiY1ZWVjZjA4My1kYTk3LTQ5ODEtOWI0MS02YTVjZDhkYzQwMWNfNRABGAU=/stop?key=pqcIHXIeiypE
Example Response
{
"status": "OK"
}
Device Properties
Each Nest device type publishes its own set of properties, detailed in the sections below. They are retrieved as a set of
JSON field/value pairs by the GET /devices/{id} and GET /devices/{id}/{property} API calls, and modified by the POST /devices/{id} API call.
In addition to properties specific to the respective device types, all devices also have 4 standard properties:
Field |
Type |
Value |
Writable |
type |
String |
Nest device type: "thermostat", "temp_sensor", "protect", "cam", "lock", "home_away_control" |
close |
id |
String |
Nest device ID for this device, e.g. "6416660000123456" |
close |
where |
String |
Location of device, e.g. "Front Room", if set in the Nest app (otherwise, "") |
close |
name |
String |
Name of the device, e.g. "Thermostat", if set in the Nest app (otherwise, ""). HomeKit accessory names are formed by appending the "name" property to the "where" property |
close |
serialNumber |
String |
(API version 1.1 and above) Serial number of the device, e.g. "09AC01ACXXXXYYYY", as printed on the label on the back of the device (if no serial number, "") |
close |
structureName |
String |
(API version 1.2 and above) Name of the structure (Nest home) where the device resides, e.g. "John's Home" |
close |
Thermostat
Field |
Type |
Value |
Writable |
backplateTemperature |
Number |
Temperature at the thermostat, in degrees C |
close |
batteryStatus |
String |
(API version 2.5 and above, 2020 model Nest Thermostat only) Battery (alkaline AAA) status. Values: "normal", "low" |
close |
canCool |
Boolean |
True if the HVAC system can cool (i.e. has air conditioning) |
close |
canHeat |
Boolean |
True if the HVAC system can heat (i.e. has a furnace or boiler) |
close |
currentHumidifierState |
String |
(HVAC systems with a humidifier/dehumidifier only) Current humidifier/dehumidifier state. Values: "off", "idle", "humidifying", "dehumidifying" |
close |
currentTemperature |
Number |
Temperature at the currently active Temperature Sensor, in degrees C. If no Temperature Sensors are present, or none is active, returns the temperature at the thermostat |
close |
displayTemperatureUnits |
String |
Temperature units as shown on the thermostat's physical display. Values: "C", "F" |
check |
ecoMode |
Boolean |
(3rd Gen Learning Thermostat and Thermostat E only) True if the thermostat is in Eco Mode |
check |
fanRunning |
Boolean |
(HVAC systems with a fan only) True if the fan is currently running |
check |
hotWaterEnabled |
Boolean |
(UK/EU HVAC systems with a boiler only) True if the hot water boiler is active |
check |
humidifierActive |
Boolean |
(HVAC systems with a humidifier/dehumidifier only) True if the humidifier/dehumidifier is active |
check |
humidityPercent |
Number |
Relative humidity at the thermostat, in % |
close |
hvacMode |
String |
Currently active thermostat mode. Values: "off", "heat", "cool", "heatCool" |
check |
hvacState |
String |
Current HVAC system state. Values: "off", "heating", "cooling" |
close |
presetSelected |
String |
(October 2020 Google Nest Thermostat only) The name of the currently selected preset, or "" (no preset selected). Presets include "Eco", "Normal", "Comfort" plus user-defined preset names. Note you cannot deselect a preset by writing "" to this property - instead, just change targetTemperature |
check |
sensorSelected |
String |
The device ID of the currently selected Temperature Sensor, or "" (no sensor selected, i.e. thermostat is tracking to the backplate temperature) |
check |
targetCoolingThresholdTemperature |
Number |
Thermostat cooling setpoint temperature for "heatCool" mode, in degrees C |
check |
targetHeatingThresholdTemperature |
Number |
Thermostat heating setpoint temperature for "heatCool" mode, in degrees C |
check |
targetHumidity |
Number |
(HVAC systems with a humidifier/dehumidifier only) Thermostat humidity setpoint, in % |
check |
targetTemperature |
Number |
Thermostat setpoint temperature for "heat" and "cool" modes, in degrees C |
check |
tempHoldMode |
Boolean |
(October 2020 Google Nest Thermostat only) True if the thermostat is in Temperature Hold Mode |
check |
Temperature Sensor
Field |
Type |
Value |
Writable |
batteryStatus |
String |
Battery status. Values: "normal", "low" |
close |
currentTemperature |
Number |
Temperature at the sensor, in degrees C |
close |
Protect
Field |
Type |
Value |
Writable |
batteryStatus |
String |
Battery status. Values: "normal", "low" |
close |
coDetected |
Boolean |
True if a high level of carbon monoxide (CO) is detected ("emergency" state) |
close |
coStateDetail |
String |
(API version 2.7 and above) Detailed carbon monoxide (CO) detection state. Values: "ok" (no CO), "warn" (CO levels rising, no alarm), "emergency" (high CO levels, alarm triggered) |
close |
manualTestActive |
Boolean |
(API version 1.2 and above) True if manual test of the alarm is in progress |
close |
occupancyDetected |
Boolean |
(Wired Nest Protects only) True if occupancy is detected |
close |
smokeDetected |
Boolean |
True if heavy smoke is detected ("emergency" state) |
close |
smokeStateDetail |
String |
(API version 2.7 and above) Detailed smoke detection state. Values: "ok" (no smoke), "warn" (smoke levels rising, no alarm), "emergency" (high smoke levels, alarm triggered) |
close |
Camera
Field |
Type |
Value |
Writable |
animalDetected |
Boolean |
(API version 2.0 and above, 2021 model Nest cameras only) True if the camera is currently detecting an animal. Requires animal detection to be enabled in the Google Home app |
close |
batteryIsCharging |
Boolean |
(API version 2.0 and above, cameras with batteries only) True if camera is currently charging (i.e. connected to a power source) |
close |
batteryLevel |
Number |
(API version 2.0 and above, cameras with batteries only) Current battery charge level (in percent) |
close |
batteryStatus |
String |
(API version 2.0 and above, cameras with batteries only) Battery status. Values: "normal", "low" |
close |
cameraEnabled |
Boolean |
True if the camera is currently turned on |
check |
cameraModel |
String |
Model of the camera: "Nest Cam with Floodlight", "Nest Cam (wired)", "Nest Cam (Battery)", "Nest Doorbell (battery)", "Nest Cam", "Nest Cam Outdoor", "Nest Doorbell (wired)", "Nest Doorbell (Wired, 2nd Gen)", "Nest Cam IQ", "Nest Cam IQ Outdoor", "Google Nest Hub Max", "Dropcam", "Dropcam Pro", "Unknown" |
close |
chimeEnabled |
Boolean |
(Nest Doorbell only) True if the indoor chime is enabled |
check |
doorbellPushed |
Boolean |
(Nest Doorbell only) True if the doorbell has been pushed in the last 5 seconds |
close |
faceDetected:name |
Boolean |
(Nest Aware only) True if face name is detected |
close |
floodlightOn |
Boolean |
(API version 2.1 and above, cameras with floodlights only) True if floodlight is on |
check |
garageDoorState |
Boolean |
(API version 2.8 and above, cameras with garage door detection supported and enabled only) Garage door detection state. Values: "closed", "open" |
close |
motionDetected |
Boolean |
True if the camera is currently detecting motion. Requires motion detection to be enabled in the Nest/Google Home app |
close |
packageDelivered |
Boolean |
(Nest Doorbell with Nest Aware only) True if the camera has recently detected a package being delivered. Requires package detection to be enabled in the Nest/Google Home app |
close |
packageRetrieved |
Boolean |
(Nest Doorbell with Nest Aware only) True if the camera has recently detected a package being retrieved. Requires package detection to be enabled in the Nest/Google Home app |
close |
personDetected |
Boolean |
(Nest Aware, Nest Doorbell or Nest Cam IQ only) True if the camera is currently detecting a person. Requires person detection to be enabled in the Nest/Google Home app |
close |
runningOnBattery |
Boolean |
(API version 2.0 and above) True if camera is currently running on battery power, false if running on DC power and/or no battery is present |
close |
soundDetected |
Boolean |
(Pre-2021 model Nest cameras only) True if the camera is currently detecting sound. Requires sound detection to be enabled in the Nest/Google Home app |
close |
supportsStreaming |
Boolean |
(2021 model Nest cameras only) True if the camera supports the SDC WebRTC Camera Stream Control APIs |
close |
trickleCharging |
Boolean |
(API version 2.4 and above) True if the camera is trickle charging from a limited power source, for example a doorbell transformer or a solar panel |
close |
vehicleDetected |
Boolean |
(API version 2.0 and above, 2021 model Nest cameras only) True if the camera is currently detecting a vehicle. Requires vehicle detection to be enabled in the Google Home app |
close |
zoneActivityDetected:name |
Boolean |
(Nest Aware only) True if activity is detected in zone name |
close |
Nest × Yale Lock
Field |
Type |
Value |
Writable |
autoRelockEnabled |
Boolean |
True if Auto Relock is enabled |
check |
batteryStatus |
String |
Battery status. Values: "normal", "low" |
close |
currentState |
String |
Current lock state. Values: "unlocked", "locked", (API version 2.6 and above) "jammed" |
close |
isTampered |
Boolean |
(API version 2.5 and above) True if the lock has been tampered with (i.e. front plate removed) |
close |
lastLockUnlockMethod |
String |
(API version 2.7 and above) How the lock was last locked or unlocked. Values: "physical", "keypad", "app", "other" |
close |
oneTouchLockEnabled |
Boolean |
True if One-Touch Lock mode is enabled |
check |
privacyModeEnabled |
Boolean |
True if Privacy Mode is enabled (absent if Privacy Mode is completely disabled from the Nest app) |
check |
targetState |
String |
Target lock state. Values: "unlocked", "locked" |
check |
Home/Away Control
Field |
Type |
Value |
Writable |
homeState |
String |
True if system is in Home Mode, false if system is in Away Mode |
check |
Nest Weather Service
Field |
Type |
Value |
Writable |
currentTemperature |
Number |
(API version 2.3 and above) Temperature outside this home, in degrees C |
close |
humidityPercent |
Number |
(API version 2.3 and above) Relative humidity outside this home, in % |
close |
serialNumber |
String |
(API version 2.3 and above) ID of the structure (Nest home) for this weather service reading |
close |
structureName |
String |
(API version 2.3 and above) Name of the structure (Nest home) for this weather service reading, e.g. "John's Home" |
close |
Error Responses
Calls to the Starling Developer Connect API that are not successful return a 400, 401 or 404 response.
400 Bad Request
Response (Failure): JSON Object
Field |
Type |
Value |
status |
String |
"Error" |
code |
String |
Value |
Meaning |
"BAD_CONTENT_TYPE" |
POST call to set properties must have message body content type of "application/json" or "application/x-www-form-urlencoded" |
"DEVICE_NOT_FOUND" |
Non-existent Nest device ID specified |
"EMPTY_REQUEST" |
POST call to set properties has empty message body |
"INCOMPLETE_REQUEST" |
POST call is missing required request parameters in the body |
"NO_DEVICE_ID" |
Nest device ID missing from request |
"NO_SNAPSHOT_AVAILABLE" |
(API version 2.2 and above) Camera did not respond to Starling Home Hub's request for a snapshot. Camera may need to be restarted |
"NO_SNAPSHOT_CAMERA_OFF" |
(API version 2.0 and above) Camera is turned off and cannot return a snapshot at this time |
"NO_SNAPSHOT_CAMERA_OFFLINE" |
(API version 2.0 and above) Camera is not the connected to the network and cannot return a snapshot at this time |
"NO_SNAPSHOT_CAMERA_SAVING_ENERGY" |
(API version 2.0 and above, 2021 model cameras only) Camera is saving energy and cannot return a snapshot at this time. Please wait 2 minutes, then re-issue this API call |
"NO_SNAPSHOT_PLEASE_WAIT" |
(API version 2.0 and above, 2021 model cameras only) Camera is preparing to take a snapshot. Please wait 15 seconds, then re-issue this API call |
"NOT_YET_LOADED" |
Hub is still loading devices from the Nest cloud service. Try again in a few seconds |
"PROPERTY_NOT_FOUND" |
Non-existent property name specified |
"SDC_NOT_READY" |
API server is starting up. Try again in a few seconds |
"STREAM_REQUEST_REFUSED" |
The Nest camera refused the request to create, extend or stop a stream. The API call response contains additional detail on what went wrong |
|
message |
String |
English-language message providing more detail on the error |
401 Unauthorized
Response (Failure): JSON Object
Field |
Type |
Value |
status |
String |
"Error" |
code |
String |
Value |
Meaning |
"INVALID_API_KEY" |
API key not specified in query string, is not valid, or has the wrong permissions |
|
message |
String |
English-language message providing more detail on the error |
404 Not Found
Response (Failure): JSON Object
Field |
Type |
Value |
status |
String |
"Error" |
Example Projects
Here we present some Node.js example projects to demonstrate use of the Starling Developer Connect API.
Temperature Logger (Node.js)
Demonstrates connecting to the SDC API from Node.js, and polling a property (currentTemperature) of your Nest Thermostat at regular intervals.
Camera Dashboard (VueJS)
Demonstrates connecting to the SDC API from a browser app, and displaying a dashboard of all your cameras with periodic snapshots. (All Nest camera models supported.)
Camera Streamer (VueJS)
Demonstrates connecting to the SDC API from a browser app, and displaying a live stream (video and audio) of your all Nest cameras together. (2021 model Nest cameras only.)