Authentication
The CEMM Open API uses API keys to authenticate requests. The API key must be send with each request. All API requests are sent over HTTPS, this will automatically encrypt the API key. It is important that you keep your API key safe.
Caution: Everyone with access to your API key is able to request data from any linked CEMM!
How to obtain an API key?
At this time it is not possible to request your API key using your MyCEMM account. However, you can request an API key using the contact form on this website.
Connecting to the Open API
The Open API can be reached at: https://open-api.cemm.nl/v1/
API Promise
The Open API returns a promise when it is unable to immediately fulfill the request. A promise is a unique identifier which expires after 10 seconds. The promise indicates that data is being requested from the CEMM. By repeating the request, the data can still be obtained.
API Endpoints
All available endpoints are described below. The Open API is still in a BETA phase, API responses may be subject to change.
- Request linked CEMMs
- Request an I/O of a CEMM
- Request an I/O of a CEMM using an alias
- Requesting realtime data of a I/O using an alias
- Request daily data of an I/O using an alias
- Request monthly data of an I/O using an alias
- Request yearly data of an I/O using an alias
- Request meter readings of an I/O using an alias
Aliases
Aliases are used to directly address connected meters (I/O). At this point in time it is only possible to select an I/O using an alias.
p1 | Returns the connected DSMR smart meter. The smart meter is connected to connection 1.1 of the CEMM |
han | Returns the connected AMS HAN meter. The smart meter is connected to connection 1.1 of the CEMM using a HAN converter |
p1-gas | Returns the connected smart gas meter. The smart gas meter is connected via the smart meter to the CEMM |
s01 | Returns the connected pulse meter on connection 2 of the CEMM |
s02 | Returns the connected pulse meter on connection 1.2 of the CEMM |
s03 | Returns the connected pulse meter on connection 1.1 of the CEMM |
MeasurementArray
A MeasurementArray is a regular array with a timestamp in milliseconds at index 0 and the corresponding value at index 1.
electric_power<MeasurementArray> [0]<Integer> # Timestamp in milliseconds [1]<Double> # Sensor value
Request linked CEMMs
←Back to the endpoint overview
This endpoint returns a dataset of CEMMs that are linked to the API key that was sent. The uid of a CEMM will be used in other endpoints to select that particular CEMM.
Endpoint
GET cemm/
GET Parameters
api_key | The Open API authentication key |
Response
This endpoint returns a JSON object. The structure of the JSON object is illustrated below.
<Object> data<Array> <Object> uid<String> # CEMM mac address
Response codes
200 OK # Successful API response without errors 202 Accepted # API is unable to immediately fulfill the request, the API returns a promise 403 Unauthorized # Access denied. API key invalid for this action 408 Request Timeout # API was unable to respond on time 502 Bad Gateway # An unexpected error occurred in the API
Example
GET https://mijn.cemm.nl/open-api/v1/cemm/?api_key=4e4f657....
{ "data": [ { "uid": "00-00-00-00-00-00" }, { "uid": "FF-FF-FF-FF-FF-FF" } ] }
Request an I/O of a CEMM
←Back to the endpoint overview
This endpoint returns all activated I/Os. An I/O describes a meter/sensor or actuator. Each meter/sensor that is connected to the CEMM is assigned an io_id. The io_id is a unique number that can be used to select the I/O. The io_id is assigned in the order the I/Os are activated. To select a specific connection of the CEMM an alias is used.
Endpoint
GET cemm/<CEMM UID>/io/
URL Parameters
<CEMM UID> | The mac address of the CEMM as returned by the cemm/ endpoint |
GET Parameters
api_key | The Open API authentication key |
Response
This endpoint returns a JSON object. The structure of the JSON object is illustrated below.
<Object> data<Array> <Object> io_id<Integer> # Id of the I/O port<Integer> # Port number to which the I/O is connected type<String> # I/O type port_option<String> # Input or Output type full_id<Integer> # Id of the decentralized unit to which the I/O is connected
Response codes
200 OK # Successful API response without errors 202 Accepted # API is unable to immediately fulfill the request, the API returns a promise 403 Unauthorized # Access denied. API key invalid for this action 408 Request Timeout # API was unable to respond on time 502 Bad Gateway # An unexpected error occurred in the API
Example
GET https://mijn.cemm.nl/open-api/v1/cemm/FF-FF-FF-FF-FF-FF/io/?api_key=4e4f657....
{ "data":[ { "io_id":1, "port":3, "type":"p1", "port_option":"p1_in", "full_id":16384 }, { "io_id":2, "port":3, "type":"gas", "port_option":"enabled", "full_id":16384 }, { "io_id":3, "port":1, "type":"solar_energy", "port_option":"s0_in", "full_id":16384 } ] }
Request an I/O of a CEMM using an alias
←Back to the endpoint overview
This endpoint returns info about the I/O selected by alias. Available aliases for this endpoint are: p1, p1-gas, s01, s02, s03
Endpoint
GET cemm/<CEMM UID>/<ALIAS>/
URL Parameters
<CEMM UID> | The mac address of the CEMM as returned by the cemm/ endpoint |
<ALIAS> | The alias for the I/O to be requested |
GET Parameters
api_key | The Open API authentication key |
Response
This endpoint returns a JSON object. The structure of the JSON object is illustrated below.
<Object> data<Array> <Object> io_id<Integer> # Id of the I/O port<Integer> # Port number to which the I/O is connected type<String> # I/O type port_option<String> # Input or Output type full_id<Integer> # Id of the decentralized unit to which the I/O is connected
Response codes
200 OK # Successful API response without errors 202 Accepted # API is unable to immediately fulfill the request, the API returns a promise 403 Unauthorized # Access denied. API key invalid for this action 408 Request Timeout # API was unable to respond on time 412 Precondition Failed # The specified alias is not supported by this endpoint 502 Bad Gateway # An unexpected error occurred in the API
Example
GET https://mijn.cemm.nl/open-api/v1/cemm/FF-FF-FF-FF-FF-FF/p1/?api_key=4e4f657....
{ "data":[ { "io_id":1, "port":3, "type":"p1", "port_option":"p1_in", "full_id":16384 } ] }
Requesting realtime data of a I/O using an alias
←Back to the endpoint overview
This endpoint returns a dataset with realtime data for the I/O selected by alias. Available aliases for this endpoint are: p1, p1-gas, s01, s02, s03
Endpoint
GET cemm/<CEMM UID>/<ALIAS>/realtime/
URL Parameters
<CEMM UID> | The mac address of the CEMM as returned by the cemm/ endpoint |
<ALIAS> | The alias for the I/O to be requested |
GET Parameters
api_key | The Open API authentication key |
Response
This endpoint returns a JSON object. The structure of the JSON object is illustrated below. The response depends on the requested alias. All I/O sensor values in the API responses are returned as a MeasurementArray
Response for aliases: s01, s02, s03
<Object> io_id<Integer> # Id of the requested I/O data<Object> electric_power<MeasurementArray>
Response for alias: p1
<Object> io_id<Integer> # Id of the requested I/O data<Object> t1<MeasurementArray> t2<MeasurementArray> t3<MeasurementArray> t4<MeasurementArray> electric_power<MeasurementArray> rate<MeasurementArray> switch<MeasurementArray> gas<MeasurementArray>
Response for alias: p1-gas
<Object> io_id<Integer> # Id of the requested I/O data<Object> gas<MeasurementArray>
Response codes
200 OK # Successful API response without errors 202 Accepted # API is unable to immediately fulfill the request, the API returns a promise 403 Unauthorized # Access denied. API key invalid for this action 408 Request Timeout # API was unable to respond on time 412 Precondition Failed # The specified alias is not supported by this endpoint 502 Bad Gateway # An unexpected error occurred in the API
Example
GET https://mijn.cemm.nl/open-api/v1/cemm/FF-FF-FF-FF-FF-FF/p1/realtime/?api_key=4e4f657....
{ "io_id":1, "data":{ "t1":[ 1496326765000, 1351 ], "t2":[ 1496326765000, 1614 ], "t3":[ 1496326765000, 883 ], "t4":[ 1496326765000, 2018 ], "electric_power":[ 1496326765000, -1607 ], "rate":[ 1496326765000, 2 ], "switch":[ 0, 0 ], "gas":[ 1496326765000, 2617 ] } }
Request daily data of an I/O using an alias
←Back to the endpoint overview
This endpoint returns a dataset containing all minutes of the day for the selected I/O by alias. Available aliases for this endpoint are: p1, p1-gas, s01, s02, s03
Caution: The smart meter updates the gas meter reading only once an hour. This endpoint returns data in hours instead of minutes for p1-gas.
Endpoint
GET cemm/<CEMM UID>/<ALIAS>/data/day/
URL Parameters
<CEMM UID> | The mac address of the CEMM as returned by the cemm/ endpoint |
<ALIAS> | The alias for the I/O to be requested |
GET Parameters
api_key | The Open API authentication key |
time | Timestamp of the day in seconds (can be any moment between 00:00 and 23:59) |
Response
This endpoint returns a JSON object. The structure of the JSON object is illustrated below. The response depends on the requested alias. All I/O sensor values in the API responses are returned as a MeasurementArray
Response for aliases: p1, s01, s02, s03
<Object> io_id<Integer> # Id of the requested I/O time<Integer> # Timestamp of the requested day in milliseconds data<Object> electric_power<Array> 0<MeasurementArray> . . 1439<MeasurementArray>
Response for alias: p1-gas (DSMR 3.x and DSMR 4.x)
<Object> io_id<Integer> # Id of the requested I/O time<Integer> # Timestamp of the requested day in milliseconds data<Object> gas<Array> 0<MeasurementArray> . . 23<MeasurementArray>
Response for alias: p1-gas (DSMR 5.x)
DSMR5.x smart meters update the gas meter reading every 5 minutes. This allows the CEMM to calculate the gas usage in L/min.
<Object> io_id<Integer> # Id of the requested I/O time<Integer> # Timestamp of the requested day in milliseconds data<Object> gas<Array> 0<MeasurementArray> . . 1440<MeasurementArray>
Response codes
200 OK # Successful API response without errors 202 Accepted # API is unable to immediately fulfill the request, the API returns a promise 403 Unauthorized # Access denied. API key invalid for this action 408 Request Timeout # API was unable to respond on time 412 Precondition Failed # The specified alias is not supported by this endpoint 502 Bad Gateway # An unexpected error occurred in the API
Example
GET https://mijn.cemm.nl/open-api/v1/cemm/FF-FF-FF-FF-FF-FF/p1-gas/data/day/?time=1496242535&api_key=4e4f657....
{ "io_id":2, "time":1496242535000, "data":{ "gas":[ [ 1496267999000, 0 ], [ 1496264400000, 0.14208984375 ], . . . [ 1496185200000, 0 ], [ 1496181600000, 0.0009765625 ] ] } }
Request monthly data of an I/O using an alias
←Back to the endpoint overview
This endpoint returns a dataset containing all days of the month for the selected I/O by alias. Available aliases for this endpoint are: p1, p1-gas, s01, s02, s03
Endpoint
GET cemm/<CEMM UID>/<ALIAS>/data/month/
URL Parameters
<CEMM UID> | The mac address of the CEMM as returned by the cemm/ endpoint |
<ALIAS> | The alias for the I/O to be requested |
GET Parameters
api_key | The Open API authentication key |
time | Timestamp of the month in seconds (can be any moment in the month) |
Response
This endpoint returns a JSON object. The structure of the JSON object is illustrated below. The response depends on the requested alias. All I/O sensor values in the API responses are returned as a MeasurementArray
Response for aliases: p1, s01, s02, s03
<Object> io_id<Integer> # Id of the requested I/O time<Integer> # Timestamp of the requested month in milliseconds data<Object> electric_energy_low<Array> 0<MeasurementArray> . . 30<MeasurementArray> # Length of the Array depends on the month electric_energy_high<Array> 0<MeasurementArray> . . 30<MeasurementArray> # Length of the Array depends on the month
Response for alias: p1-gas
<Object> io_id<Integer> # Id of the requested I/O time<Integer> # Timestamp of the requested month in milliseconds data<Object> gas<Array> 0<MeasurementArray> . . 30<MeasurementArray> # Length of the Array depends on the month
Response codes
200 OK # Successful API response without errors 202 Accepted # API is unable to immediately fulfill the request, the API returns a promise 403 Unauthorized # Access denied. API key invalid for this action 408 Request Timeout # API was unable to respond on time 412 Precondition Failed # The specified alias is not supported by this endpoint 502 Bad Gateway # An unexpected error occurred in the API
Example
GET https://mijn.cemm.nl/open-api/v1/cemm/FF-FF-FF-FF-FF-FF/p1-gas/data/month/?time=1496242535&api_key=4e4f657....
{ "io_id":2, "time":1496242535000, "data":{ "gas":[ [ 1496181600000, 0.60400390625 ], [ 1496095200000, 0.534912109375 ], . . . [ 1493676000000, 0.003173828125 ], [ 1493589600000, 0.0029296875 ] ] } }
Request yearly data of an I/O using an alias
←Back to the endpoint overview
This endpoint returns a dataset containing all months of the year for the selected I/O by alias. Available aliases for this endpoint are: p1, p1-gas, s01, s02, s03
Endpoint
GET cemm/<CEMM UID>/<ALIAS>/data/year/
URL Parameters
<CEMM UID> | The mac address of the CEMM as returned by the cemm/ endpoint |
<ALIAS> | The alias for the I/O to be requested |
GET Parameters
api_key | The Open API authentication key |
time | Timestamp of the year in seconds (can be any moment of the year) |
Response
This endpoint returns a JSON object. The structure of the JSON object is illustrated below. The response depends on the requested alias. All I/O sensor values in the API responses are returned as a MeasurementArray
Response for aliases: p1, s01, s02, s03
<Object> io_id<Integer> # Id of the requested I/O time<Integer> # Timestamp of the requested year in milliseconds data<Object> electric_energy_low<Array> 0<MeasurementArray> . . 11<MeasurementArray> electric_energy_high<Array> 0<MeasurementArray> . . 11<MeasurementArray>
Response for alias: p1-gas
<Object> io_id<Integer> # Id of the requested I/O time<Integer> # Timestamp of the requested year in milliseconds data<Object> gas<Array> 0<MeasurementArray> . . 11<MeasurementArray>
Response codes
200 OK # Successful API response without errors 202 Accepted # API is unable to immediately fulfill the request, the API returns a promise 403 Unauthorized # Access denied. API key invalid for this action 408 Request Timeout # API was unable to respond on time 412 Precondition Failed # The specified alias is not supported by this endpoint 502 Bad Gateway # An unexpected error occurred in the API
Example
GET https://mijn.cemm.nl/open-api/v1/cemm/FF-FF-FF-FF-FF-FF/p1-gas/data/year/?time=1496242535&api_key=4e4f657....
{ "io_id":2, "time":1496242535000, "data":{ "gas":[ [ 1512082800000, 0 ], . . . [ 1488322800000, 144.4921875 ], [ 1485903600000, 229.00390625 ], [ 1483225200000, 281.623046875 ] ] } }
Request meter readings of an I/O using an alias
←Back to the endpoint overview
This endpoint returns a dataset with the last known meter reading of the day for the selected I/O by alias. Available aliases for this endpoint are: p1, p1-gas, s01, s02, s03
Endpoint
GET cemm/<CEMM UID>/<ALIAS>/totals/
URL Parameters
<CEMM UID> | The mac address of the CEMM as returned by the cemm/ endpoint |
<ALIAS> | The alias for the I/O to be requested |
GET Parameters
api_key | The Open API authentication key |
time | Timestamp of the day in seconds (can be any moment of the day) |
Response
This endpoint returns a JSON object. The structure of the JSON object is illustrated below. The response depends on the requested alias. All I/O sensor values in the API responses are returned as a MeasurementArray
Response for aliases: s01, s02, s03
<Object> io_id<Integer> # Id of the requested I/O time<Integer> # Timestamp of the requested day in milliseconds data<Object> electric_energy<MeasurementArray> electric_energy_high<MeasurementArray>
Response for alias: p1
<Object> io_id<Integer> # Id of the requested I/O time<Integer> # Timestamp of the requested day in milliseconds data<Object> t1<MeasurementArray> t2<MeasurementArray> t3<MeasurementArray> t4<MeasurementArray> electric_energy<MeasurementArray> electric_energy_high<MeasurementArray> gas<MeasurementArray>
Response for alias: p1-gas
<Object> io_id<Integer> # Id of the requested I/O time<Integer> # Timestamp of the requested day in milliseconds data<Object> gas<MeasurementArray>
Response codes
200 OK # Successful API response without errors 202 Accepted # API is unable to immediately fulfill the request, the API returns a promise 403 Unauthorized # Access denied. API key invalid for this action 408 Request Timeout # API was unable to respond on time 412 Precondition Failed # The specified alias is not supported by this endpoint 502 Bad Gateway # An unexpected error occurred in the API
Example
GET https://mijn.cemm.nl/open-api/v1/cemm/FF-FF-FF-FF-FF-FF/p1/totals/?time=1496242535&api_key=4e4f657....
{ "io_id": 1, "time": 1496242535000, "data": { "t1": [ 1496242500000, 1350.5639648438 ], "t2": [ 1496242500000, 1612.3809814453 ], "t3": [ 1496242500000, 883.86798095703 ], "t4": [ 1496242500000, 2005.5209960938 ], "electric_energy": [ 1496242500000, 466.6960144043 ], "electric_energy_high": [ 1496242500000, -393.11401367188 ], "gas": [ 1496242500000, 2616.8449707031 ] } }