Australian Energy Regulator

Australian Energy Regulator Electricity Usage API

Electricity Usage endpoints

Documentation GitHub OpenAPI

Operations 3

GET /energy/electricity/servicepoints/{servicePointId}/usage Get Usage For Service Point #

GET /energy/electricity/servicepoints/usage Get Bulk Usage #

POST /energy/electricity/servicepoints/usage Get Usage For Specific Service Points #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this

find_apisBrowse and filter every API in the catalog.
get_api_artifactsOne API's artifacts, grouped by type.
get_openapiThe primary OpenAPI for this API.
find_similar_apisAPIs that look like this one.
apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
resolveTurn a domain, URL or GitHub org into the provider it belongs to.
find_cohortsEvery scored population of providers in the catalog.

All 92 tools →

Call it yourself

curl for this page

This API

curl "https://apis.io/api/v1/apis/aer-electricity-usage-api"

All apis

curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no email required.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

openapi: 3.2.0
info:
  title: CDR Energy Electricity Usage API
  version: 1.36.0
  description: Specifications for resource endpoints applicable to data holders in the Energy sector.
  contact:
    name: Data Standards Body
    email: contact@dsb.gov.au
    url: https://dsb.gov.au/
servers:
- description: MTLS
  url: https://mtls.dh.example.com/cds-au/v1
tags:
- name: Electricity Usage
  x-shortName: Usage
  description: Electricity Usage endpoints
paths:
  /energy/electricity/servicepoints/{servicePointId}/usage:
    get:
      summary: Get Usage For Service Point
      operationId: getElectricityServicePointUsage
      x-scopes:
      - energy:electricity.usage:read
      description: Obtain a list of electricity usage data from a particular service point.
      tags:
      - Electricity Usage
      x-version: '1'
      parameters:
      - $ref: '#/components/parameters/PathServicePointId'
      - $ref: '#/components/parameters/QueryOldestDate'
      - $ref: '#/components/parameters/QueryNewestDate'
      - $ref: '#/components/parameters/QueryEnergyIntervalReads'
      - $ref: '#/components/parameters/QueryPage'
      - $ref: '#/components/parameters/QueryPageSize'
      - $ref: '#/components/parameters/HeaderXV'
      - $ref: '#/components/parameters/HeaderXMinV'
      - $ref: '#/components/parameters/HeaderXFAPIInteractionId'
      - $ref: '#/components/parameters/HeaderXFAPIAuthDate'
      - $ref: '#/components/parameters/HeaderXFAPICustomerIPAddress'
      - $ref: '#/components/parameters/HeaderXCDSClientHeaders'
      responses:
        '200':
          $ref: '#/components/responses/GetElectricityServicePointUsage200'
        '400':
          $ref: '#/components/responses/GetElectricityServicePointUsage400'
        '404':
          $ref: '#/components/responses/GetElectricityServicePointUsage404'
        '406':
          $ref: '#/components/responses/GetElectricityServicePointUsage406'
        '422':
          $ref: '#/components/responses/GetElectricityServicePointUsage422'
  /energy/electricity/servicepoints/usage:
    get:
      summary: Get Bulk Usage
      operationId: listElectricityUsageBulk
      x-scopes:
      - energy:electricity.usage:read
      description: Obtain usage data for all service points associated with the customer.
      tags:
      - Electricity Usage
      x-version: '1'
      parameters:
      - $ref: '#/components/parameters/QueryEnergyIntervalReads'
      - $ref: '#/components/parameters/QueryOldestDate'
      - $ref: '#/components/parameters/QueryNewestDate'
      - $ref: '#/components/parameters/QueryPage'
      - $ref: '#/components/parameters/QueryPageSize'
      - $ref: '#/components/parameters/HeaderXV'
      - $ref: '#/components/parameters/HeaderXMinV'
      - $ref: '#/components/parameters/HeaderXFAPIInteractionId'
      - $ref: '#/components/parameters/HeaderXFAPIAuthDate'
      - $ref: '#/components/parameters/HeaderXFAPICustomerIPAddress'
      - $ref: '#/components/parameters/HeaderXCDSClientHeaders'
      responses:
        '200':
          $ref: '#/components/responses/ListElectricityUsageBulk200'
        '400':
          $ref: '#/components/responses/ListElectricityUsageBulk400'
        '406':
          $ref: '#/components/responses/ListElectricityUsageBulk406'
        '422':
          $ref: '#/components/responses/ListElectricityUsageBulk422'
    post:
      summary: Get Usage For Specific Service Points
      operationId: listElectricityUsageForServicePoints
      x-scopes:
      - energy:electricity.usage:read
      description: Obtain the electricity usage data for a specific set of service points.
      tags:
      - Electricity Usage
      x-version: '1'
      parameters:
      - $ref: '#/components/parameters/QueryOldestDate'
      - $ref: '#/components/parameters/QueryNewestDate'
      - $ref: '#/components/parameters/QueryEnergyIntervalReads'
      - $ref: '#/components/parameters/QueryPage'
      - $ref: '#/components/parameters/QueryPageSize'
      - $ref: '#/components/parameters/HeaderXV'
      - $ref: '#/components/parameters/HeaderXMinV'
      - $ref: '#/components/parameters/HeaderXFAPIInteractionId'
      - $ref: '#/components/parameters/HeaderXFAPIAuthDate'
      - $ref: '#/components/parameters/HeaderXFAPICustomerIPAddress'
      - $ref: '#/components/parameters/HeaderXCDSClientHeaders'
      requestBody:
        $ref: '#/components/requestBodies/RequestServicePointIds'
      responses:
        '200':
          $ref: '#/components/responses/ListElectricityUsageForServicePoints200'
        '400':
          $ref: '#/components/responses/ListElectricityUsageForServicePoints400'
        '406':
          $ref: '#/components/responses/ListElectricityUsageForServicePoints406'
        '422':
          $ref: '#/components/responses/ListElectricityUsageForServicePoints422'
