Home + Security API Documentation

Configuration

Get configuration

Here is the list of configurations that can be retrieved from Security devices.

Modify configuration

Here is the list of the Security device configurations that can be modified.

Available data

Security devices state can be retrieved in 2 ways: polling the data or being notified by events.

Data

Informative data

Video data

This part concerns the Smart Indoor Cameras (NACamera), the Smart Outdoor Cameras (NOC) and the Doorbell (NDB).

2 types of video are available: live streams and video of past events.

Videos of events are available for those 3 devices whereas video streams are only available for Smart Indoor Cameras and Smart Outdoor Cameras.

Requirements

By default, 3rd party applications do not have access to the video live streaming. Only the app developer has access to the live video streaming.

This access, offered by a specific token is controlled and subject to a few conditions:

• Tokens are stored on the device, not in the 3rd party cloud, to mitigate the impact of a leak

• Business opportunity is evaluated

• The 3rd party architecture is evaluated & validated by Netatmo

• A amendment to the contract must be signed by the 3rd party with its architecture attached. In case of leaks, it is hold responsible. Netatmo reserves the right to revoke the access unilaterally.

Once these conditions fulfilled, the application is whitelisted and the app can request access_* scopes that give access to the cameras VPN urls. To request the scope, please reach complete the request scope form.

When requesting the video access, the developer requests an "access_*" scopes. It is then delivered 2 pairs of tokens:

• Access Token / Refresh Token

• Restricted Access Token / Restricted Refresh Token

The restricted tokens are the tokens without the access_* scopes.

{
    "scope": [
        "read_camera",
        "write_camera",
        "access_camera",
        "read_presence",
        "write_presence",
        "access_presence"
    ],
    "access_token": "61929906e0f96809c04ecb4a|4cf61db77df1c319b9796f3cca817c87",
    "expires_in": 10800,
    "expire_in": 10800,
    "refresh_token": "61929906e0f96809c04ecb4a|c820e6d1501c32ea55be6cb80a04929d",
    "restricted_access_token": "61929906e0f96809c04ecb4a|64c99fe55fb051b5f3d8c7b8763c50b3",
    "restricted_refresh_token": "61929906e0f96809c04ecb4a|62ea5ad5ee38dcb8e6a5be30ec894570"
}

When doing a /homestatus call with the restricted_access_token, no vpn_url address is available whereas when doing the same call with the access_token, the vpn_url s are returned.

Accessing to the video stream/video of an event

Video streams and events can be accessed locally or remotely via the VPN. Hence, the first step is to know if the camera is reachable locally.

Local access test

• Step 1: Use the Homestatus method

If "is_local" parameter is set to "true" this means the camera and your application use the same public IP address. However, being on the same IP address might not mean they are on the same local network.

• Step 2: Test that the app and the camera are on the same local network

Use command /command/ping in the camera vpn_url.

https://prodvpn-eu-2.netatmo.net/10.255.0.1/d257xxxxxxxxxxxx/MTU4Nr-aMZILLg,,/command/ping

You will receive a JSON with the camera address in parameter local_url

local_url: "http://192.168.128.232/52ced8bccxxxxxx"
 product_name: "Smart Indoor Camera"

• Step 3: Run the command /command/ping again against the local_url retrieved

http://192.168.128.232/52ced8bcc8149xxxxxxxxxx/command/ping

If local_url retrieved in the new JSON matches with current one, the camera and your application are on the same network.

Access to the video of an event

• Step 1: Retrieve the camera URL

Use Homestatus method for the user. In the array "modules", retrieve the vpn_url for the camera you're interested in

• Step 2: Retrieve the video_id

Use Getevents to retrieve the video_id of the events array.

• Step 3: Call the m3u8 index with the camera_url and the video id

If your app and the camera are on the same local network, add /camera_url/vod/(your_video_id)/index_local.m3u8 to access the video. If not, add /camera_url/vod/(your_video_id)/index.m3u8 to access the video

Access to the live stream

• Step 1: Retrieve the camera url

Retrieve the vpn_url of the camera you're interested in using Homestatus request.

Note: The vpn_url expire after 3 hours and if the camera reboots

• Step 2: Add /live/index.m3u8 or /live/indexlocal.m3u8 to the vpn_url

If your app is on the local network as the camera, add /live/index_local.m3u8 to access the live stream.

If not, add /live/index.m3u8 to access the live stream.

https://prodvpn-eu-2.netatmo.net/10.255.0.1/d257xxxxxxxxxxxxx/MTU4NDDr-aMZIkmaaLLg,,/live/index.m3u8

To retrieve a live snapshot, add /live/snapshot_720.jpg to the camera url

https://prodvpn-eu-2.netatmo.net/10.255.0.1/d257xxxxxxxxxxxxx/MTU4NDDr-aMZIkmaaLLg,,/live/snapshot_720.jpg

Events

There is a webhook system to keep track of events happening in a user's home. It permits you to build apps that are more reactive as you get notified almost instantly when an event occurs.

Registering

To set up a new webhook, there are two possible solutions:

• Automatic subscription : Go to your application settings and add the webhook link. Once saved, every user that will give the ‘read_device’ acces scope to your application will be registered for webhooks. The webhook is only registered when the user has accepted your app. It means that if your app already has existing users that gave access to your app, you will need to go through the manual subscription process.

• Manual subscription : By using the manual subscription, you can use a different url for each user. To register a webhook, you will need to use the endpoint /addwebhook. You can always drop a webhook using the endpoint /dropwebhook.

Note that it is necessary to authenticate to activate the webhooks for already existing users.

Ban

For security reasons, we want you to use https links for a production application. Only the creator of the application can receive webhooks with a simple http link. The http code returned by your application shall always be ‘200’. If another code is returned more than five times in a row, your webhook will be deactivated during 24 hours. One valid request resets the failing counter of your application.

You must always respond to webhooks quickly. Once you receive a webhook, you only have 10 seconds to respond. To do so, manage your response and your treatment in different threads.

List of events

Events format

Here are the different parameters available for Security products webhooks calls:

NB: sent parameters will depends on the product, eg persons field will only be returned for Indoor Cameras.

Possible actions