Home / Specifications / cdsc-wg2-03 - API Interface

API Interface

Below is a rendering of this specification in our github repository: https://github.com/carbon-data-specification/Power-Systems-Data/blob/main/specifications/cdsc-wg2-03.md

CDSC-WG2 - Endpoints

Version: 0.0.2 Status: Draft

1. Foreword

Attention is drawn to the possibility that some of the elements of this document may be the subject of patent rights. No party shall not be held responsible for identifying any or all such patent rights.

Any trade name used in this document is information given for the convenience of users and does not constitute an endorsement.

This draft deliverable was prepared by the LF Energy Standards and Specifications (LFESS) Carbon Data Standards Consortium (CDSC) - Power System Data Working Group.

THESE MATERIALS ARE PROVIDED “AS IS.” The Contributors and Licensees expressly disclaim any warranties (express, implied, or otherwise), including implied warranties of merchantability, non-infringement, fitness for a particular purpose, or title, related to the materials. The entire risk as to implementing or otherwise using the materials is assumed by the implementer and user. IN NO EVENT WILL THE CONTRIBUTORS OR LICENSEES BE LIABLE TO ANY OTHER PARTY FOR LOST PROFITS OR ANY FORM OF INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES OF ANY CHARACTER FROM ANY CAUSES OF ACTION OF ANY KIND WITH RESPECT TO THIS DELIVERABLE OR ITS GOVERNING AGREEMENT, WHETHER BASED ON BREACH OF CONTRACT, TORT (INCLUDING NEGLIGENCE), OR OTHERWISE, AND WHETHER OR NOT THE OTHER MEMBER HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

2. Introduction

This specification was developed as part of the global effort to combat the climate crisis. Specifically, in order to scalably measure carbon emissions of organizations, calculate the impact of deploying and operating clean energy technologies, and catalyze action, companies need an efficient means to discover the details and characteristics of electricity system operators and other similar entities.

This specification offers a set of endpoints that contains the necessary information for carbon data calculations.

3. Normative references

The following documents are referred to in the text in such a way that some or all of their content constitutes requirements of this document. For dated references, only the edition cited applies. For undated references, the latest edition of the referenced document (including any amendments) applies.

4. Terminology and Identification

Within this standard, some entities SHALL only take specific values as outlined below.

  • For fuel, the enum values SHALL be those in column ‘Full code’ defined in EECS Rules Fact Sheet 5: TYPES OF ENERGY INPUTS AND TECHNOLOGIES
  • For technology, the enum values SHALL be those in column ‘Full code’ defined in EECS Rules Fact Sheet 5: TYPES OF ENERGY INPUTS AND TECHNOLOGIES
  • For topology_level, the user SHALL define their own levels and MAY use some of the examples in the APPENDIX. These levels SHALL be a sequential set of positive integers starting at 0 for the top level, with increasing numbers indicating higher geographical resolution.
  • For timestamp, last_updated, startDatetime, and endDatetime, the format of all timestamps SHALL comply with ISO 8601 and include a timezone.

The keywords “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this specification are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here.

All data types in this specification are to be interpreted as described in OpenAPI Specification v3.1.0 when, and only when, they appear in all italics.

All field names in the specification are case-sensitive.

5. Endpoint Categories

The following is a list of the endpoints that will be subsequently defined in this section.

# PSR-Specific Metadata
/power-system-resources/list-topology-levels (GET)
/power-system-resources/list-resources (GET)
/power-system-resource/{id}/describe (GET)
/power-system-resource/{id}/capacity (GET)
/power-system-resource/{id}/transmission-capacity (GET)
/power-system-resource/{id}/topology (GET)

# Timeseries Data
/power-system-resource/{id}/timeseries/emissions (GET)
/power-system-resource/{id}/timeseries/generation (GET)
/power-system-resource/{id}/timeseries/demand (GET)
/power-system-resource/{id}/timeseries/imports (GET)
/power-system-resource/{id}/timeseries/exports (GET)
/power-system-resource/{id}/timeseries/price (GET)
/power-system-resource/{id}/timeseries/curtailment (GET)

5.1 PowerSystemResource,Metadata

The primary set of endpoints that contains reference information for PowerSystemResource (PSR) objects. These objects SHALL contain several metadata fields about these PSRs.

