JSON Feeds Meterbeheer HUB

Requesting feeds

• Unique URL Access: Each JSON feed is accessible through a unique, non-guessable URL that can be requested using the HTTPS protocol.
• Metering Data Inclusion: Every JSON feed contains the metering data of one channel of one meter. A meter can have several channels, and each channel has its own URL. The last part of the URL names the channel (e.g., 1.8.0.json is channel "1.8.0").
• Unlimited Request Frequency: You can request a feed URL as often as you like.
• 24-Hour Update Cycle: Each feed is updated once every 24 hours.
• Default Data Scope: By default, a feed contains the data of the most recent available day.
• Custom Date Ranges: Alternatively, you can specify the "from" and "to" fields to obtain data for specific dates. The required date format is "YYYY-MM-DD".
• Maximum Period Duration: The requested time span can extend to a maximum of 365 days.

Data structure of feeds

The example at the bottom of this page shows every field at once so you can see the shape. A real feed carries either metering data or errors, not both.

• Each JSON feed contains the metering data of one meter of the previous day, per 15 minutes;
• Each JSON feed contains the following metadata:
  • EAN: the 18-digit EAN code of the meter;
  • Supplier channel: the channel code the metering company uses for this meter;
  • Unit: the unit of the data that is provided. This will be kilowatt-hour (kWh) for electricity meters and cubic meters (m³, given as m3) for gas meters.
  • master_data (optional): what the grid operator registers for this connection. Present once the connection has been looked up:
    • consumption_type: small_consumer or large_consumer;
    • grid_operator_name: the grid operator of the connection;
    • meter_installation_date: the date the current meter was put into use;
    • mandate_start_date and mandate_end_date: the period we are authorized to read this connection;
• Each JSON feed contains the following metering data:
  • From + to: the date and time in ISO 8601 format (for example "2023-01-01T12:00:00+01:00");
  • Value: the usage of the meter for the specified period (in the unit specified in the metadata). Null between the last reading of a replaced meter and the first reading of its successor, since the usage in that period is unknown.
  • A feed of meter readings (/feed-meter-reading/) lists a meter_reading per moment instead. It is null at the moments between the last reading of a replaced meter and the first reading of its successor.
• Each JSON feed may contain a message in the metadata: one line saying why no data is coming in. It distinguishes an outage, which is expected to pass, from a connection the grid operator refuses outright, for which no data will arrive until the meter itself changes. Subscribe to API+ to receive the provider's own reason per day in an errors array instead of this one line.

Example request

A request would look like this:

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

Example JSON response

The response to the request above would look like this (the data shown here is fictional):

{
    "meter_data": {
        "ean": "871234500012345678",
        "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
        }
    ]
}

This means: the meter with EAN 871234500012345678 had a usage of:

• 1 kWh on January 1st 2023 between 0:00 and 0:15 h.
• 2.75 kWh on January 1st 2023 between 0:15 and 0:30 h.
• 3.25 kWh on January 1st 2023 between 0:30 and 0:45 h.

Example request with date range

A request with a date range would look like this:

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

Demo feed

There’s a demo feed available at the following url:

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

This feed is updated every 24 hours, just like a real feed.

The metering data field of the test feed contains values that help you see when the feed was generated. This is done to be able to easily run tests with the data. This logic only applies to the test feed. Real feeds will of course contain the actual values without any logic.

The first decimal of all values represents the day of the week, according to this table:

The rest of the decimals is a counter that starts with 1 (the first 15-minute block of the feed) and ends with 96 (the last 15-minute block of the feed), since there are 96 blocks of 15 minutes in a full day (24 * 4).

The whole-number part of the values is random and contains no logic.

• A value of 385.101 represents a Monday feed and is the first value of that feed;
• A value of 10.411 represents a Thursday feed and is the 11th value of that feed;
• A value of 376.696 represents a Saturday feed and is the 96th (and last) value of that feed.

Document version: 1.3 (2024-02-17)