CEMM Open API

Click here for an English version.

 

Authenticatie

De CEMM Open API maakt gebruik van API keys om requests the authenticeren. De API key moet bij elk request meegestuurd worden. Alle API requests worden over HTTPS verstuurd, de API key wordt hierin automatisch versleuteld. Het is belangrijk dat je je API key zelf goed afschermt.

Let op: Iedereen die in het bezit is van je API key kan gegevens opvragen van de gekoppelde CEMM!

Hoe kom ik aan een API key?

Op dit moment is het nog niet mogelijk om in je mijncemm account een API key op te vragen. Een API key kan aangevraagd worden via het contactformulier op deze website.

Verbinden met de Open API

De Open API is te benaderen via https://open-api.cemm.nl/v1/

Nieuw API Promise

De Open API geeft een promise terug als er niet direct op het request gereageerd kan worden. Een promise is een unieke code die na 10 seconden verloopt. De promise geeft aan dat de data opgevraagd wordt van de CEMM. Door het request te herhalen kan de data alsnog opgevraagd worden.

API Endpoints

Alle beschikbare endpoints worden hieronder beschreven. De Open API is nog in BETA fase, API responses kunnen nog worden gewijzigd.

  1. Gekoppelde CEMM apparaten opvragen
  2. I/O van een CEMM opvragen
  3. I/O van een CEMM opvragen via een alias
  4. Realtime data van een I/O opvragen via een alias
  5. Dag data van een I/O opvragen via een alias
  6. Maand data van een I/O opvragen via een alias
  7. Jaar data van een I/O opvragen via een alias
  8. Meterstanden van een I/O opvragen via een alias

 

Aliassen

Om aangesloten meters rechtstreeks op te vragen wordt gebruik gemaakt van aliassen. Op dit moment is het gebruik van een alias de enige methode om een meter te selecteren.

p1 Geeft een aangesloten DSMR slimme meter terug. De slimme meter wordt aangesloten op aansluiting 1.1 van de CEMM
p1-gas  Geeft de aangesloten slimme gas meter terug. De slimme gas meter wordt via de slimme meter aangesloten op de CEMM
s01 Geeft de aangesloten puls meter terug op aansluiting 2 van de CEMM
s02 Geeft de aangesloten puls meter terug op aansluiting 1.2 van de CEMM
s03 Geeft de aangesloten puls meter terug op aansluiting 1.1 van de CEMM

 

MeasurementArray

Een MeasurementArray is een normale array met als eerste element (index 0) de timestamp in milliseconden en als tweede element (index 1) de bijbehorende waarde.

electric_power<MeasurementArray>
  [0]<Integer> # Timestamp in milliseconden
  [1]<Double>  # Sensor waarde

 

Gekoppelde CEMM apparaten opvragen

←Terug naar endpoint overzicht

Deze endpoint geeft een dataset terug met CEMM apparaten die zijn gekoppeld aan de meegezonden API key. De uid van de CEMM wordt gebruikt in andere endpoints om de CEMM te selecteren.

Endpoint
GET cemm/
GET Parameters
api_key De Open API authenticatie key

 

Response

Deze endpoint geeft een JSON object terug. De opmaak van het JSON object wordt hieronder beschreven.

<Object>
  data<Array>
    <Object>
      uid<String> # CEMM mac adres
Response codes
200 OK              # API response zonder errors
202 Accepted        # API kan niet direct een response geven, de API geeft een promise terug
403 Unauthorized    # Geen toegang. API key ongeldig voor deze actie
408 Request Timeout # API kon niet op tijd een response geven
502 Bad Gateway     # Er is een onbekende error opgetreden in de API
Voorbeeld
GET https://open-api.cemm.nl/v1/cemm/?api_key=4e4f657....
{
    "data": [
        {
            "uid": "00-00-00-00-00-00"
        },
        {
            "uid": "FF-FF-FF-FF-FF-FF"
        }
    ]
}

 

I/O van een CEMM opvragen

←Terug naar endpoint overzicht

Deze endpoint geeft een dataset terug met alle geactiveerde I/O. Een I/O beschrijft een meter/sensor of een actuator. Elke meter/sensor die op de CEMM wordt aangesloten krijgt een io_id. Het io_id is een uniek nummer waarmee een I/O geselecteerd kan worden. Een io_id wordt uitgegeven in de volgorde van activeren van I/O. Om een specifieke aansluiting van de CEMM te selecteren wordt gebruik gemaakt van aliassen.

Endpoint
GET cemm/<CEMM UID>/io/
URL Parameters
<CEMM UID> Het mac adres van de CEMM zoals gegeven in het response van de cemm/ endpoint

 

GET Parameters
api_key De Open API authenticatie key

 

Response

Deze endpoint geeft een JSON object terug. De opmaak van het JSON object wordt hieronder beschreven.

