Ga naar inhoud

Openbare API

De openbare API maakt het mogelijk om data van de CEMM op te halen. De API is beschikbaar voor iedereen die lokaal toegang heeft tot een CEMM. De API is beschikbaar op het lokale IP-adres van de CEMM (poort 80). Als de lokale rol is ingesteld op "Geen toegang" zal de API niet beschikbaar zijn.

Endpoints

Onderstaande endpoints verwachten een HTTP GET request en geven een JSON-response terug.

CEMM informatie

Dit endpoint geeft algemene informatie over de CEMM. Zie onderstaand voorbeeld voor de beschikbare velden.

Endpoint: /api/v1/public/cemm

Voorbeeld

{
  "id": 24000293,
  "name": "Development",
  "icon": "building",
  "icon_color": "#CF2D27",
  "mac": "80:1F:12:47:06:B0",
  "local_ip": "192.168.2.34",
  "version": "1.10.0",
  "timezone": "Europe/Amsterdam",
  "time": 1736428623,
  "modules": [
    "webhooks",
    "smartmeter",
    "pulse",
    "shelly",
    "weather",
    "mqtt"
  ],
  "currency": "EUR"
}

Meters

Dit endpoint geeft een lijst terug van alle ingestelde meters en bijbehorende kanalen. Iedere meter en kanaal heeft een id en key. De combinatie van meter ID/key en kanaal ID/key is uniek. Deze IDs of keys komen terug in de endpoints waar data wordt opgehaald.

Het label van de meter en kanaal kan worden ingesteld via de Instellingen > Meters pagina in de CEMM.

Het type en role van de meter geeft aan om wat voor soort meter het gaat, zie Meters rollen voor meer informatie.

De unit van het kanaal geeft aan in welke eenheid de data wordt weergegeven. Dit geldt voor alle waardes die via de API voor dit kanaal worden opgehaald.

De aggregation_method geeft aan hoe de gegevens van het kanaal in de CEMM worden verwerkt. Dit bepaalt onder andere welke topics beschikbaar zijn voor dit kanaal.

Endpoint: /api/v1/public/meters

Voorbeeld

{
  "meters": [
    {
      "id": 1,
      "key": "hoofdmeter",
      "label": "Hoofdmeter",
      "type": "electricity",
      "role": "grid-connection",
      "channels": [
        {
          "id": 1,
          "key": "electric_power_import",
          "label": "Vermogen afname",
          "unit": "W",
          "aggregation_method": "AVG"
        },
        {
          "id": 2,
          "key": "electric_power_export",
          "label": "Vermogen teruglevering",
          "unit": "W",
          "aggregation_method": "AVG"
        },
        {
          "id": 3,
          "key": "electric_energy_import",
          "label": "Energy afname",
          "unit": "kWh",
          "aggregation_method": "COUNTER"
        },
        {
          "id": 4,
          "key": "electric_energy_export",
          "label": "Energie teruglevering",
          "unit": "kWh",
          "aggregation_method": "COUNTER"
        },
        {
          "id": 8,
          "key": "electric_usage_power",
          "label": "Elektrisch verbruik vermogen",
          "unit": "W",
          "aggregation_method": "CALCULATED"
        },
        {
          "id": 9,
          "key": "electric_usage_energy",
          "label": "Elektrisch verbruik energie",
          "unit": "kWh",
          "aggregation_method": "CALCULATED"
        }
      ]
    },
    {
      "id": 2,
      "key": "koelkast",
      "label": "Koelkast",
      "type": "electricity",
      "role": "usage",
      "channels": [
        {
          "id": 11,
          "key": "electric_power",
          "label": "Vermogen",
          "unit": "W",
          "aggregation_method": "AVG"
        },
        {
          "id": 12,
          "key": "electric_energy",
          "label": "Energie",
          "unit": "kWh",
          "aggregation_method": "COUNTER"
        }
      ]
    }
  ]
}

Status

Via dit endpoint kunnen de meest recente waardes van de kanalen worden opgevraagd. Per kanaal en topic wordt de waarde en het tijdstip van de meting teruggegeven.

