Offtake/Injection
The Energy Measurements endpoint provides a historical view on energy offtake and injection in a household.
The pseudo code for the generic endpoint for energy-measurements looks like this:
GET /energy-measurements/{metric_type}/{feed_type}/{interval}/{start_date}/{end_date}
Offtake and injection
Offtake and injection meaning
Offtake shows how much energy is taken from the grid for household consumption. Injection or feedin shows how much locally produced energy is delivered back to the grid.
Be aware that the combination of these two factors determine the grid balance, but they do not determine the total household consumption and solar production. This is because households use part of the solar produced energy for self consumption. The solar production and consumption values are calculated by NET2GRID and described in determination of solar production.
Metric type
The metric_type parameter is used to specify what kind of measurements you want to retrieve.
Options for metric_type are:
- electricity-offtake: the electricity consumed from the grid
- electricity-feedin : the electricity produced and delivered back to the grid
- gas: the gas consumed from the household
- electricity-offtake-tier-1 & electricity-offtake-tier-2: the electricity consumed from the grid and its cost will be calculated based on the tier for which is relevant
- electricity-feedin-tier-1 & electricity-feedin-tier-2: the electricity produced and delivered back to the grid and its cost will be calculated based on the tier for which is relevant
A measurement call with offtake as metric_type returns the amount of electricity taken of the grid. Without solar panels, this is the consumed energy. A measurement call with feedin as metric_type returns the amount of electricity injected back into the grid.
Associated with consumed and produced electricity are the costs. Costs can be based on a single tariff or on multiple tariffs, depending on the time of use. NET2GRID supports single tier and two tier energy measurements. tier-1 in a two-tier tariff contract might be the tariff for the day and tier-2 the tariff for night and weekend, or the other way around depending on the energy retailer. With the metric_type parameter the amount of electricity offtake and injection can be requested separately for one of the two tiers or for the single tier. In order to retrieve two tiered energy measurements, the energy data source needs to provide the time-of-use data. With smart meter measurements this often a daily value for both tiers. For real-time data the tier is associated with the high granularity level of the measurements.
The offtake of gas can also be requested via the metric_type parameter.
Although the energy measurements endpoints return either offtake or injection (feedin) measurements, depending on the metric-type, these values are often combined in the same view. The smart meter either reports offtake, Current Summation Delivered (CSD), or injection, Current Summation Received (CSR), at a particular point in time. For a 15 minutes or longer interval though, the electricity values can contain both CSD and CSR values, in case electricity is both taken off and injected back into the grid intermittent in that interval.
As an example, have a look at how the Ynni apps shows energy measurements for smart meter data. The grey bars in this monthly view depict daily electricity offtake and the yellow bars depict injection.
Smart meter offtake and injection monthly view
Feed type (Smart meter and real-time)
As explained in Energy data sources smart meter data usually is available up till yesterday or the day before yesterday, whereas real-time data is available near real time. Whereas the granularity at the source of these two data feeds is different, the energy measurements call provides results at an aggregated level with a similar granularity. The feed_type parameter is important to identify the right source feed though and can have value [smart-meter] or [real-time].
Find the feedtype and energy type of the end-user
The CE-API provides the GET /v2/feedtype endpoint that returns the meters for which the user is eligible to request data for and can be used to identify the feed type and limit some metric types for which energy measurements are available.
An example result of a successful call would be:
{
"status": "ok",
"data": {
"electricity": 1,
"gas": 1
},
"timestamp": "2023-01-10T15:12:21+01:00"
}
This response would mean that the user has real-time data for electricity and gas, so the following calls should return data for the relevant period:
GET /v2/energy-measurements/electricity-offtake/real-time/{interval}/{start_date}/{end_date}
GET /v2/energy-measurements/gas/real-time/{interval}/{start_date}/{end_date}
Similarly the response could be something like
{
"status": "ok",
"data": {
"electricity": 1,
"gas": 1,
"amr_electricity": 1,
"amr_gas": 1
},
"timestamp": "2023-01-10T15:12:21+01:00"
}
then this would mean that both real-time and smart-meter feedtypes would be eligible for the end-user both for electricity and for gas, so the following calls would be possible:
GET /v2/energy-measurements/electricity-offtake/real-time/{interval}/{start_date}/{end_date}
GET /v2/energy-measurements/gas/real-time/{interval}/{start_date}/{end_date}
GET /v2/energy-measurements/electricity-offtake/smart-meter/{interval}/{start_date}/{end_date}
GET /v2/energy-measurements/gas/smart-meter/{interval}/{start_date}/{end_date}
Time interval and period
Historical measurements can be requested using different zoom or abstraction levels, depending on the view to be displayed in the app. In the generic measurements call this zoom level is determined by the parameter interval and period: start_date and end_date.
The interval parameter describes the granularity of the measurements, i.e. the interval between measurements. Supported values for interval are quarter-hours, hours, days, weeks and months. The beginning and the end of the requested period is determined by the start_date and end_date parameters. Note that when the period is a single day, i.e. when the start and stop date are equal, the interval should still be "days" and not "day".
In order to protect the call for becoming too heavy, i.e. returning too many results of high granularity for a long period, the call entry fields for start_date and end_date have been adjusted for a specific interval.
The three zoom levels are:
intervalof quarter-hours, hours or days: the period is up to 30 daysintervalof weeks: the period is a quarter yearintervalof months: the period can span multiple years
Find the time period for which data is available for a metric
CE-API provides the Returns the first and last measurements of a time series for the provided energy type. endpoint that returns the period for which each metric has data for.
As an example of all of the above, for the highest level of abstraction, for returning the electricity offtake per month for the year 2022, the call
GET /v2/energy-measurements/electricity-offtake/real-time/months/2022-01/2022-12
would e.g. return:
{
"status": "ok",
"data": [
{
"timestamp": "2022-01-01T00:00:00+01:00",
"measured": 960828,
"cost_measured": 211.38216
},
{
"timestamp": "2022-02-01T00:00:00+01:00",
"measured": 738430,
"cost_measured": 162.4546
},
{
"timestamp": "2022-03-01T00:00:00+01:00",
"measured": 643434,
"cost_measured": 141.55548000000002
},
{
"timestamp": "2022-04-01T00:00:00+02:00",
"measured": 510849,
"cost_measured": 112.38678
},
{
"timestamp": "2022-05-01T00:00:00+02:00",
"measured": 440407,
"cost_measured": 96.88954
},
{
"timestamp": "2022-06-01T00:00:00+02:00",
"measured": 344208,
"cost_measured": 75.72576
},
{
"timestamp": "2022-07-01T00:00:00+02:00",
"measured": 274477,
"cost_measured": 60.38494
},
{
"timestamp": "2022-08-01T00:00:00+02:00",
"measured": 405032,
"cost_measured": 89.10704
},
{
"timestamp": "2022-09-01T00:00:00+02:00",
"measured": 434529,
"cost_measured": 95.59638000000001
},
{
"timestamp": "2022-10-01T00:00:00+02:00",
"measured": 499929,
"cost_measured": 109.98438
},
{
"timestamp": "2022-11-01T00:00:00+01:00",
"measured": 870282,
"cost_measured": 191.46204
},
{
"timestamp": "2022-12-01T00:00:00+01:00",
"measured": 1117892,
"cost_measured": 245.93624
}
]
}
and the corresponding feedin call
GET /v2/energy-measurements/electricity-feedin/real-time/months/2022-01/2022-12
would e.g. return:
{
"status": "ok",
"data": [
{
"timestamp": "2022-01-01T00:00:00+01:00",
"measured": 40375,
"cost_measured": 0
},
{
"timestamp": "2022-02-01T00:00:00+01:00",
"measured": 190589,
"cost_measured": 0
},
{
"timestamp": "2022-03-01T00:00:00+01:00",
"measured": 677120,
"cost_measured": 0
},
{
"timestamp": "2022-04-01T00:00:00+02:00",
"measured": 727851,
"cost_measured": 0
},
{
"timestamp": "2022-05-01T00:00:00+02:00",
"measured": 868750,
"cost_measured": 0
},
{
"timestamp": "2022-06-01T00:00:00+02:00",
"measured": 932079,
"cost_measured": 0
},
{
"timestamp": "2022-07-01T00:00:00+02:00",
"measured": 961854,
"cost_measured": 0
},
{
"timestamp": "2022-08-01T00:00:00+02:00",
"measured": 909751,
"cost_measured": 0
},
{
"timestamp": "2022-09-01T00:00:00+02:00",
"measured": 562779,
"cost_measured": 0
},
{
"timestamp": "2022-10-01T00:00:00+02:00",
"measured": 292965,
"cost_measured": 0
},
{
"timestamp": "2022-11-01T00:00:00+01:00",
"measured": 110978,
"cost_measured": 0
},
{
"timestamp": "2022-12-01T00:00:00+01:00",
"measured": 20948,
"cost_measured": 0
}
]
}
Updated 3 months ago