Supply point readings

The supply point readings allows your to query for aggregated readings for supply points, devices underneath them, and registers underneath those devices. Importantly, not all utility markets have devices or registers. This endpoint preserves the ability for developers to be ignorant to these underlying realities and use the same query across all markets.

The fact is, readings for supply points, devices, and registers are all readings. This endpoint embraces this fact and allows you to query for readings for any of these entities using the same GraphQL fragments.

These docs assume a two things:

  1. Your client is using Amphio to store its meter readings. (amphio link)
  2. This endpoint is enabled for your client. See these docs to learn how to enable it. (link)

HasReadings interface

The `HasReadings` interface allows for readings to be queried identically at each level. The `SupplyPointType`, `Device` type, and `DeviceRegister` types all implement the HasReadings interface.

Readings are split into `importReadings` and `exportReadings`. This distinction applies moreso to electricity markets; however, this split has advantages for all markets. The choice to split readings into import and export was made out of consideration for front end applications that may want to display both generation and consumption. It is far easier to combine the two connections than it is to split them apart. Instead of looping over all readings to sort them into generation and consumption, we can simply query for both and let the front end check for the existence of each via a simple if statement.

For all markets, `importReadings` are readings that represent the amount of utility that was used by the supply point. Gas and water markets have no concept of export readings for residential supply points. For electricity markets, `exportReadings` are readings that represent the amount of electricity generated and exported to the grid by the supply point. Gas and water markets have no concept of export readings for residential supply points.

It is best to query for both import and export readings for all markets. Lacking one or the other will result in an empty connection. 

fragment ReadingNodeFields on Reading {
    __typename
    value
    units
    intervalEnd
    intervalStart
    source
    quality
}

fragment PageInfoFields on PageInfo {
    hasNextPage
    hasPreviousPage
    endCursor
}

fragment Readings on HasReadings {
    readings(
        startAt: $startAt
        endAt: $endAt
        readingType: $readingType
        timeGranularity: $timeGranularity
        timezone: $timezone
    ) {
        __typename
        exportReadings(first: $first, after: $after) {
            __typename
            totalCount
            pageInfo {
                ...PageInfoFields
            }
            edges {
                node {
                    ...ReadingNodeFields
                }
            }
        }
        importReadings(first: $first, after: $after) {
            __typename
            totalCount
            pageInfo {
                ...PageInfoFields
            }
            edges {
                node {
                    ...ReadingNodeFields
                }
            }
        }
    }
}

Inputs - HasReadings interface

These inputs are required for the HasReadings interface.

  • startAt - The inclusive start of the time period you are querying for. Must be isoformatted.
  • endAt - The exclusive end of the time period you are querying for. Must be isoformatted.
  • readingType - Use INTERVAL for interval readings, ACCUMULATION for accumulation readings, or PEAK for peak demand readings.
  • timeGranularity - The time granularity to which readings will be aggregated. E.g., HOUR, DAY, WEEK, MONTH etc.
  • timezone - defaults to the timezone of the market. Must be a valid timezone string like "America/Chigago", "Europe/London", "Asia/Tokyo", "Australia/Sydney" etc.
Lastly, we have two optional inputs that can be used to filter for specific devices and registers. These inputs are optional and can be used to filter for specific devices and registers. If not provided, each devices and register will be returned as their own connections with their device and register identifiers included.

  • deviceIdentifiers - A list of device identifiers to filter for.
  • registerIdentifiers - A list of register identifiers to filter for.

Queries

There are two relevant perspectives when it comes to supply point readings: the markets and industry perspective and the account user perspective. The former cares amount the marketSupplyPointId and the market name. The latter cares about the account numbers or portfolio numbers. They for different use cases.

supplyPoint

The singular supplyPoint query is excellent when you do not need to care about the Kraken account to whom which these readings belong. Utility supply points exist on their own, and their data is stored without any reference to Kraken accounts, properties, effective periods, agreements, products, etc. 

query SupplyPointReadings(
    $externalIdentifier: String!
    $marketName: String!
    $startAt: DateTime!
    $endAt: DateTime!
    $readingType: ReadingTypes!
    $timeGranularity: TimeGranularities!
    $timezone: String!
    $first: Int
    $after: String
) {
    supplyPoint(
        externalIdentifier: $externalIdentifier
        marketName: $marketName
    ) {
        __typename
        externalIdentifier
        marketName
        ...Readings
    }
}

Inputs - supplyPoint

The two required inputs to supplyPoint are the externalIdentifie` and marketName. The `externalIdentifier` is the unique identifier for the supply point you are querying for. The `marketName` is the name of the market that supply point exists in. Both must be provided because the same external identifier may exist in multiple markets. 

{
  "externalIdentifier": "00000000000000",
  "marketName": "ELECTRICITY",
  "startAt": "2025-01-01T00:00:00",
  "endAt": "2025-01-02T00:00:00",
  "readingType": "INTERVAL",
  "timeGranularity": "DAY",
  "timezone": "Europe/London"
}

Response


supplyPoints

The plural supplyPoints query is excellent when you do need to care about the Kraken account to whom which these readings belong. Using this, you can query for an account with both an electricity and gas supply point with a single query as opposed to two separate queries for the Electricity and Gas markets respectively.

We are able to do this because both endpoints leverage Kraken's core SupplyPointType. The plural supplyPoints query returns a SupplyPointConnection while the singular supplyPoint query returns a SupplyPointType. The Readings type is defined on the SupplyPointType and is therefore available on both endpoints. 

query AccountSupplyPointsReadings(
    $accountNumber: String!
    $portfolioNumber: String!
    $startAt: DateTime!
    $endAt: DateTime!
    $readingType: ReadingTypes!
    $timeGranularity: TimeGranularities!
    $timezone: String!
) {
    supplyPoints(
        accountNumber: $accountNumber
        portfolioNumber: $portfolioNumber
    ) {
        edges{
            node {
            __typename
            externalIdentifier
            marketName
            ...Readings

            }
        }
    }
}

Inputs - supplyPoints

The two required inputs to supplyPoints are the `accountNumber` and `portfolioNumber`. 

{
  "accountNumber": "A-00000000",
  "portfolioNumber": "P-00000000",
  "startAt": "2025-01-01T00:00:00",
  "endAt": "2025-01-02T00:00:00",
  "readingType": "INTERVAL",
  "timeGranularity": "DAY",
  "timezone": "Europe/London"
}



Behavior differences

Calling either the supplyPoint or supplyPoints query will produce different results depending on whether your token is associated with an account user or an oAuth application. Account users will only be able to query for readings that are associated with their account for the time they lived at the property with the supply point you're intetrested in. OAuth applications will be able to query for all readings belonging to tha supply point. This behavior is due to the fact that account users are associated with a specific Kraken account and OAuth applications are not. Accounts have through models that link them to properties, effective periods, agreements, products, etc. Kraken's core API middleware will automatically filter the readings to only include those that are associated with the account user's account. OAuth applications are not associated with any of these entities. They will be able to query for readings for all accounts regardless of time period. This is advantageous for applications that need true time series data for supply points regardless of who happened to be living there at the time.