<Object>
  data<Array>
    <Object>
      io_id<Integer>      # Id van het I/O
      port<Integer>       # Nummer van de poort waarop de I/O is aangesloten
      type<String>        # Soort I/O
      port_option<String> # Input of Output type
      full_id<Integer>    # Id van de decentrale unit waarop de I/O is aangesloten
Response codes
200 OK              # API response zonder errors
202 Accepted        # API kan niet direct een response geven, de API geeft een promise terug
403 Unauthorized    # Geen toegang. API key ongeldig voor deze actie
408 Request Timeout # API kon niet op tijd een response geven
502 Bad Gateway     # Er is een onbekende error opgetreden in de API
Voorbeeld
GET https://open-api.cemm.nl/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
        }
    ]
}

 

I/O van een CEMM opvragen via een alias

←Terug naar endpoint overzicht

Deze endpoint geeft een dataset terug van het geselecteerde I/O op basis van een alias. Beschikbare aliassen voor deze endpoint: p1, p1-gas, s01, s02, s03

Endpoint
GET cemm/<CEMM UID>/<ALIAS>/
URL Parameters
<CEMM UID> Het mac adres van de CEMM zoals gegeven in het response van de cemm/ endpoint
<ALIAS> De alias voor de op te vragen I/O

 

GET Parameters
api_key De Open API authenticatie key

 

Response

Deze endpoint geeft een JSON object terug. De opmaak van het JSON object wordt hieronder beschreven.

<Object>
  data<Array>
    <Object>
      io_id<Integer>      # Id van het I/O
      port<Integer>       # Nummer van de poort waarop de I/O is aangesloten
      type<String>        # Soort I/O
      port_option<String> # Input of Output type
      full_id<Integer>    # Id van de decentrale unit waarop de I/O is aangesloten
Response codes
200 OK                  # API response zonder errors
202 Accepted            # API kan niet direct een response geven, de API geeft een promise terug
403 Unauthorized        # Geen toegang. API key ongeldig voor deze actie
408 Request Timeout     # API kon niet op tijd een response geven
412 Precondition Failed # Het opgegeven alias wordt niet ondersteund door deze endpoint
502 Bad Gateway         # Er is een onbekende error opgetreden in de API
Voorbeeld
GET https://open-api.cemm.nl/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
        }
    ]
}

 

Realtime data van een I/O opvragen via een alias

←Terug naar endpoint overzicht

Deze endpoint geeft een dataset terug met realtime data van het geselecteerde I/O op basis van een alias. Beschikbare aliassen voor deze endpoint: p1, p1-gas, s01, s02, s03

Endpoint
GET cemm/<CEMM UID>/<ALIAS>/realtime/
URL Parameters
<CEMM UID> Het mac adres van de CEMM zoals gegeven in het response van de cemm/ endpoint
<ALIAS> De alias voor de op te vragen I/O

 

GET Parameters
api_key De Open API authenticatie key

 

Response

Deze endpoint geeft een JSON object terug. De opmaak van het JSON object wordt hieronder beschreven. Het response is afhankelijk van het opgegeven alias. Alle I/O sensor waarden in de API responses worden teruggeven als een MeasurementArray

Response voor aliassen: s01, s02, s03
<Object>
  io_id<Integer> # Id van de opgevraagde I/O
  data<Object>
      electric_power<MeasurementArray>
Response voor alias: p1
<Object>
  io_id<Integer> # Id van de opgevraagde I/O
  data<Object>
      t1<MeasurementArray>
      t2<MeasurementArray>
      t3<MeasurementArray>
      t4<MeasurementArray>
      electric_power<MeasurementArray>
      rate<MeasurementArray>
      switch<MeasurementArray>
      gas<MeasurementArray>
Response voor alias: p1-gas
<Object>
  io_id<Integer> # Id van de opgevraagde I/O
  data<Object>
      gas<MeasurementArray>
Response codes
200 OK                  # API response zonder errors
202 Accepted            # API kan niet direct een response geven, de API geeft een promise terug
403 Unauthorized        # Geen toegang. API key ongeldig voor deze actie
408 Request Timeout     # API kon niet op tijd een response geven
412 Precondition Failed # Het opgegeven alias wordt niet ondersteund door deze endpoint
502 Bad Gateway         # Er is een onbekende error opgetreden in de API
Voorbeeld
GET https://open-api.cemm.nl/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
        ]
    }
}

 

Dag data van een I/O opvragen via een alias

←Terug naar endpoint overzicht

Deze endpoint geeft een dataset terug met alle minuten van de dag van het geselecteerde I/O op basis van een alias. Beschikbare aliassen voor deze endpoint: p1, p1-gas, s01, s02, s03

