Consumer Data Right (Energy) Electricity Usage (SR) API

openapi: 3.2.0
info:
  contact:
    email: contact@dsb.gov.au
    name: Data Standards Body
    url: https://dsb.gov.au/
  description: Specifications for resource endpoints applicable to secondary data holders in the Energy sector.
  title: CDR Energy Secondary Data Holder Electricity Usage (SR) API
  version: 1.36.0
servers:
- description: TLS
  url: https://tls.sdh.example.com/cds-au/v1
tags:
- description: Electricity Usage (SR) endpoints
  name: Electricity Usage (SR)
  x-shortName: Usage
paths:
  /secondary/energy/electricity/servicepoints/{servicePointId}/usage:
    get:
      description: Obtain a list of electricity usage data from a particular service point.
      operationId: getElectricityServicePointUsageSR
      parameters:
      - description: The independent ID of the service point, known in the industry as the NMI. The _servicePointId_ will be replaced with NMI for all interactions between Data Holder and AEMO.
        explode: false
        in: path
        name: servicePointId
        required: true
        schema:
          $ref: '#/components/schemas/EnergySDHServicePointId'
        style: simple
      - 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.
        explode: true
        in: query
        name: oldest-date
        required: false
        schema:
          type: string
        style: form
        x-cds-type: DateString
      - 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.
        explode: true
        in: query
        name: newest-date
        required: false
        schema:
          type: string
        style: form
        x-cds-type: DateString
      - description: Type of interval reads. Any one of the valid values for this field can be supplied. If absent defaults to `NONE`.
        explode: true
        in: query
        name: interval-reads
        required: false
        schema:
          default: NONE
          enum:
          - NONE
          - MIN_30
          - FULL
          type: string
        style: form
      - description: Page of results to request (standard pagination).
        explode: true
        in: query
        name: page
        required: false
        schema:
          type: integer
        style: form
        x-cds-type: PositiveInteger
      - description: Page size to request. Default is 25 (standard pagination).
        explode: true
        in: query
        name: page-size
        required: false
        schema:
          type: integer
        style: form
        x-cds-type: PositiveInteger
      - 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).
        explode: false
        in: header
        name: x-v
        required: true
        schema:
          type: string
        style: simple
      - 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`.
        explode: false
        in: header
        name: x-min-v
        required: false
        schema:
          type: string
        style: simple
      - description: The _x-fapi-interaction-id_ header value provided by the Data Recipient. If not supplied by the Data Recipient, the primary Data Holder **MUST** create a unique **[[RFC4122]](#nref-RFC4122)** UUID value for the _x-fapi-interaction-id_ header.
        explode: false
        in: header
        name: x-fapi-interaction-id
        required: true
        schema:
          type: string
        style: simple
      - description: A unique string representing a consent arrangement between a Data Recipient Software Product and Data Holder for a given consumer. The identifier **MUST** be unique per customer according to the definition of customer in the CDR Federation section of this profile. The _x-cds-arrangement_ should contain the arrangement ID for the consent that the request is being made under and will be used for tracing and audit purposes. This field **MUST** be populated but AEMO **MUST NOT** seek to validate the consent associated with the arrangement.
        explode: false
        in: header
        name: x-cds-arrangement
        required: true
        schema:
          type: string
        style: simple
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnergyUsageListResponse'
          description: Successful response
          headers:
            x-v:
              $ref: '#/components/headers/XV'
            x-fapi-interaction-id:
              $ref: '#/components/headers/XFAPIInteractionId'
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseErrorListV2'
          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'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseErrorListV2'
          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'
        '406':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseErrorListV2'
          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'
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseErrorListV2'
          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'
      summary: Get Usage For Service Point (SR)
      tags:
      - Electricity Usage (SR)
      x-restricted-access: AEMO
      x-version: '1'
  /secondary/energy/electricity/servicepoints/usage:
    post:
      description: Obtain the electricity usage data for a specific set of service points.
      operationId: listElectricityUsageForServicePointsSR
      parameters:
      - 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.
        explode: true
        in: query
        name: oldest-date
        required: false
        schema:
          type: string
        style: form
        x-cds-type: DateString
      - 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.
        explode: true
        in: query
        name: newest-date
        required: false
        schema:
          type: string
        style: form
        x-cds-type: DateString
      - description: Type of interval reads. Any one of the valid values for this field can be supplied. If absent defaults to `NONE`.
        explode: true
        in: query
        name: interval-reads
        required: false
        schema:
          default: NONE
          enum:
          - NONE
          - MIN_30
          - FULL
          type: string
        style: form
      - description: Page of results to request (standard pagination).
        explode: true
        in: query
        name: page
        required: false
        schema:
          type: integer
        style: form
        x-cds-type: PositiveInteger
      - description: Page size to request. Default is 25 (standard pagination).
        explode: true
        in: query
        name: page-size
        required: false
        schema:
          type: integer
        style: form
        x-cds-type: PositiveInteger
      - 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).
        explode: false
        in: header
        name: x-v
        required: true
        schema:
          type: string
        style: simple
      - 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`.
        explode: false
        in: header
        name: x-min-v
        required: false
        schema:
          type: string
        style: simple
      - description: The _x-fapi-interaction-id_ header value provided by the Data Recipient. If not supplied by the Data Recipient, the primary Data Holder **MUST** create a unique **[[RFC4122]](#nref-RFC4122)** UUID value for the _x-fapi-interaction-id_ header.
        explode: false
        in: header
        name: x-fapi-interaction-id
        required: true
        schema:
          type: string
        style: simple
      - description: A unique string representing a consent arrangement between a Data Recipient Software Product and Data Holder for a given consumer. The identifier **MUST** be unique per customer according to the definition of customer in the CDR Federation section of this profile. The _x-cds-arrangement_ should contain the arrangement ID for the consent that the request is being made under and will be used for tracing and audit purposes. This field **MUST** be populated but AEMO **MUST NOT** seek to validate the consent associated with the arrangement.
        explode: false
        in: header
        name: x-cds-arrangement
        required: true
        schema:
          type: string
        style: simple
      requestBody:
        $ref: '#/components/requestBodies/RequestSDHServicePointIds'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnergyUsageListResponse'
          description: Successful response
          headers:
            x-v:
              $ref: '#/components/headers/XV'
            x-fapi-interaction-id:
              $ref: '#/components/headers/XFAPIInteractionId'
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseErrorListV2'
          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'
        '406':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseErrorListV2'
          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'
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseErrorListV2'
          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'
      summary: Get Usage For Specific Service Points (SR)
      tags:
      - Electricity Usage (SR)
      x-restricted-access: AEMO
      x-version: '1'
components:
  schemas:
    RequestSDHServicePointIdListV1_data:
      properties:
        servicePointIds:
          description: Array of _servicePointId_ values to obtain data for.
          items:
            $ref: '#/components/schemas/EnergySDHServicePointId'
          type: array
      required:
      - servicePointIds
      type: object
    EnergyUsageRead_intervalRead_readQualities:
      properties:
        startInterval:
          description: Start interval for read quality flag. First read begins at `1`.
          example: 1
          type: integer
          x-cds-type: PositiveInteger
        endInterval:
          description: End interval for read quality flag.
          example: 1
          type: integer
          x-cds-type: PositiveInteger
        quality:
          description: The quality of the read taken.
          enum:
          - SUBSTITUTE
          - FINAL_SUBSTITUTE
          type: string
      required:
      - endInterval
      - quality
      - startInterval
      type: object
    EnergyUsageRead:
      properties:
        servicePointId:
          $ref: '#/components/schemas/EnergySDHServicePointId'
        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.
          enum:
          - basicRead
          - intervalRead
          type: string
        basicRead:
          $ref: '#/components/schemas/EnergyUsageRead_basicRead'
        intervalRead:
          $ref: '#/components/schemas/EnergyUsageRead_intervalRead'
      required:
      - readStartDate
      - readUType
      - registerSuffix
      - servicePointId
      type: object
      x-conditional:
      - basicRead
      - intervalRead
    ResponseErrorListV2:
      properties:
        errors:
          description: List of errors.
          items:
            $ref: '#/components/schemas/ErrorV2'
          type: array
      required:
      - errors
      type: object
    EnergyUsageListResponse:
      properties:
        data:
          $ref: '#/components/schemas/EnergyUsageListResponse_data'
        links:
          $ref: '#/components/schemas/LinksPaginated'
        meta:
          $ref: '#/components/schemas/MetaPaginated'
      required:
      - data
      - links
      - meta
      type: object
    EnergyUsageRead_basicRead:
      description: Mandatory if _readUType_ is set to `basicRead`.
      properties:
        quality:
          default: ACTUAL
          description: The quality of the read taken. If absent then assumed to be `ACTUAL`.
          enum:
          - ACTUAL
          - SUBSTITUTE
          - FINAL_SUBSTITUTE
          type: string
        value:
          description: Meter read value. If positive then it means consumption, if negative it means export.
          type: number
      required:
      - value
      type: object
    ErrorV2:
      properties:
        code:
          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.
          type: string
        title:
          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.
          type: string
        detail:
          description: A human-readable explanation specific to this occurrence of the problem.
          type: string
        meta:
          $ref: '#/components/schemas/ErrorV2_meta'
      required:
      - code
      - detail
      - title
      type: object
      x-conditional:
      - meta
    EnergyUsageListResponse_data:
      properties:
        reads:
          description: Array of meter reads sorted by NMI in ascending order followed by _readStartDate_ in descending order.
          items:
            $ref: '#/components/schemas/EnergyUsageRead'
          type: array
      required:
      - reads
      type: object
    ErrorV2_meta:
      description: Additional data for customised error codes.
      properties:
        urn:
          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.
          type: string
      type: object
      x-conditional:
      - urn
    EnergyUsageRead_intervalRead:
      description: Mandatory if _readUType_ is set to `intervalRead`.
      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).
          items:
            type: number
          type: array
        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`.
          items:
            $ref: '#/components/schemas/EnergyUsageRead_intervalRead_readQualities'
          type: array
      required:
      - aggregateValue
      type: object
      x-conditional:
      - readIntervalLength
      - intervalReads
      - readQualities
    RequestSDHServicePointIdListV1:
      properties:
        data:
          $ref: '#/components/schemas/RequestSDHServicePointIdListV1_data'
        meta:
          $ref: '#/components/schemas/Meta'
      required:
      - data
      type: object
    EnergySDHServicePointId:
      description: The independent ID of the service point, known in the industry as the National Meter Identifier (NMI). Note that the _servicePointId_ will be replaced with NMI for all interactions between Data Holder and AEMO.
      type: string
      x-cds-type: ASCIIString
    MetaPaginated:
      properties:
        totalRecords:
          description: The total number of records in the full set. See [pagination](#pagination).
          type: integer
          x-cds-type: NaturalNumber
        totalPages:
          description: The total number of pages in the full set. See [pagination](#pagination).
          type: integer
          x-cds-type: NaturalNumber
      required:
      - totalPages
      - totalRecords
      type: object
    Meta:
      type: object
    LinksPaginated:
      properties:
        self:
          description: Fully qualified link that generated the current response document.
          type: string
          x-cds-type: URIString
        first:
          description: URI to the first page of this set. Mandatory if this response is not the first page.
          type: string
          x-cds-type: URIString
        prev:
          description: URI to the previous page of this set. Mandatory if this response is not the first page.
          type: string
          x-cds-type: URIString
        next:
          description: URI to the next page of this set. Mandatory if this response is not the last page.
          type: string
          x-cds-type: URIString
        last:
          description: URI to the last page of this set. Mandatory if this response is not the last page.
          type: string
          x-cds-type: URIString
      required:
      - self
      type: object
      x-conditional:
      - first
      - prev
      - next
      - last
  requestBodies:
    RequestSDHServicePointIds:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RequestSDHServicePointIdListV1'
      description: Request payload containing a list of _servicePointId_ values to obtain data for.
      required: true
  headers:
    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.
      explode: false
      required: true
      schema:
        type: string
      style: simple
    XV:
      description: The [payload version](#response-headers) that the endpoint has responded with.
      explode: false
      required: true
      schema:
        type: string
      style: simple