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 Service Points (SR) API version: 1.36.0 servers: - description: TLS url: https://tls.sdh.example.com/cds-au/v1 tags: - description: Electricity Service Point (SR) endpoints name: Electricity Service Points (SR) x-shortName: Service Points paths: /secondary/energy/electricity/servicepoints: post: description: 'Obtain a list of service points owned by the customer that has authorised the current session. Other Versions: [v1](includes/obsolete/get-service-points-SR-v1.html).' operationId: listElectricityServicePointsSR 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/EnergyServicePointListResponseV2' 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:
headers: 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. explode: false schema: type: string style: simple '406': content: application/json: schema: $ref: '#/components/schemas/ResponseErrorListV2' description: The following error codes **MUST** be supported:
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:
headers: x-fapi-interaction-id: $ref: '#/components/headers/XFAPIInteractionId' summary: Get Service Points (SR) tags: - Electricity Service Points (SR) x-restricted-access: AEMO x-version: '2' /secondary/energy/electricity/servicepoints/{servicePointId}: get: description: 'Obtain detailed standing information for a specific service point that is owned by the customer that has authorised the current session. Other Versions: [v1](includes/obsolete/get-service-point-detail-SR-v1.html).' operationId: getElectricityServicePointDetailSR 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/EnergyServicePointDetailResponseV2' 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:
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:
headers: 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. explode: false schema: type: string style: simple '406': content: application/json: schema: $ref: '#/components/schemas/ResponseErrorListV2' description: The following error codes **MUST** be supported:
headers: x-fapi-interaction-id: $ref: '#/components/headers/XFAPIInteractionId' summary: Get Service Point Detail (SR) tags: - Electricity Service Points (SR) x-restricted-access: AEMO x-version: '2' components: schemas: EnergyServicePointDetailV2_allOf_specifications: description: Technical characteristics of the meter. properties: status: description: 'A code to denote the status of the meter. Note the details of enumeration values below: ' enum: - CURRENT - DISCONNECTED type: string installationType: description: 'The metering Installation type code indicates whether the metering installation has to be manually read. Note the details of enumeration values below: ' enum: - BASIC - COMMS1 - COMMS2 - COMMS3 - COMMS4 - COMMS4C - COMMS4D - MRAM - MRIM - PROF - SAMPLE - UMCP - VICAMI - NCOLNUML type: string manufacturer: description: Free text field to identify the manufacturer of the installed meter. type: string model: description: Free text field to identify the meter manufacturer's designation for the meter model. type: string readType: description: 'Code to denote the method and frequency of Meter Reading. The value is formatted as follows: For example, ' type: string nextScheduledReadDate: description: This date is the next scheduled meter read date (NSRD) if a manual Meter Reading is required. type: string x-cds-type: DateString required: - installationType - status type: object EnergyServicePointListResponseV2: properties: data: $ref: '#/components/schemas/EnergyServicePointListResponseV2_data' links: $ref: '#/components/schemas/LinksPaginated' meta: $ref: '#/components/schemas/MetaPaginated' required: - data - links - meta type: object 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 EnergyServicePointDetailV2_allOf_registers: properties: registerId: description: Unique identifier of the register within this service point. Is not globally unique. type: string registerSuffix: description: Register suffix of the meter register where the meter reads are obtained. type: string averagedDailyLoad: description: The energy delivered through a connection point or metering point over an extended period normalised to a 'per day' basis (kWh). This value is calculated annually. type: number registerConsumptionType: description: Indicates the consumption type of register. enum: - INTERVAL - BASIC - PROFILE_DATA - ACTIVE_IMPORT - ACTIVE - REACTIVE_IMPORT - REACTIVE type: string networkTariffCode: description: The Network Tariff Code is a free text field containing a code supplied and published by the local network service provider. type: string unitOfMeasure: description: The unit of measure for data held in this register. type: string timeOfDay: description: Code to identify the time validity of register contents. enum: - ALLDAY - INTERVAL - PEAK - BUSINESS - SHOULDER - EVENING - OFFPEAK - CONTROLLED - DEMAND type: string multiplier: description: Multiplier required to take a register value and turn it into a value representing billable energy. type: number controlledLoad: description: Indicates whether the energy recorded by this register is created under a Controlled Load regime. type: boolean consumptionType: description: 'Actual/Subtractive Indicator. Note the details of enumeration values below: ' enum: - ACTUAL - CUMULATIVE type: string required: - registerConsumptionType - registerId type: object EnergyServicePointDetailV2_allOf_relatedParticipants: properties: party: description: The name of the party/organisation related to this service point. type: string role: description: 'The role performed by this participant in relation to the service point. Note the details of enumeration values below: ' enum: - FRMP - LNSP - DRSP type: string required: - party - role type: object 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 EnergyServicePointDetailResponseV2: properties: data: $ref: '#/components/schemas/EnergyServicePointDetailV2' links: $ref: '#/components/schemas/Links' meta: $ref: '#/components/schemas/Meta' required: - data - links type: object Meta: type: object EnergyServicePointDetailV2: allOf: - $ref: '#/components/schemas/EnergyServicePointV2' - $ref: '#/components/schemas/EnergyServicePointDetailV2_allOf' EnergyServicePointListResponseV2_data: properties: servicePoints: items: $ref: '#/components/schemas/EnergyServicePointV2' type: array required: - servicePoints 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 EnergyServicePointDetailV2_allOf: properties: distributionLossFactor: $ref: '#/components/schemas/EnergyServicePointDetailV2_allOf_distributionLossFactor' relatedParticipants: items: $ref: '#/components/schemas/EnergyServicePointDetailV2_allOf_relatedParticipants' type: array location: allOf: - $ref: '#/components/schemas/CommonPhysicalAddress' description: Location of the servicepoint. meters: description: The meters associated with the service point. This may be empty where there are no meters physically installed at the service point. items: $ref: '#/components/schemas/EnergyServicePointDetailV2_allOf_meters' type: array required: - distributionLossFactor - location - relatedParticipants 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 EnergyServicePointV2: properties: servicePointId: $ref: '#/components/schemas/EnergySDHServicePointId' nationalMeteringId: description: The independent ID of the service point, known in the industry as the NMI. type: string servicePointClassification: description: The classification of the service point as defined in MSATS procedures. enum: - EXTERNAL_PROFILE - GENERATOR - LARGE - SMALL - WHOLESALE - NON_CONTEST_UNMETERED_LOAD - NON_REGISTERED_EMBEDDED_GENERATOR - DISTRIBUTION_WHOLESALE type: string servicePointStatus: description: 'Code used to indicate the status of the service point. Note the details for the enumeration values below: ' enum: - ACTIVE - DE_ENERGISED - EXTINCT - GREENFIELD - OFF_MARKET type: string jurisdictionCode: description: 'Jurisdiction code to which the service point belongs. This code defines the jurisdictional rules which apply to the service point. Note the details of enumeration values below: ' enum: - ALL - ACT - NEM - NSW - QLD - SA - TAS - VIC type: string isGenerator: default: false description: This flag determines whether the energy at this connection point is to be treated as consumer load or as a generating unit (this may include generator auxiliary loads). If absent defaults to `false`.
**Note:** Only applicable for scheduled or semischeduled generators, does not indicate on site generation by consumer. type: boolean validFromDate: description: The latest start date from which the constituent data sets of this service point became valid. type: string x-cds-type: DateString lastUpdateDateTime: description: The date and time that the information for this service point was modified. type: string x-cds-type: DateTimeString lastConsumerChangeDate: description: The date the account holder changed for the NMI. type: string x-cds-type: DateString consumerProfile: $ref: '#/components/schemas/EnergyServicePointV2_consumerProfile' required: - jurisdictionCode - lastUpdateDateTime - nationalMeteringId - servicePointClassification - servicePointId - servicePointStatus - validFromDate 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 CommonPhysicalAddress: properties: addressUType: description: The type of address object present. enum: - paf - simple type: string simple: $ref: '#/components/schemas/CommonSimpleAddress' paf: $ref: '#/components/schemas/CommonPAFAddress' required: - addressUType type: object x-conditional: - simple - paf EnergyServicePointV2_consumerProfile: properties: classification: description: A code that defines the consumer class as defined in the National Energy Retail Regulations, or in overriding Jurisdictional instruments. enum: - BUSINESS - RESIDENTIAL type: string threshold: description: 'A code that defines the consumption threshold as defined in the National Energy Retail Regulations, or in overriding Jurisdictional instruments. Note the details of enumeration values below: ' enum: - LOW - MEDIUM - HIGH type: string type: object EnergyServicePointDetailV2_allOf_distributionLossFactor: properties: code: description: A code used to identify data loss factor for the service point values. Refer to AEMO distribution loss factor documents for each financial year to interpret. type: string description: description: Description of the data loss factor code and value. type: string lossValue: description: The value associated with the loss factor code. type: string required: - code - description - lossValue type: object EnergyServicePointDetailV2_allOf_meters: properties: meterId: description: The meter ID uniquely identifies a meter for a given service point. It is unique in the context of the service point. It is not globally unique. type: string specifications: $ref: '#/components/schemas/EnergyServicePointDetailV2_allOf_specifications' registers: description: Usage data registers available from the meter. This may be empty where there are no meters physically installed at the service point. items: $ref: '#/components/schemas/EnergyServicePointDetailV2_allOf_registers' type: array required: - meterId - specifications type: object ResponseErrorListV2: properties: errors: description: List of errors. items: $ref: '#/components/schemas/ErrorV2' type: array required: - errors type: object CommonSimpleAddress: description: Required if _addressUType_ is set to `simple`. properties: mailingName: description: Name of the individual or business formatted for inclusion in an address used for physical mail. type: string addressLine1: description: First line of the standard address object. type: string addressLine2: description: Second line of the standard address object. type: string addressLine3: description: Third line of the standard address object. type: string postcode: description: Mandatory for Australian addresses. type: string city: description: Name of the city or locality. type: string state: description: Free text if the country is not Australia. If country is Australia then must be one of the values defined by the [State Type Abbreviation](https://auspost.com.au/content/dam/auspost_corp/media/documents/australia-post-data-guide.pdf) in the PAF file format. `NSW`, `QLD`, `VIC`, `NT`, `WA`, `SA`, `TAS`, `ACT`, `AAT`. type: string country: default: AUS description: A valid [ISO 3166 Alpha-3](https://www.iso.org/iso-3166-country-codes.html) country code. Australia (`AUS`) is assumed if country is not present. type: string x-cds-type: ExternalRef required: - addressLine1 - city - state type: object x-conditional: - postcode CommonPAFAddress: description: Australian address formatted according to the file format defined by the [PAF file format](https://auspost.com.au/content/dam/auspost_corp/media/documents/australia-post-data-guide.pdf). Required if _addressUType_ is set to `paf`. properties: dpid: description: Unique identifier for an address as defined by Australia Post. Also known as Delivery Point Identifier. type: string thoroughfareNumber1: description: Thoroughfare number for a property (first number in a property ranged address). type: integer x-cds-type: PositiveInteger thoroughfareNumber1Suffix: description: Suffix for the thoroughfare number. Only relevant if _thoroughfareNumber1_ is populated. type: string thoroughfareNumber2: description: Second thoroughfare number (only used if the property has a ranged address e.g., 23-25). type: integer x-cds-type: PositiveInteger thoroughfareNumber2Suffix: description: Suffix for the second thoroughfare number. Only relevant if _thoroughfareNumber2_ is populated. type: string flatUnitType: description: Type of flat or unit for the address. type: string flatUnitNumber: description: Unit number (including suffix, if applicable). type: string floorLevelType: description: Type of floor or level for the address. type: string floorLevelNumber: description: Floor or level number (including alpha characters). type: string lotNumber: description: Allotment number for the address. type: string buildingName1: description: Building/Property name 1. type: string buildingName2: description: Building/Property name 2. type: string streetName: description: The name of the street. type: string streetType: description: The street type. Valid enumeration defined by Australia Post PAF code file. type: string streetSuffix: description: The street type suffix. Valid enumeration defined by Australia Post PAF code file. type: string postalDeliveryType: description: Postal delivery type. (e.g., PO BOX). Valid enumeration defined by Australia Post PAF code file. type: string postalDeliveryNumber: description: Postal delivery number if the address is a postal delivery type. type: integer x-cds-type: PositiveInteger postalDeliveryNumberPrefix: description: Postal delivery number prefix related to the postal delivery number. type: string postalDeliveryNumberSuffix: description: Postal delivery number suffix related to the postal delivery number. type: string localityName: description: Full name of locality. type: string postcode: description: Postcode for the locality. type: string state: description: State in which the address belongs. Valid enumeration defined by Australia Post PAF code file [State Type Abbreviation](https://auspost.com.au/content/dam/auspost_corp/media/documents/australia-post-data-guide.pdf). `NSW`, `QLD`, `VIC`, `NT`, `WA`, `SA`, `TAS`, `ACT`, `AAT`. type: string required: - localityName - postcode - state 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