From c4d631f9d6108be852f5deac8338b5abac0b0365 Mon Sep 17 00:00:00 2001 From: louispt1 Date: Thu, 25 Jun 2026 19:54:22 +0200 Subject: [PATCH] Docs for meta exports endpoint - move capacities to the annual exports section --- docs/api/exports.md | 46 +++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 42 insertions(+), 4 deletions(-) diff --git a/docs/api/exports.md b/docs/api/exports.md index 3a83d260..0d26698b 100644 --- a/docs/api/exports.md +++ b/docs/api/exports.md @@ -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 @@ -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. @@ -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" } + ] +} +```