Let op: De slimme meter update de gas meterstand per uur. Deze endpoint geeft voor p1-gas geen minuten terug maar uren.

Endpoint
GET cemm/<CEMM UID>/<ALIAS>/data/day/
URL Parameters
<CEMM UID> Het mac adres van de CEMM zoals gegeven in het response van de cemm/ endpoint
<ALIAS> De alias voor de op te vragen I/O

 

GET Parameters
api_key De Open API authenticatie key
time Timestamp in seconden van de dag (mag elk moment zijn tussen 00:00 en 23:59)

 

Response

Deze endpoint geeft een JSON object terug. De opmaak van het JSON object wordt hieronder beschreven. Het response is afhankelijk van het opgegeven alias. Alle I/O sensor waarden in de API responses worden teruggeven als een MeasurementArray

Response voor aliassen: p1, s01, s02, s03
<Object>
  io_id<Integer> # Id van de opgevraagde I/O
  time<Integer>  # Timestamp van de opgevraagde dag in milliseconden
  data<Object>
      electric_power<Array>
        0<MeasurementArray>
        .
        .
        1439<MeasurementArray>
Response voor alias: p1-gas (DSMR 3.x en DSMR 4.x)
<Object>
  io_id<Integer> # Id van de opgevraagde I/O
  time<Integer>  # Timestamp van de opgevraagde dag in milliseconden
  data<Object>
      gas<Array>
        0<MeasurementArray>
        .
        .
        23<MeasurementArray>
Response voor alias: p1-gas (DSMR 5.x)

DSMR5.x slimme meters updaten de gas meterstand elke 5 minuten. Dit geeft de CEMM de mogelijkheid om het gasverbruik in L/min. te berekenen.

<Object>
  io_id<Integer> # Id van de opgevraagde I/O
  time<Integer>  # Timestamp van de opgevraagde dag in milliseconden
  data<Object>
      gas<Array>
        0<MeasurementArray>
        .
        .
        1440<MeasurementArray>
Response codes
200 OK                  # API response zonder errors
202 Accepted            # API kan niet direct een response geven, de API geeft een promise terug
403 Unauthorized        # Geen toegang. API key ongeldig voor deze actie
408 Request Timeout     # API kon niet op tijd een response geven
412 Precondition Failed # Het opgegeven alias wordt niet ondersteund door deze endpoint
502 Bad Gateway         # Er is een onbekende error opgetreden in de API
Voorbeeld
GET https://open-api.cemm.nl/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
            ]
        ]
    }
}

 

Maand data van een I/O opvragen via een alias

←Terug naar endpoint overzicht

Deze endpoint geeft een dataset terug met alle dagen van de maand van het geselecteerde I/O op basis van een alias. Beschikbare aliassen voor deze endpoint: p1, p1-gas, s01, s02, s03

Endpoint
GET cemm/<CEMM UID>/<ALIAS>/data/month/
URL Parameters
<CEMM UID> Het mac adres van de CEMM zoals gegeven in het response van de cemm/ endpoint
<ALIAS> De alias voor de op te vragen I/O

 

GET Parameters
api_key De Open API authenticatie key
time Timestamp in seconden van de maand (mag elk willekeurig moment zijn in de maand)

 

Response

Deze endpoint geeft een JSON object terug. De opmaak van het JSON object wordt hieronder beschreven. Het response is afhankelijk van het opgegeven alias. Alle I/O sensor waarden in de API responses worden teruggeven als een MeasurementArray

Response voor aliassen: p1, s01, s02, s03
<Object>
  io_id<Integer> # Id van de opgevraagde I/O
  time<Integer>  # Timestamp van de opgevraagde maand in milliseconden
  data<Object>
      electric_energy_low<Array>
        0<MeasurementArray>
        .
        .
        30<MeasurementArray> # Lengte van de Array is afhankelijk van de maand

      electric_energy_high<Array>
        0<MeasurementArray>
        .
        .
        30<MeasurementArray> # Lengte van de Array is afhankelijk van de maand
Response voor alias: p1-gas
<Object>
  io_id<Integer> # Id van de opgevraagde I/O
  time<Integer>  # Timestamp van de opgevraagde maand in milliseconden
  data<Object>
      gas<Array>
        0<MeasurementArray>
        .
        .
        30<MeasurementArray> # Lengte van de Array is afhankelijk van de maand
Response codes
200 OK                  # API response zonder errors
202 Accepted            # API kan niet direct een response geven, de API geeft een promise terug
403 Unauthorized        # Geen toegang. API key ongeldig voor deze actie
408 Request Timeout     # API kon niet op tijd een response geven
412 Precondition Failed # Het opgegeven alias wordt niet ondersteund door deze endpoint
502 Bad Gateway         # Er is een onbekende error opgetreden in de API
Voorbeeld
GET https://open-api.cemm.nl/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
            ]
        ]
    }
}

 