5.1.1 Topology Level (List) power-system-resources/list-topology-levels

Description

The topology levels endpoint SHALL return a list of named PowerSystemResources topology levels and their relation to each other.

Request Object

N/A

Response Object
  • id - string - (REQUIRED) - The name of the topology levels present in the grid region. It SHALL be human-readable.
  • topology_level - int - (REQUIRED) - A number representing the hierarchy of this resource topology in relation to the other resource types. These levels SHALL be a sequential set of positive integers starting at 0 for the top level.

5.1.2 PSR (List) /power-system-resources/list-resources

Description

The summary endpoint SHALL return a list of all PowerSystemResources (PSR) objects.

Request Object
  • topology_level: int - (OPTIONAL) - An optional filter to only return PSR objects with the given topology level.
Response Object
  • id - string - (REQUIRED) - The id of the requested PowerSystemResource.
  • topology_level - string - (REQUIRED) - The id of the topology level for this PSR.
  • name - string - (OPTIONAL) - A descriptive name that provides additional context about the PSR.

This summary endpoint should only include the id, name, and topology_level fields. It MUST NOT contain additional fields.

5.1.3 PSR Topology (List) /power-system-resource/{id}/topology

Description

The topology endpoint SHALL provide a means for understanding how a particular PSR relates to other PSRs by providing all parents and children of that PSR.

Request Object
  • id - string - (REQUIRED) - The id of the requested PowerSystemResource.
  • numLevelsUp - int - (OPTIONAL) - Number of levels above the requested PSR to return in the response. A value of 1 means that it will only return that PSR's direct parent. Default is zero.
  • numLevelsDown - int - (OPTIONAL) - Number of levels below the requested PSR to return in the response. A value of 1 means that it will only return that PSR's direct children. Default is zero.
Response Object
  • id - string - (REQUIRED) - The id of the requested PowerSystemResource.
  • topology - Object
    • parent - Object - (OPTIONAL)
      • id - string The id of the PowerSystemResource that is one level higher in the topology.
      • parent - Object - (OPTIONAL)
        • ...
    • connectedSiblings - array - (OPTIONAL)
      • id - string - The id of the PowerSystemResource that has some transmission-based connection.
      • connectedSiblings - array - (OPTIONAL)
        • id - string
    • children - array - (OPTIONAL)
      • id - string -The id of the PowerSystemResource that is one level lower in the topology.
      • connectedSiblings - array - (OPTIONAL)
      • children - array - (OPTIONAL)

5.1.4 PSR Describe /power-system-resource/{id}/describe

Description

The described endpoint SHALL provide descriptive information, such as geography and other metadata, for a given PowerSystemResource.

Request Object
  • id - string - (REQUIRED) - The id of the requested PowerSystemResource.
Response Object
  • id - string - (REQUIRED) - TThe id of the requested PowerSystemResource.
  • describe
    • asset_info - array - (OPTIONAL) - A list of additional information associated with that PSR.
    • location - (OPTIONAL)
  • description - string - (OPTIONAL)
  • geojson - geojson - (OPTIONAL)

5.1.5 PSR Capacity /power-system-resource/{id}/capacity

Description

The capacity endpoint SHALL provide capacity information by fuel type and technology for a given PowerSystemResource.

Request Object
  • id - string - (REQUIRED) - The id of the requested PowerSystemResource.
  • timestamp - ISO8601 Datetime - (OPTIONAL) A timestamp for which the capacity is to be returned.
Response Object
  • id - string - (REQUIRED) - The id of the requested PowerSystemResource.
  • unit - string - (REQUIRED) - SHALL be one of: [MW, kW, W]
  • capacity - array
    • technology - string - (OPTIONAL) - id of the technology for generating this fuel.
    • fuel - string - (REQUIRED) - id of the fuel type used for generation.
    • value - float - A value of the capacity of generation at this PSR using the given technology and fuel.
    • last_updated - ISO8601 Datetime- (REQUIRED) - The date and time when value was most recently updated.

5.1.6 PSR Transmission Capacity /power-system-resource/{id}/transmission-capacity

Description

The transmission capacity endpoint SHALL provide transmission line capacity information for understanding how a particular PSR relates to others PSRs.