components:
  parameters:
    HeaderXFAPIInteractionId:
      name: x-fapi-interaction-id
      description: An **[[RFC4122]](#nref-RFC4122)** UUID used as a correlation id. If provided, the data holder **MUST** play back this value in the _x-fapi-interaction-id_ response header. If not provided a **[[RFC4122]](#nref-RFC4122)** UUID value is required to be provided in the response header to track the interaction.
      in: header
      schema:
        type: string
    QueryOldestDate:
      name: oldest-date
      in: query
      description: Constrain the request to records with effective date at or after this date. If absent defaults to _newest-date_ minus 24 months. Format is aligned to DateString common type.
      schema:
        type: string
      x-cds-type: DateString
    QueryEnergyIntervalReads:
      name: interval-reads
      description: Type of interval reads. Any one of the valid values for this field can be supplied. If absent defaults to `NONE`.
      in: query
      schema:
        type: string
        default: NONE
        enum:
        - NONE
        - MIN_30
        - FULL
    HeaderXV:
      name: x-v
      description: Version of the API endpoint requested by the client. Must be set to a positive integer. The endpoint should respond with the highest supported version between [_x-min-v_](#request-headers) and [_x-v_](#request-headers). If the value of [_x-min-v_](#request-headers) is equal to or higher than the value of [_x-v_](#request-headers) then the [_x-min-v_](#request-headers) header should be treated as absent. If all versions requested are not supported then the endpoint **MUST** respond with a `406 Not Acceptable`. See [HTTP Headers](#request-headers).
      in: header
      required: true
      schema:
        type: string
    HeaderXFAPICustomerIPAddress:
      name: x-fapi-customer-ip-address
      description: The customer's original IP address if the customer is currently logged in to the data recipient. The presence of this header indicates that the API is being called in a customer present context. Not to be included for unauthenticated calls.
      in: header
      schema:
        type: string
    HeaderXCDSClientHeaders:
      name: x-cds-client-headers
      description: The customer's original standard http headers [Base64](#common-field-types) encoded, including the original User-Agent header, if the customer is currently logged in to the data recipient. Mandatory for customer present calls. Not required for unattended or unauthenticated calls.
      in: header
      x-conditional: true
      schema:
        type: string
      x-cds-type: Base64
    QueryNewestDate:
      name: newest-date
      in: query
      description: Constrain the request to records with effective date at or before this date. If absent defaults to current date. Format is aligned to DateString common type.
      schema:
        type: string
      x-cds-type: DateString
    QueryPageSize:
      name: page-size
      description: Page size to request. Default is 25 (standard pagination).
      in: query
      schema:
        type: integer
        default: '25'
      x-cds-type: PositiveInteger
    HeaderXFAPIAuthDate:
      name: x-fapi-auth-date
      description: The time when the customer last logged in to the Data Recipient Software Product as described in **[[FAPI-1.0-Baseline]](#nref-FAPI-1-0-Baseline)**. Required for all resource calls (customer present and unattended). Not required for unauthenticated calls.
      in: header
      x-conditional: true
      schema:
        type: string
    PathServicePointId:
      name: servicePointId
      description: The _servicePointId_ to obtain data for. _servicePointId_ values are returned by service point list endpoints. Note that it is not a _nationalMeteringId_.
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/EnergyServicePointId'
    QueryPage:
      name: page
      description: Page of results to request (standard pagination).
      in: query
      schema:
        type: integer
        default: '1'
      x-cds-type: PositiveInteger
    HeaderXMinV:
      name: x-min-v
      description: Minimum version of the API endpoint requested by the client. Must be set to a positive integer if provided. The endpoint should respond with the highest supported version between [_x-min-v_](#request-headers) and [_x-v_](#request-headers). If all versions requested are not supported then the endpoint **MUST** respond with a `406 Not Acceptable`.
      in: header
      schema:
        type: string
  responses:
    ListElectricityUsageBulk400:
      description: The following error codes **MUST** be supported:<br/><ul class="error-code-list"><li>[400 - Invalid Field](#error-400-field-invalid)</li><li>[400 - Missing Required Field](#error-400-field-missing)</li><li>[400 - Invalid Date](#error-400-field-invalid-date-time)</li><li>[400 - Invalid Page Size](#error-400-field-invalid-page-size)</li><li>[400 - Invalid Version](#error-400-header-invalid-version)</li></ul>
      headers:
        x-fapi-interaction-id:
          $ref: '#/components/headers/XFAPIInteractionId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PrimaryResponseErrorListV1'
    ListElectricityUsageBulk200:
      description: Successful response
      headers:
        x-v:
          $ref: '#/components/headers/XV'
        x-fapi-interaction-id:
          $ref: '#/components/headers/XFAPIInteractionId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/EnergyUsageListResponse'
    ListElectricityUsageForServicePoints422:
      description: The following error codes **MUST** be supported:<br/><ul class="error-code-list"><li>[422 - Invalid Page](#error-422-field-invalid-page)</li><li>[422 - Unavailable Service Point](#error-422-unavailable-service-point)</li><li>[422 - Invalid Service Point](#error-422-invalid-service-point)</li></ul>
      headers:
        x-fapi-interaction-id:
          $ref: '#/components/headers/XFAPIInteractionId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PrimaryResponseErrorListV1'
    ListElectricityUsageForServicePoints400:
      description: The following error codes **MUST** be supported:<br/><ul class="error-code-list"><li>[400 - Invalid Field](#error-400-field-invalid)</li><li>[400 - Missing Required Field](#error-400-field-missing)</li><li>[400 - Invalid Date](#error-400-field-invalid-date-time)</li><li>[400 - Invalid Page Size](#error-400-field-invalid-page-size)</li><li>[400 - Invalid Version](#error-400-header-invalid-version)</li></ul>
      headers:
        x-fapi-interaction-id:
          $ref: '#/components/headers/XFAPIInteractionId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PrimaryResponseErrorListV1'
    GetElectricityServicePointUsage400:
      description: The following error codes **MUST** be supported:<br/><ul class="error-code-list"><li>[400 - Invalid Field](#error-400-field-invalid)</li><li>[400 - Missing Required Field](#error-400-field-missing)</li><li>[400 - Invalid Date](#error-400-field-invalid-date-time)</li><li>[400 - Invalid Page Size](#error-400-field-invalid-page-size)</li><li>[400 - Invalid Version](#error-400-header-invalid-version)</li></ul>
      headers:
        x-fapi-interaction-id:
          $ref: '#/components/headers/XFAPIInteractionId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PrimaryResponseErrorListV1'
    GetElectricityServicePointUsage200:
      description: Successful response
      headers:
        x-v:
          $ref: '#/components/headers/XV'
        x-fapi-interaction-id:
          $ref: '#/components/headers/XFAPIInteractionId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/EnergyUsageListResponse'
    GetElectricityServicePointUsage406:
      description: The following error codes **MUST** be supported:<br/><ul class="error-code-list"><li>[406 - Unsupported Version](#error-406-header-unsupported-version)</li></ul>
      headers:
        x-fapi-interaction-id:
          $ref: '#/components/headers/XFAPIInteractionId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PrimaryResponseErrorListV1'
    ListElectricityUsageForServicePoints200:
      description: Successful response
      headers:
        x-v:
          $ref: '#/components/headers/XV'
        x-fapi-interaction-id:
          $ref: '#/components/headers/XFAPIInteractionId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/EnergyUsageListResponse'
    ListElectricityUsageBulk406:
      description: The following error codes **MUST** be supported:<br/><ul class="error-code-list"><li>[406 - Unsupported Version](#error-406-header-unsupported-version)</li></ul>
      headers:
        x-fapi-interaction-id:
          $ref: '#/components/headers/XFAPIInteractionId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PrimaryResponseErrorListV1'
    ListElectricityUsageForServicePoints406:
      description: The following error codes **MUST** be supported:<br/><ul class="error-code-list"><li>[406 - Unsupported Version](#error-406-header-unsupported-version)</li></ul>
      headers:
        x-fapi-interaction-id:
          $ref: '#/components/headers/XFAPIInteractionId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PrimaryResponseErrorListV1'
    ListElectricityUsageBulk422:
      description: The following error codes **MUST** be supported:<br/><ul class="error-code-list"><li>[422 - Invalid Page](#error-422-field-invalid-page)</li></ul>
      headers:
        x-fapi-interaction-id:
          $ref: '#/components/headers/XFAPIInteractionId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PrimaryResponseErrorListV1'
    GetElectricityServicePointUsage422:
      description: The following error codes **MUST** be supported:<br/><ul class="error-code-list"><li>[422 - Invalid Page](#error-422-field-invalid-page)</li></ul>
      headers:
        x-fapi-interaction-id:
          $ref: '#/components/headers/XFAPIInteractionId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PrimaryResponseErrorListV1'
    GetElectricityServicePointUsage404:
      description: The following error codes **MUST** be supported:<br/><ul class="error-code-list"><li>[404 - Unavailable Service Point](#error-404-unavailable-service-point)</li><li>[404 - Invalid Service Point](#error-404-invalid-service-point)</li></ul>
      headers:
        x-fapi-interaction-id:
          $ref: '#/components/headers/XFAPIInteractionId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PrimaryResponseErrorListV1'
  schemas:
    LinksPaginated:
      type: object
      required:
      - self
      x-conditional:
      - first
      - prev
      - next
      - last
      properties:
        self:
          type: string
          description: Fully qualified link that generated the current response document.
          x-cds-type: URIString
        first:
          type: string
          description: URI to the first page of this set. Mandatory if this response is not the first page.
          x-cds-type: URIString
        prev:
          type: string
          description: URI to the previous page of this set. Mandatory if this response is not the first page.
          x-cds-type: URIString
        next:
          type: string
          description: URI to the next page of this set. Mandatory if this response is not the last page.
          x-cds-type: URIString
        last:
          type: string
          description: URI to the last page of this set. Mandatory if this response is not the last page.
          x-cds-type: URIString
    EnergyUsageListResponse:
      type: object
      required:
      - data
      - links
      - meta
      properties:
        data:
          type: object
          required:
          - reads
          properties:
            reads:
              description: Array of meter reads sorted by NMI in ascending order followed by _readStartDate_ in descending order.
              type: array
              items:
                $ref: '#/components/schemas/EnergyUsageRead'
        links:
          $ref: '#/components/schemas/LinksPaginated'
        meta:
          $ref: '#/components/schemas/MetaPaginated'
    Meta:
      type: object
    EnergyServicePointId:
      type: string
      description: A unique identifier for an Energy service point, generated according to [CDR ID Permanence](#id-permanence) requirements.
      x-cds-type: ASCIIString
    PrimaryResponseErrorListV1:
      type: object
      required:
      - errors
      properties:
        errors:
          description: List of errors.
          type: array
          items:
            $ref: '#/components/schemas/PrimaryErrorV1'
    MetaPaginated:
      type: object
      required:
      - totalPages
      - totalRecords
      properties:
        totalRecords:
          type: integer
          description: The total number of records in the full set. See [pagination](#pagination).
          x-cds-type: NaturalNumber
        totalPages:
          type: integer
          description: The total number of pages in the full set. See [pagination](#pagination).
          x-cds-type: NaturalNumber
    PrimaryErrorV1:
      type: object
      allOf:
      - type: object
        properties:
          isSecondaryDataHolderError:
            type: boolean
            description: Indicates the error was propagated from a designated secondary data holder.
            default: false
      - $ref: '#/components/schemas/ErrorV2'
    ErrorV2:
      type: object
      required:
      - code
      - title
      - detail
      x-conditional:
      - meta
      properties:
        code:
          type: string
          description: The code of the error encountered. Where the error is specific to the respondent, an application-specific error code, expressed as a string value. If the error is application-specific, the URN code that the specific error extends must be provided in the _meta_ object. Otherwise, the value is the error code URN.
        title:
          type: string
          description: A short, human-readable summary of the problem that **MUST NOT** change from occurrence to occurrence of the problem represented by the error code.
        detail:
          type: string
          description: A human-readable explanation specific to this occurrence of the problem.
        meta:
          type: object
          x-conditional:
          - urn
          description: Additional data for customised error codes.
          properties:
            urn:
              type: string
              description: The CDR error code URN which the application-specific error code extends. Mandatory if the error _code_ is an application-specific error rather than a standardised error code.
    RequestServicePointIdListV1:
      type: object
      required:
      - data
      properties:
        data:
          type: object
          required:
          - servicePointIds
          properties:
            servicePointIds:
              type: array
              description: Array of _servicePointId_ values to obtain data for.
              items:
                $ref: '#/components/schemas/EnergyServicePointId'
        meta:
          $ref: '#/components/schemas/Meta'
    EnergyUsageRead:
      type: object
      required:
      - servicePointId
      - registerSuffix
      - readStartDate
      - readUType
      x-conditional:
      - basicRead
      - intervalRead
      properties:
        servicePointId:
          description: Unique identifier for the service point.
          allOf:
          - $ref: '#/components/schemas/EnergyServicePointId'
        registerId:
          description: Register ID of the meter register where the meter reads are obtained.
          type: string
        registerSuffix:
          description: Register suffix of the meter register where the meter reads are obtained.
          type: string
        meterId:
          description: Meter id/serial number as it appears in customer's bill. ID permanence rules do not apply.
          type: string
        controlledLoad:
          description: Indicates whether the energy recorded by this register is created under a Controlled Load regime.
          type: boolean
        readStartDate:
          description: Date when the meter reads start in AEST and assumed to start from 12:00am AEST.
          type: string
          x-cds-type: DateString
        readEndDate:
          description: Date when the meter reads end in AEST. If absent then assumed to be equal to _readStartDate_. In this case the entry represents data for a single date specified by _readStartDate_.
          type: string
          x-cds-type: DateString
        unitOfMeasure:
          description: Unit of measure of the meter reads. Refer to Appendix B of <a href='https://www.aemo.com.au/-/media/files/stakeholder_consultation/consultations/nem-consultations/2019/5ms-metering-package-2/final-determination/mdff-specification-nem12-nem13-v21-final-determination-clean.pdf?la=en&hash=03FCBA0D60E091DE00F2361AE76206EA'>MDFF Specification NEM12 NEM13 v2.1</a> for a list of possible values.
          type: string
          x-cds-type: ExternalRef
        readUType:
          description: Specify the type of the meter read data.
          type: string
          enum:
          - basicRead
          - intervalRead
        basicRead:
          description: Mandatory if _readUType_ is set to `basicRead`.
          type: object
          required:
          - value
          properties:
            quality:
              description: The quality of the read taken. If absent then assumed to be `ACTUAL`.
              type: string
              enum:
              - ACTUAL
              - SUBSTITUTE
              - FINAL_SUBSTITUTE
              default: ACTUAL
            value:
              description: Meter read value. If positive then it means consumption, if negative it means export.
              type: number
        intervalRead:
          description: Mandatory if _readUType_ is set to `intervalRead`.
          type: object
          required:
          - aggregateValue
          x-conditional:
          - readIntervalLength
          - intervalReads
          - readQualities
          properties:
            readIntervalLength:
              description: Read interval length in minutes. Required when _interval-reads_ query parameter equals `FULL` or `MIN_30`.
              type: integer
              x-cds-type: PositiveInteger
            aggregateValue:
              description: The aggregate sum of the interval read values. If positive then it means net consumption, if negative it means net export.
              type: number
            intervalReads:
              description: Array of Interval read values. If positive then it means consumption, if negative it means export. Required when _interval-reads_ query parameter equals `FULL` or `MIN_30`.<br>Each read value indicates the read for the interval specified by _readIntervalLength_ beginning at midnight of _readStartDate_ (for example 00:00 to 00:30 would be the first reading in a 30 minute Interval).
              type: array
              items:
                type: number
            readQualities:
              description: ' Specifies quality of reads that are not `ACTUAL`. For read indices that are not specified, quality is assumed to be `ACTUAL`. If not present, all quality of all reads are assumed to be actual. Required when _interval-reads_ query parameter equals `FULL` or `MIN_30`.'
              type: array
              items:
                type: object
                required:
                - startInterval
                - endInterval
                - quality
                properties:
                  startInterval:
                    description: Start interval for read quality flag. First read begins at `1`.
                    type: integer
                    x-cds-type: PositiveInteger
                    example: 1
                  endInterval:
                    description: End interval for read quality flag.
                    type: integer
                    x-cds-type: PositiveInteger
                    example: 1
                  quality:
                    description: The quality of the read taken.
                    type: string
                    enum:
                    - SUBSTITUTE
                    - FINAL_SUBSTITUTE
  headers:
    XV:
      description: The [payload version](#response-headers) that the endpoint has responded with.
      required: true
      schema:
        type: string
    XFAPIInteractionId:
      description: An **[[RFC4122]](#nref-RFC4122)** UUID used as a correlation id. If provided, the data holder **MUST** play back this value in the _x-fapi-interaction-id_ response header. If not provided a **[[RFC4122]](#nref-RFC4122)** UUID value is required to be provided in the response header to track the interaction.
      required: true
      schema:
        type: string
  requestBodies:
    RequestServicePointIds:
      description: Request payload containing a list of _servicePointId_ values to obtain data for.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RequestServicePointIdListV1'
      required: true