Energy API Documentation
This page presents the APIs related to Energy devices, i.e. the devices that can be controlled using the Energy App.
The presentation of the API is structured with the following topics:
The available products with their ID and a summary of the available data & actions
The endpoints to get & modify the products configuration.
The endpoints to diagnose the state of the devices
The endpoints to get data from the devices
Products
The Energy devices communicate in radio with the gateway (the thermostat relay) that connects them to Netatmo's cloud.
Product | Product type | Data available | Possible action |
|---|---|---|---|
Thermostat Relay | NAPlug NATherm1 NRV | Device information (FW version, Radio/Wifi status & setup date) Current Temperature Temperature configurations (Setpoint & schedules) Boiler activity | Modify the home/room heating configuration Modify the temperature in a room Modify the schedules |
Gateways / Modules
Configuration
The notion of topology is detailed in the Glossary. If you are unfamiliar with this notion in Netatmo’s API, we recommend to take a moment to read about it.
As every heating device belong to a room, when setting a room temperature, it also sets the setpoint temperature of all the Energy devices in the room. Hence, configuring a room temperature is equivalent to configuring the heating devices of the room. For instance if there are several valves in a room, when setting the room temperature, it updates the temperature of all the valves in the room.
Get configuration
Here is the list of configurations that can be retrieved from Energy devices.
Configuration | Description | Product type | Endpoint |
|---|---|---|---|
Software version | Software version of a device | NAPlug, NRV, NATherm1 | /homestatus |
Valve boost mode | Boost mode is activated when a setpoint temperature is manually set to a temperature higher than the current temperature | NRV, NATherm1 | |
Open Window mode | “Open Window” mode prevents from heating when a window is open | NRV, NATherm1 | |
Anticipated heating mode | “Anticipate heating” mode starts/stops heating to reach a scheduled temperature | - (Home level) | |
Room heating mode | A room can be in scheduled / manual / away mode | NRV, NATherm1 | |
Heating schedules | Temperature schedules that set the temperature per room on a weekly schedule | NRV, NATherm1 | |
Manual heating duration | Duration of setpoint temperature when set manually | NRV, NATherm1 | |
Home heating mode | A home can be in schedule, away, frostguard modes | - (Home level) | |
Setpoint temperature | Get the setpoint temperature of a room | NRV, NATherm1 |
Modify configuration
Here is the list of the Energy devices configurations that can be modified.
Configuration | Description | Product type | Endpoint |
|---|---|---|---|
Room Heating configuration | A room can be in manual / max / home mode | NRV, NATherm1 | |
Create a new home schedule | Creating a new home heating schedule | NRV, NATherm1 | |
Modify the current schedule | Modifying the current heating schedule | NRV, NATherm1 | |
Modify an existing schedule | Modifying an existing heating schedule | NRV, NATherm1 | |
Selecting another schedule | Switching to an existing heating schedule | NRV, NATherm1 | |
Heating mode of a home | A home can be in schedule, away, frostguard modes | NRV, NATherm1 | |
Setpoint temperature | Setting the temperature of a room | NRV, NATherm1 |
Heating schedules
Energy devices can be controlled via heating schedules that define their weekly temperature schedule.
Heating schedules have a specific format and are detailed in the Glossary page.
Diagnostic
There are some parameters that can help to diagnose or anticipate the disfunction of an Energy device.
Diagnose
Diagnostic | Description | Product type | Endpoint |
|---|---|---|---|
Radio status | Diagnose the radio strength | NAPlug, NRV, NATherm1 | /homestatus |
Wifi status | Diagnose the wifi strength | NAPlug | |
Setup | Diagnose the last setup date | NAPlug, NRV, NATherm1 | |
Room reachable | Diagnose if a room is reachable to modify its temperature | NRV, NATherm1 |
Available data
Energy devices have temperature sensors. It is possible to retrieve the historic of these data.
Data
Data | Description | Product type | Endpoint |
|---|---|---|---|
Boiler Status | Knowing if the boiler is currently activated by a heating control device | NRV, NATherm1 | /homestatus |
Current temperature of a room | Getting the current temperature of a room | NRV, NATherm1 | |
Historic temperatures of a room | Get the historic of the temperatures of a room (historic of temperature, min/max temperature, dates of min/max temperature, ...) | NRV, NATherm1 | |
Heating power requested by a room | Get the heating power requested by a room | NRV | |
Historic of boiler activity | Get the historic boiler activity (mean activity or cumulated activity) | NRV, NATherm1 |