API (English)

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.

  1. Request linked CEMMs
  2. Request an I/O of a CEMM
  3. Request an I/O of a CEMM using an alias
  4. Requesting realtime data of a I/O using an alias
  5. Request daily data of an I/O using an alias
  6. Request monthly data of an I/O using an alias
  7. Request yearly data of an I/O using an alias
  8. 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
    ]
  }
}