JSON-feeds Meterbeheer HUB

Feeds opvragen

  • Unieke URL: elke JSON-feed heeft een eigen URL die niet te raden is. Je vraagt hem op via HTTPS.
  • Meetdata per channel: elke JSON-feed bevat de meetdata van één channel van één meter. Een meter kan meerdere channels hebben, en elk channel heeft een eigen URL. Het laatste deel van de URL is het channel (1.8.0.json is bijvoorbeeld channel "1.8.0").
  • Onbeperkt opvragen: je kunt een feed-URL zo vaak opvragen als je wilt.
  • Elke 24 uur bijgewerkt: elke feed wordt eens per 24 uur bijgewerkt.
  • Standaardperiode: standaard bevat een feed de data van de meest recente beschikbare dag.
  • Eigen periode: met de velden "from" en "to" haal je in plaats daarvan de data van bepaalde datums op. Gebruik het formaat "YYYY-MM-DD".
  • Maximale periode: je kunt maximaal 365 dagen in één keer opvragen.

Datastructuur van feeds

Het voorbeeld onderaan deze pagina toont alle velden tegelijk, zodat je de opbouw ziet. Een echte feed bevat óf meetdata óf fouten, nooit allebei.

  • Elke JSON-feed bevat de meetdata van één meter over de vorige dag, per 15 minuten;
  • Elke JSON-feed bevat de volgende metadata:
    • EAN: de EAN-code van 18 cijfers van de meter;
    • data_source: measured voor waarden die een meter, gebouwbeheersysteem of omvormer heeft geregistreerd, ai_forecast voor waarden die ons voorspelmodel heeft berekend;
    • Supplier channel: de channelcode die het meetbedrijf voor deze meter gebruikt;
    • Unit: de eenheid van de geleverde data. Dat is kilowattuur (kWh) voor elektriciteitsmeters en kubieke meter (m³, als m3) voor gasmeters.
    • master_data (optioneel): wat de netbeheerder voor deze aansluiting registreert. Aanwezig zodra we de aansluiting hebben opgezocht:
      • consumption_type: small_consumer (kleinverbruik) of large_consumer (grootverbruik);
      • grid_operator_name: de netbeheerder van de aansluiting;
      • meter_installation_date: de datum waarop de huidige meter in gebruik is genomen;
      • mandate_start_date en mandate_end_date: de periode waarin we deze aansluiting mogen uitlezen;
  • Elke JSON-feed bevat de volgende meetdata:
    • From + to: datum en tijd in ISO 8601-formaat (bijvoorbeeld "2023-01-01T12:00:00+01:00");
    • Value: het verbruik van de meter in die periode (in de eenheid uit de metadata). Null tussen de laatste meting van een vervangen meter en de eerste meting van zijn opvolger, omdat het verbruik in die periode onbekend is.
    • Een feed met meterstanden (/feed-meter-reading/) geeft in plaats daarvan een meter_reading per moment. Die is null op de momenten tussen de laatste meting van een vervangen meter en de eerste meting van zijn opvolger.
  • Elke JSON-feed kan een message in de metadata bevatten: één regel die zegt waarom er geen data binnenkomt. Die maakt onderscheid tussen een storing, die naar verwachting overgaat, en een aansluiting die de netbeheerder helemaal weigert, waarvoor pas data komt als de meter zelf verandert. Met API+ krijg je in plaats van deze ene regel per dag de eigen reden van de meetdienst, in een errors-array.

Voorbeeldrequest

Een request ziet er zo uit:

curl
curl https://test.hub.meterbeheer.nl/feed/70fbe0de-7140-49d1-9c30-b5081dc3f023/1.8.0.json

Voorbeeld van een JSON-response

De response op het request hierboven ziet er zo uit (de data is verzonnen):

JSON
{
    "meter_data": {
        "ean": "871234500012345678",
        "data_source": "measured",
        "supplier_channel": "1.8.0",
        "unit": "kWh",
        "master_data": {
            "consumption_type": "small_consumer",
            "grid_operator_name": "Stedin",
            "meter_installation_date": "2021-10-28",
            "mandate_start_date": "2022-06-01",
            "mandate_end_date": "2036-12-31"
        },
        "from": "2023-01-01T00:00:00+01:00",
        "to": "2023-01-01T00:45:00+01:00"
    },
    "metering_data": [
        {
            "from": "2023-01-01T00:00:00+01:00",
            "to": "2023-01-01T00:15:00+01:00",
            "value": 1
        },
        {
            "from": "2023-01-01T00:15:00+01:00",
            "to": "2023-01-01T00:30:00+01:00",
            "value": 2.75
        },
        {
            "from": "2023-01-01T00:30:00+01:00",
            "to": "2023-01-01T00:45:00+01:00",
            "value": 3.25
        }
    ]
}

Dit betekent dat de meter met EAN 871234500012345678 dit verbruik had:

  • 1 kWh op 1 januari 2023 tussen 0:00 en 0:15 uur.
  • 2.75 kWh op 1 januari 2023 tussen 0:15 en 0:30 uur.
  • 3.25 kWh op 1 januari 2023 tussen 0:30 en 0:45 uur.

Voorbeeldrequest met periode

Een request met een periode ziet er zo uit:

curl
curl https://test.hub.meterbeheer.nl/feed/70fbe0de-7140-49d1-9c30-b5081dc3f023/1.8.0.json?from=2026-10-01&to=2026-11-01

Demofeed

Er is een demofeed beschikbaar op deze URL:

https://test.hub.meterbeheer.nl/feed/70fbe0de-7140-49d1-9c30-b5081dc3f023/1.8.0.json

Deze feed wordt elke 24 uur bijgewerkt, net als een echte feed.

Het meetdataveld van de testfeed bevat waarden waaraan je kunt zien wanneer de feed is gemaakt. Zo kun je makkelijk testen met de data. Deze logica geldt alleen voor de testfeed: echte feeds bevatten natuurlijk gewoon de werkelijke waarden.

De eerste decimaal van elke waarde staat voor de dag van de week, volgens deze tabel:

Maandag 1
Dinsdag 2
Woensdag 3
Donderdag 4
Vrijdag 5
Zaterdag 6
Zondag 7

De overige decimalen vormen een teller die begint bij 1 (het eerste kwartier van de feed) en eindigt bij 96 (het laatste kwartier van de feed), want een hele dag heeft 96 kwartieren (24 * 4).

Het deel vóór de punt is willekeurig en bevat geen logica.

Voorbeelden:
  • De waarde 385.101 hoort bij een maandagfeed en is de eerste waarde van die feed;
  • De waarde 10.411 hoort bij een donderdagfeed en is de 11e waarde van die feed;
  • De waarde 376.696 hoort bij een zaterdagfeed en is de 96e (en laatste) waarde van die feed.

Documentversie: 1.3 (17-02-2024)