Aggregating supply point readings
The supply point readings API allows you to query for aggregated readings for supply points, devices, and registers. Assume a supply point that has one device and this device has two registers.
- Supply point - 00000000000000
- Device 1 - 123
- Register 1 - 456
- Register 2 - 789
To best demonstrate the aggregation capabilities of the supply point readings API, we will use a query that will return readings for the supply point, device, and registers at the same time. This likely is not useful for any real-world use case, but it is a good way to demonstrate the relationship between the different levels of aggregation.
The following usage pattern is used for the different time granularities. This pattern produces one importReading at each level of aggregation to keep things simple.
- 1 kWh per hour for the day interval
- 1 kWh per day for the week interval
- 1 kWh per week for the month interval
- 1 kWh per month for the quarter interval
- 1 kWh per month for the year interval
You'll see in the responses, that the registers' readings are aggregated up to the device level, which in turn is aggregated up to the supply point level. Recall that deviceIdentifiers and registerIdentifiers are optional parameters to the query. If left out, all devices and registers will be returned. Thus, the inputs below omit both.
query AllReadingsLevels(
$externalIdentifier: String!
$marketName: String!
$startAt: DateTime!
$endAt: DateTime!
$readingType: ReadingTypes!
$timeGranularity: TimeGranularities!
$timezone: String!
$deviceIdentifiers: [String]
$deviceRegisterIdentifiers: [String]
) {
supplyPoint(
externalIdentifier: $externalIdentifier
marketName: $marketName
) {
__typename
externalIdentifier
marketName
...Readings
devices(deviceIdentifiers: $deviceIdentifiers) {
__typename
edges {
node {
__typename
deviceIdentifier
...Readings
registers(registerIdentifiers: $deviceRegisterIdentifiers) {
__typename
edges {
node {
__typename
registerIdentifier
...Readings
}
}
}
}
}
}
}
}
Day interval
Day intervals are aligned to midnight.
{
"externalIdentifier": "00000000000000",
"marketName": "ELECTRICITY",
"startAt": "2025-01-01T00:00:00",
"endAt": "2025-01-02T00:00:00",
"readingType": "INTERVAL",
"timeGranularity": "DAY",
"timezone": "Europe/London"
}Day interval response
{
"data": {
"supplyPoint": {
"__typename": "SupplyPointType",
"externalIdentifier": "00000000000000",
"marketName": "ELECTRICITY",
"readings": {
"__typename": "Readings",
"exportReadings": {
"__typename": "ExportReadingsConnection",
"totalCount": 0,
"edges": []
},
"importReadings": {
"__typename": "ImportReadingsConnection",
"totalCount": 1,
"edges": [
{
"node": {
"__typename": "Reading",
"value": "48",
"units": "KILOWATT_HOURS",
"intervalEnd": "2025-01-02T00:00:00",
"intervalStart": "2025-01-01T00:00:00",
"source": "industry",
"quality": "actual"
}
}
]
}
},
"devices": {
"__typename": "DevicesConnection",
"edges": [
{
"node": {
"__typename": "Device",
"deviceIdentifier": "123",
"readings": {
"__typename": "Readings",
"exportReadings": {
"__typename": "ExportReadingsConnection",
"totalCount": 0,
"edges": []
},
"importReadings": {
"__typename": "ImportReadingsConnection",
"totalCount": 1,
"edges": [
{
"node": {
"__typename": "Reading",
"value": "48",
"units": "KILOWATT_HOURS",
"intervalEnd": "2025-01-02T00:00:00",
"intervalStart": "2025-01-01T00:00:00",
"source": "industry",
"quality": "actual"
}
}
]
}
},
"registers": {
"__typename": "RegistersConnection",
"edges": [
{
"node": {
"__typename": "DeviceRegister",
"registerIdentifier": "456",
"readings": {
"__typename": "Readings",
"exportReadings": {
"__typename": "ExportReadingsConnection",
"totalCount": 0,
"edges": []
},
"importReadings": {
"__typename": "ImportReadingsConnection",
"totalCount": 1,
"edges": [
{
"node": {
"__typename": "Reading",
"value": "24",
"units": "KILOWATT_HOURS",
"intervalEnd": "2025-01-02T00:00:00",
"intervalStart": "2025-01-01T00:00:00",
"source": "industry",
"quality": "actual"
}
}
]
}
}
}
},
{
"node": {
"__typename": "DeviceRegister",
"registerIdentifier": "789",
"readings": {
"__typename": "Readings",
"exportReadings": {
"__typename": "ExportReadingsConnection",
"totalCount": 0,
"edges": []
},
"importReadings": {
"__typename": "ImportReadingsConnection",
"totalCount": 1,
"edges": [
{
"node": {
"__typename": "Reading",
"value": "24",
"units": "KILOWATT_HOURS",
"intervalEnd": "2025-01-02T00:00:00",
"intervalStart": "2025-01-01T00:00:00",
"source": "industry",
"quality": "actual"
}
}
]
}
}
}
}
]
}
}
}
]
}
}
}
}Week interval
Week intervals are aligned to the first Monday of the week. In the case of 2025, the first Monday is on January 6th. Not using a Monday for your startAt date will result in an incomplete week.
{
"externalIdentifier": "00000000000000",
"marketName": "ELECTRICITY",
"startAt": "2025-01-06T00:00:00",
"endAt": "2025-01-13T00:00:00",
"readingType": "INTERVAL",
"timeGranularity": "WEEK",
"timezone": "Europe/London"
}Week interval response
{
"data": {
"supplyPoint": {
"__typename": "SupplyPointType",
"externalIdentifier": "00000000000000",
"marketName": "ELECTRICITY",
"readings": {
"__typename": "Readings",
"exportReadings": {
"__typename": "ExportReadingsConnection",
"totalCount": 0,
"edges": []
},
"importReadings": {
"__typename": "ImportReadingsConnection",
"totalCount": 1,
"edges": [
{
"node": {
"__typename": "Reading",
"value": "14",
"units": "KILOWATT_HOURS",
"intervalEnd": "2025-01-13T00:00:00",
"intervalStart": "2025-01-06T00:00:00",
"source": "industry",
"quality": "actual"
}
}
]
}
},
"devices": {
"__typename": "DevicesConnection",
"edges": [
{
"node": {
"__typename": "Device",
"deviceIdentifier": "123",
"readings": {
"__typename": "Readings",
"exportReadings": {
"__typename": "ExportReadingsConnection",
"totalCount": 0,
"edges": []
},
"importReadings": {
"__typename": "ImportReadingsConnection",
"totalCount": 1,
"edges": [
{
"node": {
"__typename": "Reading",
"value": "14",
"units": "KILOWATT_HOURS",
"intervalEnd": "2025-01-13T00:00:00",
"intervalStart": "2025-01-06T00:00:00",
"source": "industry",
"quality": "actual"
}
}
]
}
},
"registers": {
"__typename": "RegistersConnection",
"edges": [
{
"node": {
"__typename": "DeviceRegister",
"registerIdentifier": "456",
"readings": {
"__typename": "Readings",
"exportReadings": {
"__typename": "ExportReadingsConnection",
"totalCount": 0,
"edges": []
},
"importReadings": {
"__typename": "ImportReadingsConnection",
"totalCount": 1,
"edges": [
{
"node": {
"__typename": "Reading",
"value": "7",
"units": "KILOWATT_HOURS",
"intervalEnd": "2025-01-13T00:00:00",
"intervalStart": "2025-01-06T00:00:00",
"source": "industry",
"quality": "actual"
}
}
]
}
}
}
},
{
"node": {
"__typename": "DeviceRegister",
"registerIdentifier": "789",
"readings": {
"__typename": "Readings",
"exportReadings": {
"__typename": "ExportReadingsConnection",
"totalCount": 0,
"edges": []
},
"importReadings": {
"__typename": "ImportReadingsConnection",
"totalCount": 1,
"edges": [
{
"node": {
"__typename": "Reading",
"value": "7",
"units": "KILOWATT_HOURS",
"intervalEnd": "2025-01-13T00:00:00",
"intervalStart": "2025-01-06T00:00:00",
"source": "industry",
"quality": "actual"
}
}
]
}
}
}
}
]
}
}
}
]
}
}
}
}Month interval
Month intervals are aligned to the first day of the month.
{
"externalIdentifier": "00000000000000",
"marketName": "ELECTRICITY",
"startAt": "2025-01-01T00:00:00",
"endAt": "2025-02-01T00:00:00",
"readingType": "INTERVAL",
"timeGranularity": "MONTH",
"timezone": "Europe/London"
}Month interval response
{
"data": {
"supplyPoint": {
"__typename": "SupplyPointType",
"externalIdentifier": "00000000000000",
"marketName": "ELECTRICITY",
"readings": {
"__typename": "Readings",
"exportReadings": {
"__typename": "ExportReadingsConnection",
"totalCount": 0,
"edges": []
},
"importReadings": {
"__typename": "ImportReadingsConnection",
"totalCount": 1,
"edges": [
{
"node": {
"__typename": "Reading",
"value": "62",
"units": "KILOWATT_HOURS",
"intervalEnd": "2025-02-01T00:00:00",
"intervalStart": "2025-01-01T00:00:00",
"source": "industry",
"quality": "actual"
}
}
]
}
},
"devices": {
"__typename": "DevicesConnection",
"edges": [
{
"node": {
"__typename": "Device",
"deviceIdentifier": "123",
"readings": {
"__typename": "Readings",
"exportReadings": {
"__typename": "ExportReadingsConnection",
"totalCount": 0,
"edges": []
},
"importReadings": {
"__typename": "ImportReadingsConnection",
"totalCount": 1,
"edges": [
{
"node": {
"__typename": "Reading",
"value": "62",
"units": "KILOWATT_HOURS",
"intervalEnd": "2025-02-01T00:00:00",
"intervalStart": "2025-01-01T00:00:00",
"source": "industry",
"quality": "actual"
}
}
]
}
},
"registers": {
"__typename": "RegistersConnection",
"edges": [
{
"node": {
"__typename": "DeviceRegister",
"registerIdentifier": "456",
"readings": {
"__typename": "Readings",
"exportReadings": {
"__typename": "ExportReadingsConnection",
"totalCount": 0,
"edges": []
},
"importReadings": {
"__typename": "ImportReadingsConnection",
"totalCount": 1,
"edges": [
{
"node": {
"__typename": "Reading",
"value": "31",
"units": "KILOWATT_HOURS",
"intervalEnd": "2025-02-01T00:00:00",
"intervalStart": "2025-01-01T00:00:00",
"source": "industry",
"quality": "actual"
}
}
]
}
}
}
},
{
"node": {
"__typename": "DeviceRegister",
"registerIdentifier": "789",
"readings": {
"__typename": "Readings",
"exportReadings": {
"__typename": "ExportReadingsConnection",
"totalCount": 0,
"edges": []
},
"importReadings": {
"__typename": "ImportReadingsConnection",
"totalCount": 1,
"edges": [
{
"node": {
"__typename": "Reading",
"value": "31",
"units": "KILOWATT_HOURS",
"intervalEnd": "2025-02-01T00:00:00",
"intervalStart": "2025-01-01T00:00:00",
"source": "industry",
"quality": "actual"
}
}
]
}
}
}
}
]
}
}
}
]
}
}
}
}Quarter interval
Quarter intervals are aligned to the first day of the quarter.
{
"externalIdentifier": "00000000000000",
"marketName": "ELECTRICITY",
"startAt": "2025-01-01T00:00:00",
"endAt": "2025-04-01T00:00:00",
"readingType": "INTERVAL",
"timeGranularity": "QUARTER",
"timezone": "Europe/London"
}Quarter interval response
{
"data": {
"supplyPoint": {
"__typename": "SupplyPointType",
"externalIdentifier": "00000000000000",
"marketName": "ELECTRICITY",
"readings": {
"__typename": "Readings",
"exportReadings": {
"__typename": "ExportReadingsConnection",
"totalCount": 0,
"edges": []
},
"importReadings": {
"__typename": "ImportReadingsConnection",
"totalCount": 1,
"edges": [
{
"node": {
"__typename": "Reading",
"value": "26",
"units": "KILOWATT_HOURS",
"intervalEnd": "2025-04-01T00:00:00+02:00",
"intervalStart": "2025-01-01T00:00:00",
"source": "industry",
"quality": "actual"
}
}
]
}
},
"devices": {
"__typename": "DevicesConnection",
"edges": [
{
"node": {
"__typename": "Device",
"deviceIdentifier": "123",
"readings": {
"__typename": "Readings",
"exportReadings": {
"__typename": "ExportReadingsConnection",
"totalCount": 0,
"edges": []
},
"importReadings": {
"__typename": "ImportReadingsConnection",
"totalCount": 1,
"edges": [
{
"node": {
"__typename": "Reading",
"value": "26",
"units": "KILOWATT_HOURS",
"intervalEnd": "2025-04-01T00:00:00+02:00",
"intervalStart": "2025-01-01T00:00:00",
"source": "industry",
"quality": "actual"
}
}
]
}
},
"registers": {
"__typename": "RegistersConnection",
"edges": [
{
"node": {
"__typename": "DeviceRegister",
"registerIdentifier": "456",
"readings": {
"__typename": "Readings",
"exportReadings": {
"__typename": "ExportReadingsConnection",
"totalCount": 0,
"edges": []
},
"importReadings": {
"__typename": "ImportReadingsConnection",
"totalCount": 1,
"edges": [
{
"node": {
"__typename": "Reading",
"value": "13",
"units": "KILOWATT_HOURS",
"intervalEnd": "2025-04-01T00:00:00+02:00",
"intervalStart": "2025-01-01T00:00:00",
"source": "industry",
"quality": "actual"
}
}
]
}
}
}
},
{
"node": {
"__typename": "DeviceRegister",
"registerIdentifier": "789",
"readings": {
"__typename": "Readings",
"exportReadings": {
"__typename": "ExportReadingsConnection",
"totalCount": 0,
"edges": []
},
"importReadings": {
"__typename": "ImportReadingsConnection",
"totalCount": 1,
"edges": [
{
"node": {
"__typename": "Reading",
"value": "13",
"units": "KILOWATT_HOURS",
"intervalEnd": "2025-04-01T00:00:00+02:00",
"intervalStart": "2025-01-01T00:00:00",
"source": "industry",
"quality": "actual"
}
}
]
}
}
}
}
]
}
}
}
]
}
}
}
}Year interval
Year intervals are aligned to the first day of the year.
{
"externalIdentifier": "00000000000000",
"marketName": "ELECTRICITY",
"startAt": "2025-01-01T00:00:00",
"endAt": "2026-01-01T00:00:00",
"readingType": "INTERVAL",
"timeGranularity": "YEAR",
"timezone": "Europe/Paris"
}Year interval response
{
"data": {
"supplyPoint": {
"__typename": "SupplyPointType",
"externalIdentifier": "00000000000000",
"marketName": "ELECTRICITY",
"readings": {
"__typename": "Readings",
"exportReadings": {
"__typename": "ExportReadingsConnection",
"totalCount": 0,
"edges": []
},
"importReadings": {
"__typename": "ImportReadingsConnection",
"totalCount": 1,
"edges": [
{
"node": {
"__typename": "Reading",
"value": "730",
"units": "KILOWATT_HOURS",
"intervalEnd": "2026-01-01T00:00:00",
"intervalStart": "2025-01-01T00:00:00",
"source": "industry",
"quality": "actual"
}
}
]
}
},
"devices": {
"__typename": "DevicesConnection",
"edges": [
{
"node": {
"__typename": "Device",
"deviceIdentifier": "123",
"readings": {
"__typename": "Readings",
"exportReadings": {
"__typename": "ExportReadingsConnection",
"totalCount": 0,
"edges": []
},
"importReadings": {
"__typename": "ImportReadingsConnection",
"totalCount": 1,
"edges": [
{
"node": {
"__typename": "Reading",
"value": "730",
"units": "KILOWATT_HOURS",
"intervalEnd": "2026-01-01T00:00:00",
"intervalStart": "2025-01-01T00:00:00",
"source": "industry",
"quality": "actual"
}
}
]
}
},
"registers": {
"__typename": "RegistersConnection",
"edges": [
{
"node": {
"__typename": "DeviceRegister",
"registerIdentifier": "456",
"readings": {
"__typename": "Readings",
"exportReadings": {
"__typename": "ExportReadingsConnection",
"totalCount": 0,
"edges": []
},
"importReadings": {
"__typename": "ImportReadingsConnection",
"totalCount": 1,
"edges": [
{
"node": {
"__typename": "Reading",
"value": "365",
"units": "KILOWATT_HOURS",
"intervalEnd": "2026-01-01T00:00:00",
"intervalStart": "2025-01-01T00:00:00",
"source": "industry",
"quality": "actual"
}
}
]
}
}
}
},
{
"node": {
"__typename": "DeviceRegister",
"registerIdentifier": "789",
"readings": {
"__typename": "Readings",
"exportReadings": {
"__typename": "ExportReadingsConnection",
"totalCount": 0,
"edges": []
},
"importReadings": {
"__typename": "ImportReadingsConnection",
"totalCount": 1,
"edges": [
{
"node": {
"__typename": "Reading",
"value": "365",
"units": "KILOWATT_HOURS",
"intervalEnd": "2026-01-01T00:00:00",
"intervalStart": "2025-01-01T00:00:00",
"source": "industry",
"quality": "actual"
}
}
]
}
}
}
}
]
}
}
}
]
}
}
}
}