Request Object
  • id - string - (REQUIRED) - The id of the requested PowerSystemResource.
  • timestamp - ISO8601 Datetime - (OPTIONAL) A date and time for which the transmission capacity is to be returned.
Response Object
  • id - string - (REQUIRED) - The id of the PowerSystemResource associated with this location.
  • unit - string - (REQUIRED) - SHALL be one of: [MW, kW, W]
  • transmissionCapacity - array
    • connectedPSR - Object
      • id - string The id of the requested PowerSystemResource connected to the requested one.
    • value - float - A value of the total amount of transmission capacity between the two PSRs.
    • last_updated - timestamp - (REQUIRED) - The date and time when value was most recently updated.

5.2 PowerSystemResource Timeseries Data

The primary set of endpoints references PowerSystemResource (PSR) time-dependent objects. These objects contain time-series information such as generation or demand along with several metadata fields.

5.2.1 PSR Emissions /power-system-resource/{id}/emissions

Description

The emissions endpoint object SHALL return a time-series of values representing the GHG emissions emitted at a PSR, as well as a breakdown of emissions by fuel type and technology.

Request Object
  • id - string - (REQUIRED) - The id of the requested PowerSystemResource.
  • startDatetime - ISO8601 timestamp - (REQUIRED) A timestamp indicating that the response SHALL return data where the earliest entry's startDatetime occurs AT or AFTER the startDatetime specified in the request.
  • endDatetime - ISO8601 timestamp - (REQUIRED) A timestamp indicating that the response SHALL return data where the latest earliest entry's endDatetime occurs AT or BEFORE the endDatetime specified in the request.
Response Object
  • id - string - (REQUIRED) - The id of the PowerSystemResource associated with these emissions.
  • unit - string - (REQUIRED) - SHALL be: [Tonnes CO2e]
  • emissions - array
    • startDatetime - ISO8601 timestamp - (REQUIRED) - The timestamp MUST be timezone aware.
    • endDatetime - ISO8601 timestamp - (REQUIRED) - The timestamp MUST be timezone aware.
    • value - float - (REQUIRED) - A value of the amount of emissions that occurred at this PSR during the period indicated. A positive number indicates emissions caused.
    • valueByFuelSource - array - (REQUIRED) - Lists of fuel types, technologies, and the amount of emissions that come from that fuel type. The unit for these values MUST be the same as that of the unit field.
      • technology - string - (OPTIONAL) - id of the technology that released the emissions from this fuel.
      • fuel - string - (REQUIRED) - id of the fuel type used for generation.
      • value - float - (REQUIRED) - The amount of emissions that took place at this PSR using the given technology and fuel.

5.2.2 PSR Generation /power-system-resource/{id}/generation

Description

The generation endpoint SHALL return a timeseries of values representing electricity that was generated at a PSR, as well as a breakdown of that electricity generation by fuel type and technology.

Request Object
  • id - string - (REQUIRED) - The id of the requested PowerSystemResource.
  • startDatetime - ISO8601 timestamp - (REQUIRED) A timestamp indicating the period that the response SHALL return data for where the earliest entry's startDatetime occurs AT or AFTER the startDatetime specified in the request.
  • endDatetime - ISO8601 timestamp - (REQUIRED) A timestamp indicating the period that the response SHALL return data for where the latest entry's endDatetime occurs AT or BEFORE the endDatetime specified in the request.
Response Object
  • id - string - (REQUIRED) - The id of the PowerSystemResource associated with this generation.
  • unit - string - (REQUIRED) - SHALL be one of: [MWh, kWh, Wh]
  • generation - array
    • startDatetime - ISO8601 timestamp - (REQUIRED) - The timestamp SHALL be timezone aware.
    • endDatetime - ISO8601 timestamp - (REQUIRED) - The timestamp SHALL be timezone aware.
    • value - float - (REQUIRED) - The amount of electricity generation that took place at this PSR.
    • valueByFuelSource - array - (REQUIRED) - Lists of fuel types, technologies, and the amount of generation provided by those fuel types. The unit for these values MUST be the same as that of the unit field.
      • technology - string - (OPTIONAL) - id of the technology that generated electricity from the fuel.
      • fuel - string - (REQUIRED) - id of the fuel type that generated the electricity.
      • value - float - (REQUIRED) A value of the amount of generation that occurred at this PSR using the given technology and fuel that occurred between the startDatetime and endDatetime. A positive number indicates generation, while a negative number indicates consumption.

