Notice: We're retiring Works with Nest. See the home page for more information.

Camera

Nest Cam™ is an Internet-connected device that is intuitive and easy to use. It continuously learns about usage patterns in the home to save energy, and optimize security and comfort. Users can control Nest Cam from anywhere they have access to an Internet connection.

The Nest API provides access to the following data on Nest Cam, dependent on the level of permissions granted:

Structure name and device "where name" (location in the home)
Camera online status or mic status
Streaming status (turn video streaming on/off)
Device name and where identifier
Last online status change (last online/offline change)
Nest Aware subscription status (enrolled/not enrolled)
Deep links to the live camera feed in the Nest app (iOS, Android) or on the web at home.nest.com
Content related to the last event that triggered a notification, including:
- Sound or motion event detected
- Event start/stop times
- Deep links to image and gif files
Image snapshots on demand
Sharing status and public share URL
Activity zone names, and when there's a motion event, the ids where the motion occurred (Requires Nest Aware)

Camera types

The Nest API supports several camera types:

Nest Cam Indoor — the original indoor Nest camera
Nest Cam Outdoor — the original outdoor Nest camera
Nest Cam IQ Indoor — indoor Nest camera with additional processing power, enabling sophisticated recognition, speaker, and snapshot features
Nest Cam IQ Outdoor — outdoor Nest camera with additional processing power, enabling sophisticated recognition, speaker, and snapshot features
Nest Hello — a camera that functions as a video doorbell

Note that all Nest cameras appear in the API in the same way. In the case of Nest Hello, only the camera portion of the device appears in the Nest API. Doorbell functionality beyond the camera is not available in the API.

Camera permissions

The following access permission levels are available for Nest Cam:

Access	Permissions Camera read	Camera read/write	Camera read + images	Camera read/write + images
Can read all values, excluding: • `activity_zones` • `is_public_share_enabled` • `public_share_url` • `snapshot_url` • `last_event/image_url` • `last_event/animated_image_url` • `last_event/activity_zone_ids`	Yes	Yes
Can read all values			Yes	Yes
Can write `is_streaming` (camera on/off) • This status change requires explicit user agreement		Yes		Yes

For more info, see the Permissions Overview.

Camera identifiers

Device

Nest devices are listed by type as an array of IDs, which can be used to uniquely identify a device via the device path. So a camera ID of "awJo6rH..." means that you can load the cameras device model at devices/cameras/awJo6rH... via the API.

When a device is connected to multiple products, each developer will see a different ID for that device. For a device that has installed multiple products from the same developer, the developer will see the same ID.

Name

The name of a structure defaults to "Home" but can be any string the user chooses.

`name`

In these examples, name is "Downstairs" or "Downstairs (Front Door)".

`name_long`

The longer display name for a device. In this example, name_long is "Office (Upstairs)".

Where

`where_id`

A unique, Nest-generated identifier that represents name
where_id is read-only, and is created automatically in the call to create a custom where name

Learn more about where names for Nest Thermostats, Nest Protects and Nest Cams.

`where_name`

When you choose the Camera read permission, you can access the device where_name from the device object (devices/cameras).

Camera features

Live stream

Use these URLs to access the live stream page from the web or in an app:

Turn streaming on/off

Use the is_streaming field to turn the camera on or off.

Depending on the user's home network and your implementation, there may be a lag in response time
You must ask the user for permission to change streaming status (turn the camera on/off)

Last event

The last_event object is used to get deep links to the last detected sound, motion, or person event, and access the related image or GIF file.

Typical use cases for the last_event/has_person field are to trigger lights, or set the laundry to a quiet cycle.

Security

Using the last_event object and the structure's away state, the structure's wwn_security_state value can escalate from ok to deter, which can trigger other devices. See the Security Guide for deterrence features.

Deep links (web or app URL)

Used to display the last recorded event, and requires user to be signed in to the account.

Image or GIF files

In order for your product to access the last event URLs, the user must have an active Nest Aware subscription, and you must select one of the Camera "+ images" permissions for your client.

When you make a call for image_url or animated_image_url, you'll get a URL in this format:

"STRING1/device_id/STRING2?auth=camera_token"

Use this URL to view an image or GIF.

Note that the STRING values are for internal Nest use only. Do not change the STRING values, or the call will fail.

Snapshot on demand

Use this field to get a snapshot from the live video stream.

snapshot_url - returns the URL of an image captured from the live video stream
Requires that the camera is on and actively streaming

The snapshot quality from the API is only 1080p throughput if you are:

actively viewing the camera stream in the application (web_url)
actively viewing the public stream (app_url)
subscribed to Nest Aware

If you are not actively viewing the stream or do not have a Nest Aware subscription, the API has no 1080p source from which to retrieve a snapshot at that resolution and generates a lower-quality image. Also, low local network bandwidth may cause the API snapshot resolution to dip below 1080p with Nest Aware present.

Learn more about bandwidth requirements for Nest Cameras.

Snapshot rate limits

When you make a call to get the snapshot_url, we apply these rate limits:

2/minute for cameras that do not have a Nest Aware subscription
10/minute for cameras that have a Nest Aware subscription

Activity Zones

In order for your product to access Activity Zone information, the user must have an active Nest Aware subscription (unless it is a Nest Cam IQ), and you must select one of the Camera "+ images" permissions for your client.

When there's a motion event, you can read the activity zone ids where the motion occurred.

activity_zones—list of all zone names, including user-defined and auto-generated name(s)
- Example response: "activity_zones": [ {"name": "Porch", "id": 244083}, {"name": "Walkway", "id": 237084} ... ]
- In this example, the user changed the default "Zone 1" to "Porch", and "Zone 2" to "Walkway"
last_event/activity_zone_ids—list of zone ids that detected motion during the last event
- Example response: "activity_zone_ids" : [ "237084", "244083" ]

Public share URL

Use these two fields together to check if the user has made the video stream public, and if so, access that URL.

is_public_share_enabled—boolean, returns true if the video stream is public, false if private
public_share_url—URL of the shared public stream

iOS backlinks

If you're building an app for iOS 8 or later, you'll need to add backlinks when you use the Camera API.

Parameters

Name	Type	Required	Description
`CUSTOM_SCHEME`	string	yes	• Custom URL scheme for your app • Learn more about URI schemes
`APPNAME`	string	yes	• Name of your app • Displayed in the return banner • Can be localized
`BACKLINK_PATH`	string	yes	• Path back to your app • Learn more about backlinks

Make the call

When you build a flow where your user views the live video stream or an event, include the backlink path:

Receive the app_url from the Nest API. It should look something like this: "nestmobile://cameras/CjZHZ….7IYIm?auth=c.QbpCljxi5...Ny4gh&"
Add your parameters to the app_url in this query string format:
"nestmobile://cameras/CjZHZ….7IYIm?auth=c.QbpCljxi5...Ny4gh&appname=APPNAME&backlink=CUSTOM_SCHEME://BACKLINK_PATH"

Error messages

For information on what API call errors mean and how to handle them, see Error Messages.