Consumer Data Right (Energy) Distributed Energy Resources (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 Distributed Energy Resources (SR) API
  version: 1.36.0
servers:
- description: TLS
  url: https://tls.sdh.example.com/cds-au/v1
tags:
- description: Distributed Energy Resource (SR) endpoints
  name: Distributed Energy Resources (SR)
  x-shortName: Distributed Energy Resources
paths:
  /secondary/energy/electricity/servicepoints/{servicePointId}/der:
    get:
      description: Obtain a list of DER data from a particular service point.
      operationId: getElectricityDERForServicePointSR
      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: 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/EnergyDerDetailResponse'
          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 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'
      summary: Get DER For Service Point (SR)
      tags:
      - Distributed Energy Resources (SR)
      x-restricted-access: AEMO
      x-version: '1'
  /secondary/energy/electricity/servicepoints/der:
    post:
      description: Obtain DER data for a specific set of service points.
      operationId: listElectricityDERForSpecificServicePointsSR
      parameters:
      - 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/EnergyDerListResponse'
          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 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 DER For Specific Service Points (SR)
      tags:
      - Distributed Energy Resources (SR)
      x-restricted-access: AEMO
      x-version: '1'
components:
  schemas:
    EnergyDerRecord_acConnections:
      properties:
        connectionIdentifier:
          description: AC Connection ID as defined in the DER register. Does not align with CDR ID permanence standards.
          type: number
        count:
          description: Number of AC Connections in the group. For the suite of AC Connections to be considered as a group, all of the AC Connections included must have the same attributes.
          type: integer
          x-cds-type: PositiveInteger
        equipmentType:
          default: OTHER
          description: Indicates whether the DER device is connected via an inverter (and what category of inverter it is) or not (e.g., rotating machine). If absent, assume equipment type to be `OTHER`.
          enum:
          - INVERTER
          - OTHER
          type: string
        manufacturerName:
          description: The name of the inverter manufacturer. Mandatory if _equipmentType_ is `INVERTER`.
          type: string
        inverterSeries:
          description: The inverter series. Mandatory if _equipmentType_ is `INVERTER`.
          type: string
        inverterModelNumber:
          description: The inverter model number. Mandatory if _equipmentType_ is `INVERTER`.
          type: string
        commissioningDate:
          description: The date that the DER installation is commissioned.
          type: string
          x-cds-type: DateString
        status:
          description: Code used to indicate the status of the Inverter. This will be used to identify if an inverter is active or inactive or decommissioned.
          enum:
          - ACTIVE
          - INACTIVE
          - DECOMMISSIONED
          type: string
        inverterDeviceCapacity:
          description: The rated AC output power that is listed in the product specified by the manufacturer. Mandatory if _equipmentType_ is `INVERTER`. Default is `0` if value not known.
          type: number
        derDevices:
          items:
            $ref: '#/components/schemas/EnergyDerRecord_derDevices'
          type: array
      required:
      - commissioningDate
      - connectionIdentifier
      - count
      - derDevices
      - status
      type: object
      x-conditional:
      - manufacturerName
      - inverterSeries
      - inverterModelNumber
      - inverterDeviceCapacity
    Links:
      properties:
        self:
          description: Fully qualified link that generated the current response document.
          type: string
          x-cds-type: URIString
      required:
      - self
      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
    RequestSDHServicePointIdListV1:
      properties:
        data:
          $ref: '#/components/schemas/RequestSDHServicePointIdListV1_data'
        meta:
          $ref: '#/components/schemas/Meta'
      required:
      - data
      type: object
    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
    RequestSDHServicePointIdListV1_data:
      properties:
        servicePointIds:
          description: Array of _servicePointId_ values to obtain data for.
          items:
            $ref: '#/components/schemas/EnergySDHServicePointId'
          type: array
      required:
      - servicePointIds
      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
    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
    EnergyDerDetailResponse:
      properties:
        data:
          $ref: '#/components/schemas/EnergyDerRecord'
        links:
          $ref: '#/components/schemas/Links'
        meta:
          $ref: '#/components/schemas/Meta'
      required:
      - data
      - links
      type: object
    EnergyDerRecord_derDevices:
      properties:
        deviceIdentifier:
          description: Unique identifier for a single DER device or a group of DER devices with the same attributes. Does not align with CDR ID permanence standards.
          type: number
        count:
          description: Number of devices in the group of DER devices.
          type: integer
          x-cds-type: PositiveInteger
        manufacturer:
          description: The name of the device manufacturer. If absent then assumed to be "unknown".
          type: string
        modelNumber:
          description: The model number of the device. If absent then assumed to be "unknown".
          type: string
        status:
          description: Code used to indicate the status of the device. This will be used to identify if an inverter is active or inactive or decommissioned.
          enum:
          - ACTIVE
          - INACTIVE
          - DECOMMISSIONED
          type: string
        type:
          description: Used to indicate the primary technology used in the DER device.
          enum:
          - FOSSIL
          - HYDRO
          - WIND
          - SOLAR_PV
          - RENEWABLE
          - GEOTHERMAL
          - STORAGE
          - OTHER
          type: string
        subtype:
          description: Used to indicate the primary technology used in the DER device. This field is also used to record for example the battery chemistry, or the type of PV panel. It is also used to record if a battery is contained in an electric vehicle connected in a vehicle-to-grid arrangement. If absent then assumed to be "other".
          type: string
        nominalRatedCapacity:
          description: Maximum output in kVA that is listed in the product specification by the manufacturer. This refers to the capacity of each unit within the device group. Default is `0` if value not known.
          type: number
        nominalStorageCapacity:
          description: Maximum storage capacity in kVAh. This refers to the capacity of each storage module within the device group. Mandatory if type is equal to `STORAGE`. Default is `0` if value not known.
          type: number
      required:
      - count
      - deviceIdentifier
      - nominalRatedCapacity
      - type
      type: object
      x-conditional:
      - nominalStorageCapacity
    ResponseErrorListV2:
      properties:
        errors:
          description: List of errors.
          items:
            $ref: '#/components/schemas/ErrorV2'
          type: array
      required:
      - errors
      type: object
    EnergyDerRecord:
      properties:
        servicePointId:
          $ref: '#/components/schemas/EnergySDHServicePointId'
        approvedCapacity:
          description: Approved small generating unit capacity as agreed with NSP in the connection agreement, expressed in kVA. Value of `0` indicates no DER record exists for the given _servicePointId_.
          type: number
        availablePhasesCount:
          description: The number of phases available for the installation of DER. Acceptable values are `0`, `1`, `2` or `3`. Value of `0` indicates no DER record exists for the given _servicePointId_.
          maximum: 3
          minimum: 0
          type: integer
          x-cds-type: NaturalNumber
        installedPhasesCount:
          description: The number of phases that DER is connected to. Acceptable values are `0`, `1`, `2` or `3`. Value of `0` indicates no DER record exists for the given _servicePointId_.
          maximum: 3
          minimum: 0
          type: integer
          x-cds-type: NaturalNumber
        islandableInstallation:
          description: For identification of small generating units designed with the ability to operate in an islanded mode.
          type: boolean
        hasCentralProtectionControl:
          default: false
          description: For DER installations where NSPs specify the need for additional forms of protection above those inbuilt in an inverter. If absent then assumed to be `false`.
          type: boolean
        protectionMode:
          $ref: '#/components/schemas/EnergyDerRecord_protectionMode'
        acConnections:
          items:
            $ref: '#/components/schemas/EnergyDerRecord_acConnections'
          type: array
      required:
      - acConnections
      - approvedCapacity
      - availablePhasesCount
      - installedPhasesCount
      - islandableInstallation
      - servicePointId
      type: object
      x-conditional:
      - protectionMode
    EnergyDerListResponse:
      properties:
        data:
          $ref: '#/components/schemas/EnergyDerListResponse_data'
        links:
          $ref: '#/components/schemas/LinksPaginated'
        meta:
          $ref: '#/components/schemas/MetaPaginated'
      required:
      - data
      - links
      - meta
      type: object
    EnergyDerListResponse_data:
      properties:
        derRecords:
          description: Array of meter reads.
          items:
            $ref: '#/components/schemas/EnergyDerRecord'
          type: array
      required:
      - derRecords
      type: object
    EnergyDerRecord_protectionMode:
      description: Required only when the _hasCentralProtectionControl_ flag is set to `true`. One or more of the object fields will be provided to describe the protection modes in place.
      properties:
        exportLimitKva:
          description: Maximum amount of power (kVA) that may be exported from a connection point to the grid, as monitored by a control/relay function. An absent value indicates no limit.
          type: number
        underFrequencyProtection:
          description: Protective function limit in Hz.
          type: number
        underFrequencyProtectionDelay:
          description: Trip delay time in seconds.
          type: number
        overFrequencyProtection:
          description: Protective function limit in Hz.
          type: number
        overFrequencyProtectionDelay:
          description: Trip delay time in seconds.
          type: number
        underVoltageProtection:
          description: Protective function limit in V.
          type: number
        underVoltageProtectionDelay:
          description: Trip delay time in seconds.
          type: number
        overVoltageProtection:
          description: Protective function limit in V.
          type: number
        overVoltageProtectionDelay:
          description: Trip delay time in seconds.
          type: number
        sustainedOverVoltage:
          description: Sustained over voltage.
          type: number
        sustainedOverVoltageDelay:
          description: Sustained Over voltage protection delay in seconds.
          type: number
        frequencyRateOfChange:
          description: Rate of change of frequency trip point (Hz/s).
          type: number
        voltageVectorShift:
          description: Trip angle in degrees.
          type: number
        interTripScheme:
          description: Description of the form of inter-trip (e.g., 'from local substation').
          type: string
        neutralVoltageDisplacement:
          description: Trip voltage.
          type: number
      type: object
  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