From 9acee9996024f279bdbc80c961cefcc3ee52c441 Mon Sep 17 00:00:00 2001 From: John Mertic Date: Tue, 28 May 2024 13:16:46 -0400 Subject: [PATCH] Start doc of API responses Work in progress; needs aligned to latest spec. --- specifications/example-api-responses.md | 327 ++++++++++++++++++++++++ 1 file changed, 327 insertions(+) create mode 100644 specifications/example-api-responses.md diff --git a/specifications/example-api-responses.md b/specifications/example-api-responses.md new file mode 100644 index 0000000..9e95363 --- /dev/null +++ b/specifications/example-api-responses.md @@ -0,0 +1,327 @@ +# Examples of API Responses + +* TOC +{:toc} + +## 5.1.1 Topology Level + +``` +==Request== +GET /power-system-resource/US-WECC-CISO/topology?numLevels=2 HTTP/1.1 +Host: demoutility.com + +==Response== +HTTP/1.1 200 OK +Content-Type: application/json;charset=UTF-8 +{ + "id": "US-WECC-CISO", + "unit": "MW", + "capacity": [ + { + "fuelSource": { + "technology": "Thermal - Steam engine - Unspecified", + "type": "Fossil - Solid - Hard Coal - Unspecified" + }, + "value": 500, + "startDatetime": "2015-06-01 00:00:00+00", + "endDatetime": "2021-06-01T00:00:00+00" + }, + { + "fuelSource": { + "technology": "Thermal - Steam engine - Unspecified", + "type": "Fossil - Solid - Hard Coal - Unspecified" + }, + "startDatetime": "2010-06-01 00:00:00+00", + "value": 300 + } + ], + "next": null, + "previous": null +} +``` + +## 5.1.2 PSR (List) + +The following is an example of the endpoint that returns a list of +PowerSystemResources. This LIST endpoint should only include the `id`, +`name`, and `topology_level` fields. It MUST NOT contain fields of +undefined size (such as fields that should contain lists or dicts), as +this endpoint is meant to be capable of returning several entries. + +``` +==Request== +GET /power-system-resources HTTP/1.1 +Host: demoutility.com + +==Response== +HTTP/1.1 200 OK +Content-Type: application/json;charset=UTF-8 + +{ + "power_system_resources": [ + { + "id": "US-WECC", + "name": "Western Electricity Coordinating Council", + "topology_level": 0 + }, + { + "id": "US-WECC-CISO", + "name": "California ISO", + "topology_level": 1 + }, + { + "id": "US-WECC-CISO-ABC-HYDRO", + "name": "Hydropower Plant in ABC", + "topology_level": 2 + } + ], + "next": null, + "previous": null +} +``` + +## 5.1.4 PSR Describe + +``` +==Request== +GET /power-system-resource/US-WECC-CISO/describe HTTP/1.1 +Host: demoutility.com + +==Response== +HTTP/1.1 200 OK +Content-Type: application/json;charset=UTF-8 + +{ + "id": "US-WECC-CISO", + "describe": { + "location": { + "geojson": { + "type": "FeatureCollection", + "features": [ + { + "type": "Feature", + "geometry": { + "type": "Polygon", + "coordinates": [ + [[-122.376131, 42.009499], ...] + ] + } + } + ] + } + } + }, + "next": null, + "previous": null +} +``` + +## 5.2.2 PSR Generation + +``` +==Request== +GET /power-system-resource/US-WECC-CISO/generation?startDatetime=2022-06-01&endDatetime=201-06-02 HTTP/1.1 +Host: demoutility.com + +==Response== +HTTP/1.1 200 OK +Content-Type: application/json;charset=UTF-8 + +{ + "id": "US-WECC-CISO", + "unit": "MWh", + "generation": [ + { + "startDatetime": "2021-06-01 00:00:00+00", + "endDatetime": "2021-06-01 01:00:00+00", + "value": 10.5, + "valueByFuelSource": [ + { + "technology": "Thermal - Steam engine - Unspecified", + "type": "Fossil - Solid - Hard Coal - Unspecified", + "value": 5.0 + }, + { + "technology": "Solar - Photovoltaic - Unspecified", + "type": "Renewables - Heating and Cooling - Solar", + "value": 10.5 + }, + // Additional entries for other fuel sources if available + ] + } + // Additional entries for other time periods if available + ], + "next": null, + "previous": null +} +``` + +### 5.2.3 PSR Demand + +``` +==Request== +GET /power-system-resource/US-WECC-CISO/demand?startDatetime=2022-01-01&endDatetime=2023-01-01 HTTP/1.1 +Host: demoutility.com + +==Response== +HTTP/1.1 200 OK +Content-Type: application/json;charset=UTF-8 + +{ + "id": "US-WECC-CISO", + "unit": "MWh", + "demand": [ + { + "startDatetime": "2021-06-01 00:00:00+00", + "endDatetime": "2021-06-01 01:00:00+00", + "value": 10.5 + }, + // Additional entries for other time periods if available + ], + "next": null, + "previous": null +} +``` + +## 5.2.4 PSR Imports + +``` +==Request== +GET /power-system-resource/US-WECC-CISO/imports?startDatetime=2022-01-01&endDatetime=2023-01-01 HTTP/1.1 +Host: demoutility.com + +==Response== +HTTP/1.1 200 OK +Content-Type: application/json;charset=UTF-8 + +{ + "id": "US-WECC-CISO", + "unit": "MWh", + "imports": [ + { + "startDatetime": "2021-06-01 00:00:00+00", + "endDatetime": "2021-06-01 01:00:00+00", + "value": 10.5, + "importByConnectedPSR": [ + { + "connectedPSR": "US-WECC-LADWP", + "value": 5.5 + }, + { + "connectedPSR": "US-WECC-BANC", + "value": 5 + }, + // Additional entries for other connected PSRs if available + ] + }, + // Additional entries for other time periods if available + ], + "next": null, + "previous": null +} +``` + +## 5.2.5 PSR Exports + +``` +==Request== +GET /power-system-resource/US-WECC-CISO/exports?startDatetime=2022-01-01&endDatetime=2023-01-01 HTTP/1.1 +Host: demoutility.com + +==Response== +HTTP/1.1 200 OK +Content-Type: application/json;charset=UTF-8 + +{ + "id": "US-WECC-CISO", + "unit": "MWh", + "exports": [ + { + "startDatetime": "2021-06-01 00:00:00+00", + "endDatetime": "2021-06-01 01:00:00+00", + "value": 10.5, + "exportByConnectedPSR": [ + { + "connectedPSR": "US-WECC-LADWP", + "value": 5.5 + }, + { + "connectedPSR": "US-WECC-BANC", + "value": 5.0 + }, + // Additional entries for other connected PSRs if available + ] + }, + // Additional entries for other time periods if available + ], + "next": null, + "previous": null +} +``` + +## 5.2.6 PSR Prices + +``` +==Request== +GET /power-system-resource/US-WECC-CISO/price?startDatetime=2022-01-01&endDatetime=2023-01-01 HTTP/1.1 +Host: demoutility.com + +==Response== +HTTP/1.1 200 OK +Content-Type: application/json;charset=UTF-8 + +{ + "id": "US-WECC-CISO", + "unit": "USD", + "price": [ + { + "startDatetime": "2021-06-01 00:00:00+00", + "endDatetime": "2021-06-01 01:00:00+00", + "value": 10.5 + }, + // Additional entries for other time periods if available + ], + "next": null, + "previous": null +} +``` + +## 5.2.7 PSR Curtailment + +``` +==Request== +GET /power-system-resource/US-WECC-CISO/curtailment?startDatetime=2022-06-01&endDatetime=201-06-02 HTTP/1.1 +Host: demoutility.com + +==Response== +HTTP/1.1 200 OK +Content-Type: application/json;charset=UTF-8 + +{ + "id": "US-WECC-CISO", + "unit": "MWh", + "curtailment": [ + { + "startDatetime": "2021-06-01 00:00:00+00", + "endDatetime": "2021-06-01 01:00:00+00", + "value": 10.5, + "valueByFuelSource": [ + { + "technology": "Thermal - Steam engine - Unspecified", + "type": "Fossil - Solid - Hard Coal - Unspecified", + "value": 5.0 + }, + { + "technology": "Solar - Photovoltaic - Unspecified", + "type": "Renewables - Heating and Cooling - Solar", + "value": 10.5 + }, + // Additional entries for other fuel sources if available + ] + } + // Additional entries for other time periods if available + ], + "next": null, + "previous": null +} +```