Security

API Programs

Data available

Possible actions

Smart Home

Events (motion detected, alarm detected, known and unknown faces)
Snapshots of events
Videos of events*
Live stream*
Camera specific details

Get real time notification of events
Retrieve events
Retrieve timeline of events
Access events videos*
Access live stream*

Summary:

Meet Netatmo's security products
How does it work?
Scopes
Video stream and access
Webhooks
Warning

Meet Netatmo's security products

Netatmo has two kind of cameras:

Welcome is an indoor camera with face recognition capabilities.
Presence is an outdoor security camera with people, car and animal detection capabilities.
Netatmo cameras' users get notified when Welcome senses motions and detects faces or when Presence detects cars, animals or humans.
Each detection is considered an event, and the cameras generate timelines of events (motions, face detected, car detected etc, ...).
Users can choose what they think is relevant to record in their settings (e.g. never record motions but always record unknown faces ...). For Presence, users can also choose in their settings where they want to record. They can select specific areas for alerts, called Alert-Zones. Only the events within these Alert-Zones will be recorded.
Events are recorded and stored locally on the SD card that goes with every camera, depending on those above mentioned preferences. Following a FIFO model, as soon as the SD card is full, the oldest videos get deleted and disappear from users' timelines.
For each event, the camera that generated it takes a snapshot and records a video. The snapshot is displayed in the timeline.
When a fire starts, the Smart Smoke Alarm sounds an 85 dB alarm and sends smartphone alerts in real time to the user’s smartphone.
The Smart Smoke Alarm is equipped with a unique 10-year battery* that covers the product’s entire service life. The device constantly self-checks and immediately alerts the user if an issue arises.
Through the app, users can notably: check their Smart Smoke Alarm’s status, hush the alarm and perform a sound test of the device, as recommended on a yearly basis.
Using Netatmo Smart Home API, you will have the ability to retrieve and browse those events along with their associated snapshots and videos (Netatmo reserves the right to grant third parties' access to the videos).
*Life span for typical use. The battery’s life span may vary based on the use of the Smart Smoke Alarm. More information about the Netatmo security products can be found on Netatmo website.

How does it work?

What is a home?

Security products are designed on a per Home-basis. During intallation, users link their product to a Home. A user can have several products in the same Home and they can have several Homes. For one Home, all the events detected by the products will be aggregated into a timeline of events, there is one timeline per Home.

Timeline of events

Using Netatmo Smart Home API, you can retrieve users' home events and timelines, browse through past events, access videos and event snapshots.
With Presence, users receive customized notifications that match their needs. Users can select specific areas for alerts called Alert-Zones. Only the events within these Alert-Zones can be retrieved.
A Webhook system is available and provides real-time notifications each time an event is detected. Please use the webhooks to keep track of the timelines as unnecessary API calls to check for new events can be considered as abusive.
Read the developer guidelines.

Security events

Events Security products are able to detect:

Event

Product

Description

Person

Welcome

Event triggered when Welcome detects a face

Person_away

Welcome

Event triggered when geofencing implies the person has left the home

Movement

Welcome
Presence

Event triggered when Welcome detects a motion

Outdoor

Presence

Event triggered when Presence detects a human, a car or an animal

Connection

Welcome
Presence

When the camera connects to Netatmo servers

Disconnection

Welcome
Presence

When the camera loses connection to Netatmo servers

Welcome
Presence

Whenever monitoring is resumed

Off

Welcome
Presence

Whenever monitoring is suspended

Boot

Welcome
Presence

When the camera is booting

Welcome
Presence

Event triggered by the SD card status change

Alim

Welcome
Presence

Event triggered by the power supply status change

daily_summary

Presence

Event triggered when the video summary of the last 24 hours is available

new_module

Welcome

A new module has been paired with Welcome

module_connect

Welcome

Module is connected with Welcome (after disconnection)

module_disconnect

Welcome

Module lost its connection with Welcome

module_low_battery

Welcome

Module's battery is low

module_end_update

Welcome

Module's firmware update is over

tag_big_move

Welcome

Tag detected a big move

tag_small_move

Welcome

Tag detected a small move

tag_uninstalled

Welcome

Tag was uninstalled

tag_open

Welcome

Tag detected the door/window was left open

hush

Smoke detector

Whenever the smoke detection is activated or deactivated

smoke

Smoke detector

Whenever smoke is detected or smoke is cleared

tampered

Smoke detector

When the smoke detector is ready or tampered

wifi_status

Smoke detector

When wifi status is updated

battery_status

Smoke detector

When the battery is too low

detection_chamber_status

Smoke detector

When the detection chamber is dusty or clean

sound_test

Smoke detector

Sound test results

For Presence, only events within the Alert-Zones can be retrieved.

Event subtypes

For «Outdoor» events, an «event_list» array is available and provides more details about the event detected by Presence. If several events are detected in the same video (e.g. a car is seen and people come out of it), there will only be one «Outdoor» event and its «event_list» array will contain all of the events detected. Events are aggregated by video.
Event_list subtypes can be:

Event_list subtype

Description

human

Human seen

vehicle

Car seen

animal

Animal seen

For "SD" and "Alim", a "sub_type" value is available and provides details

SD card subtype

Description

missing SD card

SD card inserted

SD card formated

working SD card

defective SD card

incompatible SD card speed

insufficient SD card space

Alim subtypes

Description

incorrect power adapter

correct power adapter

For several Smart Smoke Alarm events, a “sub_type” value is available and provides details

detection_chamber_status subtypes

Description

clean

dusty

battery_status subtypes

Description

low

very low

hush subtypes

Description

ready

hush

smoke subtypes

Description

cleared

detected

sound_test subtypes

Description

error

tampered subtypes

Description

ready

tampered

wifi_status subtypes

Description

error

Scopes

To retrieve data from Netatmo security products, you have to choose between three scopes for Welcome, two scopes for Presence and only one for the Smart Smoke Alarm.

read_camera (for Welcome)

to retrieve events and timelines
to retrieve snapshots

read_smokedetector (for The Smart Smoke Alarm)

to retrieve events and timelines

write_camera (for Welcome)

to tell Welcome a specific person or everybody has left the Home

access_camera (for Welcome) and access_presence (for Presence)

to access the live stream
to access any video stored on the SD card

By default, Welcome apps have access to the scope read_camera, Presence apps to the scope read_presence and Smart Smoke Alarm one to the scope read_smokedetector. The scopes access_camera and access_presence are only for the developer's own camera.
*You need to request the scope access_camera/access_presence to access other user camera.
This scope is granted on a per app basis. As security is one of our main concern and as this scope gives you access to user’s videos, Netatmo will give extra-attention to each request.

Requirements

Provide Netatmo with a high-level workflow diagram of its integration (App / your servers / Netatmo servers)
Logos and Icons should comply with Netatmo branding guidelines.
Authorization code grant type is required for authentication.
User should be able to remove its cameras access from the 3rd party application.
Storing token/refresh token anywhere else than on the user device is not allowed.
Providing video access and streaming capability to anyone else than the authenticated user is not allowed.
Provide Netatmo with a link to pre-production application for review.

Netatmo teams will check that you are compliant with these guidelines and will test your app before granting the access.

To request a scope, you have to be logged in. No account yet? Sign up.

Video stream and access

You can access the video stream only if you have been granted the scope access_camera/access_presence, seeScopes section.
To retrieve the live streaming, you need to call a vpn_url. Each camera has its own vpn_url.
To get this url, use the Gethomedata method.
You can access the camera directly if you are on the same local network. Use the Ping method to check if your app and the camera are on the same network.
To access the video of an event, use the VOD method.

Webhooks

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 method addwebhook. You can always drop a webhook using dropwebhook.

Decoding requests

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

Parameter

Product

Description

device_id