Skip to content

Docs for meta exports endpoint - move capacities to the annual exports section #337

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
louispt1 wants to merge 1 commit into
base: master
Choose a base branch
from
+42 −4
Open

Docs for meta exports endpoint - move capacities to the annual exports section #337

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 42 additions & 4 deletions docs/api/exports.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,10 @@ Endpoints that can be used to retrieve annual data are based on the following da
* `costs_parameters` - Returns a CSV file containing the cost parameters of nodes belonging to costs groups.
* `direct_emissions_present` - Returns a CSV file containing the direct emissions by node in the present scenario year.
* `direct_emissions_future` - Returns a CSV file containing the direct emissions by node in the future scenario year.
* `electricity_capacities` - Returns a CSV file with the installed and peak capacity per participant in the electricity merit order.
* `district_heating_capacities` - Returns a CSV file with the installed and peak capacity per participant in the district heating network merit order.
* `hydrogen_capacities` - Returns a CSV file with the installed and peak capacity per hydrogen participant.
* `network_gas_capacities` - Returns a CSV file with the installed and peak capacity per network gas participant.


## Get annual data
Expand All @@ -47,18 +51,14 @@ Primary demand,Electricity,...
Endpoints that can be used to retrieve hourly data are based on the following data keys:

* `electricity_profiles` - Downloads the load on each participant in the electricity merit order.
* `electricity_capacities` - Downloads the installed and peak capacity per electricity participant.
* `electricity_price` - Downloads the hourly price of electricity according to the merit order.
* `district_heating_profiles` - Downloads the load on each participant in the district heating network merit order as a CSV.
* `district_heating_capacities` - Downloads the installed and peak capacity per district heating network participant.
* `agriculture_heat` - Downloads the load on each participant in the agriculture heat merit order as a CSV.
* `household_heat` – Downloads the supply and demand of heat in households, including deficits and surpluses due to buffering and time-shifting.
* `buildings_heat` - Downloads the supply and demand of heat in buildings, including deficits and surpluses due to buffering and time-shifting.
* `hydrogen_profiles` - Downloads the total demand and supply for hydrogen, with additional columns for the storage demand and supply.
* `hydrogen_capacities` - Downloads the installed and peak capacity per hydrogen participant.
* `hydrogen_integral_cost` - Downloads the levelised costs, production costs per MWh and hourly production curve per hydrogen production technology.
* `network_gas_profiles` - Downloads the total demand and supply for network gas, with additional columns for the storage demand and supply.
* `network_gas_capacities` - Downloads the installed and peak capacity per network gas participant.
* `residual_load` - Downloads the residual loads of various carriers.


Expand Down Expand Up @@ -86,3 +86,41 @@ Time,curve_1,curve_2,...
2050-01-01 07:00,0.0,0.0,...
...
```

## Discovering available outputs

Rather than hard-coding the keys listed above, clients can discover the available annual
and hourly outputs at runtime. This lets a new export or curve appear without a client
release. Both endpoints return JSON, require no scenario, and need no authentication.

* `GET /api/v3/curves/metadata` - lists the available hourly outputs under `hourly_outputs`.
Each entry has a `name`, a `type` (e.g. `merit_curve`, `price_curve`, `fever_curve`) and a `description`.
* `GET /api/v3/exports/metadata` - lists the available annual exports under `annual_exports`.
Each entry has a `name` and a `description`.

A name returned under `annual_exports` is downloaded from the annual data endpoint
(`/api/v3/scenarios/{id}/{key}.csv`); a name returned under `hourly_outputs` is downloaded
from the hourly data endpoint (`/api/v3/scenarios/{id}/curves/{key}.csv`).

```http title="Example request"
GET /api/v3/exports/metadata HTTP/2
Host: engine.energytransitionmodel.com
Accept: application/json
```

```json title="Example response"
{
"annual_exports": [
{ "name": "energy_flow", "description": "Energy flows by carrier (future year)" },
{ "name": "electricity_capacities", "description": "Installed/peak capacity per participant in the electricity merit order" }
]
}
```

```json title="Example response (curves/metadata)"
{
"hourly_outputs": [
{ "name": "electricity_profiles", "type": "merit_curve", "description": "Load on each participant in the electricity merit order" }
]
}
```