Camera

Nest Cam

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 usage name usage

name_long

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

name_long in a message

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

Video stream

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.

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

Image or GIF files

Cat in a basket

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.

Backlink banner

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:

  1. Receive the app_url from the Nest API. It should look something like this: "nestmobile://cameras/CjZHZ….7IYIm?auth=c.QbpCljxi5...Ny4gh&"
  2. 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.