5.2.3 PSR Demand /power-system-resource/{id}/demand

Description

The demand endpoint SHALL return a time-series of values representing electricity demand at a particular PSR.

Request Object
  • id - string - (REQUIRED) - The id of the requested PowerSystemResource.
  • startDatetime - ISO8601 timestamp - (REQUIRED) A timestamp indicating that the response should return data where the earliest entry's startDatetime occurs AT or AFTER the startDatetime specified in the request.
  • endDatetime - ISO8601 timestamp - (REQUIRED) A timestamp indicating that the response should return data where the latest entry's endDatetime occurs AT or BEFORE the endDatetime specified in the request.
Response Object
  • id - string - (REQUIRED) - The id of the PowerSystemResource associated with this demand.
  • unit - string - (REQUIRED) - SHALL be one of: [MWh, kWh, Wh]
  • demand - array
    • startDatetime - ISO8601 timestamp - (REQUIRED) - The timestamp MUST be timezone aware.
    • endDatetime - ISO8601 timestamp - (REQUIRED) - The timestamp MUST be timezone aware.
    • value - float - (REQUIRED) - The demand at this PSR. A positive number indicates consumption. A negative number indicates generation, for example, from behind the meter generating resources not controlled by the grid operator.

5.2.4 PSR Imports /power-system-resource/{id}/imports

Description

The import endpoint SHALL return a timeseries of values representing electricity that was imported to a particular PSR.

Request Object
  • id - string - (REQUIRED) - The id of the requested PowerSystemResource.
  • startDatetime - ISO8601 timestamp - (REQUIRED) A timestamp indicating that the response should return data where the earliest entry's startDatetime occurs AT or AFTER the startDatetime specified in the request.
  • endDatetime - ISO8601 timestamp - (REQUIRED) A timestamp indicating that the response should return data where the latest entry's endDatetime occurs AT or BEFORE the endDatetime specified in the request.
Response Object
  • id - string - (REQUIRED) - The id of the PowerSystemResource associated with this import.
  • unit - string - (REQUIRED) - SHALL be one of: [MWh, kWh, Wh]
  • imports - array
    • startDatetime - ISO8601 timestamp - (REQUIRED) - The timestamp SHALL be timezone aware.
    • endDatetime - ISO8601 timestamp - (REQUIRED) - The timestamp SHALL be timezone aware.
    • value - float - (REQUIRED) - A value of the amount of electricity imported by this PSR. The value MUST be 0 or a positive value.
    • valueByConnectedPSR - array - (REQUIRED) - Key-value pairs of the connected PSR that this PSR is importing energy from and the amount of electricity that comes from that PSR. The unit for these values MUST be the same as that of the unit field.
      • connectedPSR - string
      • value - positive float - A value of the amount of electricity imported from the connectedPSR. The value MUST be 0 or a positive value (exports should be provided in the other endpoint).

5.2.5 PSR Exports /power-system-resource/{id}/exports

Description

An export object SHALL return a timeseries of values representing electricity that was exported to a PSR.

Request Object
  • id - string - (REQUIRED) - The id of the requested PowerSystemResource.
  • startDatetime - ISO8601 timestamp - (REQUIRED) A timestamp indicating that the response should return data where the earliest entry's startDatetime occurs AT or AFTER the startDatetime specified in the request.
  • endDatetime - ISO8601 timestamp - (REQUIRED) A timestamp indicating that the response should return data where the latest entry's endDatetime occurs AT or BEFORE the endDatetime specified in the request.
Response Object
  • id - string - (REQUIRED) - The id of the PowerSystemResource associated with this export.
  • unit - string - (REQUIRED) - For electricity, should be one of: [MWh, kWh, Wh]
  • exports - array
    • startDatetime - ISO8601 timestamp - (REQUIRED) - The timestamp MUST be timezone aware.
    • endDatetime - ISO8601 timestamp - (REQUIRED) - The timestamp MUST be timezone aware.
    • value - positive float - (REQUIRED) - A value of the amount of electricity exported by this PSR. The value MUST be 0 or a positive value (imports should be provided in the other endpoint).
      • valueByConnectedPSR - array - (REQUIRED) - Key-value pairs of the connected PSR that this PSR is exporting electricity to and the amount of electricity that comes from that PSR. The unit for these values MUST be the same as that of the unit field.
      • connectedPSR - (REQUIRED) - string
      • value - positive float - (REQUIRED) - A value of the amount of electricity exported to the connectedPSR. The value MUST be 0 or a positive value (exports should be provided in the other endpoint).

