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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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 MDFF Specification NEM12 NEM13 v2.1 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`.
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