Endpoint: /api/v1/public/status

Query parameters

  • topics (optioneel) een komma gescheiden lijst van topics die opgehaald moeten worden. Zonder deze optie worden alle topics teruggegeven.
  • channels (optioneel) een komma gescheiden lijst van kanalen die opgehaald moeten worden. Zonder deze optie worden alle kanalen teruggegeven. Een kanaal kan worden opgegeven als numeriek ID of in formaat <NODE_KEY>:<CHANNEL_KEY>.
  • identifiers (optioneel) bepaalt de manier waarop het resultaat wordt georganiseerd. Er zijn twee opties: key (standaard) of id. Zie het voorbeeld hieronder.

Voorbeeld

In dit voorbeeld worden twee topics opgevraagd, namelijk realtime en this/day voor twee kanalen van de meter hoofdmeter.

/api/v1/public/status?topics=realtime,this/day&channels=hoofdmeter:electric_power_import,hoofdmeter:electric_power_export

Door gebruik te maken van numerieke IDs kan hetzelfde resultaat worden bereikt. De URL ziet er dan als volgt uit:

/api/v1/public/status?topics=realtime,this/day&channels=11,12

{
  "data": {
    "hoofdmeter": {
      "electric_power_import": {
        "realtime": {
          "value": 22.523246705532074,
          "time": 1736435099
        },
        "this/day": {
          "value": 3779.210578232764,
          "time": 1736434980
        }
      },
      "electric_power_export": {
        "realtime": {
          "value": 276.95832401514053,
          "time": 1736435099
        },
        "this/day": {
          "value": 33.39675388706475,
          "time": 1736434980
        }
      }
    }
  }
}

Voorbeeld 2

/api/v1/public/status?topics=realtime,this/day&channels=11,12&identifiers=id

In plaats van keys zoals hoofdmeter en electric_power_import worden de numerieke IDs gebruikt.

{
  "data": {
    "1": {
      "1": {
        "realtime": {
          "value": 22.523246705532074,
          "time": 1736435099
        },
        "this/day": {
          "value": 3779.210578232764,
          "time": 1736434980
        }
      },
      "2": {
        "realtime": {
          "value": 276.95832401514053,
          "time": 1736435099
        },
        "this/day": {
          "value": 33.39675388706475,
          "time": 1736434980
        }
      }
    }
  }
}

Tijdreeksen

Via dit endpoint kunnen tijdreeksen van de kanalen worden opgevraagd. Het resultaat is een lijst van tijdstippen en bijbehorende waarde(s). Er kunnen meerdere kanalen tegelijk worden opgevraagd, de waardes staan in de volgorde van de parameter channels.

Endpoint: /api/v1/public/timeseries

Query parameters

  • channels (verplicht) een komma gescheiden lijst van kanalen die opgehaald moeten worden. Een kanaal kan worden opgegeven als numeriek ID of in formaat <NODE_KEY>:<CHANNEL_KEY>.
  • start (verplicht) het start tijdstip van de tijdreeks in Unix timestamp formaat.
  • end (verplicht) het eind tijdstip van de tijdreeks in Unix timestamp formaat.
  • resolution (verplicht) de resolutie van de tijdreeks. Mogelijke waardes zijn minute, hour, day of month.

Het maximum aantal records in het resultaat is 10000. Dit wordt bepaald door de resolutie en het tijdsbereik. Als er meer dan 10000 records zijn, wordt er een foutmelding teruggegeven.

Voorbeeld

/api/v1/public/timeseries?start=1733007600&end=1736426186&resolution=day&channels=1,2


{
  "data": [
    [
      1736118000,
      3752.168336942166,
      0
    ],
    [
      1736204400,
      3589.0457362062634,
      27.17992542434287
    ],
    [
      1736290800,
      3561.728213925065,
      244.74726855199364
    ],
    [
      1736377200,
      3807.74141805203,
      32.55061146884646
    ]
  ]
}
hier wordt maar een klein deel van het antwoord getoond