5.2.6 PSR Prices /power-system-resource/{id}/price

Description

The price endpoint SHALL return a timeseries of values representing the price of electricity at a particular PSR.

Request Object
  • id - string - (REQUIRED) - The id of the requested PowerSystemResource.
  • startDatetime - ISO8601 timestamp - (REQUIRED) A timestamp indicating that the response should return data where the earliest entry's startDatetime occurs AT or AFTER the startDatetime specified in the request.
  • endDatetime - ISO8601 timestamp - (REQUIRED) A timestamp indicating that the response should return data where the latest entry's endDatetime occurs AT or BEFORE the endDatetime specified in the request.
  • price_type - string - The type of price we are returning.
Response Object
  • id - string - (REQUIRED) - The id of the PowerSystemResource associated with this price.
  • price_type - string - The type of price we are returning.
  • price - array
    • startDatetime - ISO8601 timestamp - (REQUIRED) - The timestamp SHALL be timezone aware.
    • endDatetime - ISO8601 timestamp - (REQUIRED) - The timestamp SHALL be timezone aware.
    • value - float - (REQUIRED) - A value of the price of electricity took place at this PSR.

5.2.7 PSR Curtailment /power-system-resource/{id}/curtailment

Description

The curtailment endpoint SHALL return a timeseries of values representing renewable energy that was curtailed at a particular PSR, as well as a breakdown of that curtailed electricity by fuel type.

Request Object
  • id - string - (REQUIRED) - The id of the requested PowerSystemResource.
  • startDatetime - ISO8601 timestamp - (REQUIRED) A timestamp indicating that the response should return data where the earliest entry's startDatetime occurs AT or AFTER the startDatetime specified in the request.
  • endDatetime - ISO8601 timestamp - (REQUIRED) A timestamp indicating that the response should return data where the latest entry's endDatetime occurs AT or BEFORE the endDatetime specified in the request.
Response Object
  • id - string - (REQUIRED) - The id of the PowerSystemResource associated with this curtailment renewable generation.
  • unit - string - (REQUIRED) - SHALL be one of: [MWh, kWh, Wh]
  • generation - array
    • startDatetime - ISO8601 timestamp - (REQUIRED) - The timestamp MUST be timezone aware.
    • endDatetime - ISO8601 timestamp - (REQUIRED) - The timestamp MUST be timezone aware.
    • value - float - (REQUIRED) - A value of the amount of curtailment that took place at this PSR. A positive number indicates curtailment.
    • valueByFuelSource - array - (REQUIRED) - Lists of fuel types, technologies, and the amount of curtailment that occurred for that fuel type. The unit for these values SHALL be the same as that of the unit field.
      • technology - string - (OPTIONAL) - id of the technology that was curtailed.
      • fuel - string - (REQUIRED) - id of the fuel source that was curtailed.
      • value - float - (REQUIRED) - A value of the amount of curtailment that took place at this PSR using the given technology and fuel.

APPENDIX

List of acronyms

AIB Association of Issuing Bodies

CIM Common Information Model

LFC Load frequency control

PSR Power system resource

US United States of America

Examples of Topology Levels

The following table shows an example list of topology levels for US and European Grids:

Level US Grid European Grid CIM
0 Interconnection Synchronous area GeographicalRegion
1 Balancing Authority Area LFC block/LFC area GeographicalRegion, SubGeographicalRegion
2 Zone Bidding zone SubGeographicalRegion
3 Transmission Node/Substation Control area Substation
4 Generating Plant Scheduling Area/Sub scheduling area Feeder, GeneratingUnit
5 Meter (Generator or Load) Metering Grid Area, MeteringPoint GeneratingUnit

This table can be used as a starting point for naming different levels in a given system.

Other Drafts

  • No drafts exist yet.