Jaar data van een I/O opvragen via een alias

←Terug naar endpoint overzicht

Deze endpoint geeft een dataset terug met alle maanden van het jaar van het geselecteerde I/O op basis van een alias. Beschikbare aliassen voor deze endpoint: p1, p1-gas, s01, s02, s03

Endpoint
GET cemm/<CEMM UID>/<ALIAS>/data/year/
URL Parameters
<CEMM UID> Het mac adres van de CEMM zoals gegeven in het response van de cemm/ endpoint
<ALIAS> De alias voor de op te vragen I/O

 

GET Parameters
api_key De Open API authenticatie key
time Timestamp in seconden van het jaar (mag elk willekeurig moment zijn in het jaar)

 

Response

Deze endpoint geeft een JSON object terug. De opmaak van het JSON object wordt hieronder beschreven. Het response is afhankelijk van het opgegeven alias. Alle I/O sensor waarden in de API responses worden teruggeven als een MeasurementArray

Response voor aliassen: p1, s01, s02, s03
<Object>
  io_id<Integer> # Id van de opgevraagde I/O
  time<Integer>  # Timestamp van het opgevraagde jaar in milliseconden
  data<Object>
      electric_energy_low<Array>
        0<MeasurementArray>
        .
        .
        11<MeasurementArray>

      electric_energy_high<Array>
        0<MeasurementArray>
        .
        .
        11<MeasurementArray>
Response voor alias: p1-gas
<Object>
  io_id<Integer> # Id van de opgevraagde I/O
  time<Integer>  # Timestamp van het opgevraagde jaar in milliseconden
  data<Object>
      gas<Array>
        0<MeasurementArray>
        .
        .
        11<MeasurementArray>
Response codes
200 OK                  # API response zonder errors
202 Accepted            # API kan niet direct een response geven, de API geeft een promise terug
403 Unauthorized        # Geen toegang. API key ongeldig voor deze actie
408 Request Timeout     # API kon niet op tijd een response geven
412 Precondition Failed # Het opgegeven alias wordt niet ondersteund door deze endpoint
502 Bad Gateway         # Er is een onbekende error opgetreden in de API
Voorbeeld
GET https://open-api.cemm.nl/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
            ]
        ]
    }
}

 

Meterstanden van een I/O opvragen via een alias

←Terug naar endpoint overzicht

Deze endpoint geeft een dataset terug met de laatst bekende meterstand van de dag van het geselecteerde I/O op basis van een alias. Beschikbare aliassen voor deze endpoint: p1, p1-gas, s01, s02, s03

Endpoint
GET cemm/<CEMM UID>/<ALIAS>/totals/
URL Parameters
<CEMM UID> Het mac adres van de CEMM zoals gegeven in het response van de cemm/ endpoint
<ALIAS> De alias voor de op te vragen I/O

 

GET Parameters
api_key De Open API authenticatie key
time Timestamp in seconden van de dag (mag elk willekeurig moment zijn van de dag)

 

Response

Deze endpoint geeft een JSON object terug. De opmaak van het JSON object wordt hieronder beschreven. Het response is afhankelijk van het opgegeven alias. Alle I/O sensor waarden in de API responses worden teruggeven als een MeasurementArray

Response voor aliassen: s01, s02, s03
<Object>
  io_id<Integer> # Id van de opgevraagde I/O
  time<Integer>  # Timestamp van de opgevraagde dag in milliseconden
  data<Object>
    electric_energy<MeasurementArray>
    electric_energy_high<MeasurementArray>
Response voor alias: p1
<Object>
  io_id<Integer> # Id van de opgevraagde I/O
  time<Integer>  # Timestamp van de opgevraagde dag in milliseconden
  data<Object>
    t1<MeasurementArray>
    t2<MeasurementArray>
    t3<MeasurementArray>
    t4<MeasurementArray>
    electric_energy<MeasurementArray>
    electric_energy_high<MeasurementArray>
    gas<MeasurementArray>
Response voor alias: p1-gas
<Object>
  io_id<Integer> # Id van de opgevraagde I/O
  time<Integer>  # Timestamp van de opgevraagde dag in milliseconden
  data<Object>
      gas<MeasurementArray>
Response codes
200 OK                  # API response zonder errors
202 Accepted            # API kan niet direct een response geven, de API geeft een promise terug
403 Unauthorized        # Geen toegang. API key ongeldig voor deze actie
408 Request Timeout     # API kon niet op tijd een response geven
412 Precondition Failed # Het opgegeven alias wordt niet ondersteund door deze endpoint
502 Bad Gateway         # Er is een onbekende error opgetreden in de API
Voorbeeld
GET https://open-api.cemm.nl/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
    ]
  }
}

 

Leave a Reply