{ "openapi": "3.0.1", "info": { "title": "Montel EQ Time series API", "description": "This is the documentation of the public Montel EQ Time Series API.\n\n## API stability\n\nThe Montel EQ Time Series API expands as more features and types of data becomes available.\nExpect changes such as:\n\n* New API endpoints for new data types and operations\n* New parameters for existing API endpoints\n* Minor changes in response formats over time\n\nThere may exist additional API endpoints not covered by this document. Do not use those endpoints,\nas they may be modified or removed without notice. **We do not offer support on undocumented API\nendpoints.**\n\n## Python client\n\nMontel EQ has created a Python client for this API. See documentation\nat [https://energyquantified-python.readthedocs.io/](https://energyquantified-python.readthedocs.io/).\n\n## Authentication\n\nAny use of the API requires the user to be authenticated with an **API key**.\n\n### Get your API key\n\nIf you already have an account on Montel EQ, find your API key under **Settings** when\nsigned in to the [web application](https://app.energyquantified.com). If you do not have an\naccount, you may sign up on [Montel EQ's Home Page](https://www.energyquantified.com).\n\n### How to specify the API key\n\n**Recommended method:** Add the **API key** in an **HTTP header** called `X-API-Key` for all\nrequests. Example:\n\n```\nX-API-Key: aaaaaa-bbbbbb-cccccc-ddddddd\n```\n\n**Alternative method:** (not recommended) If you are unable to set the API key in an HTTP header,\nyou can also specify it as a query parameter (also known as GET parameter) called `api-key`.\nThis may cause your API key to be exposed in technical requests logs, so it is not recommended.\nExample:\n\n```\n/api/instances//?api-key=aaaaaa-bbbbbb-cccccc-ddddddd\n```\n\n\n\n## Subscriptions\n\nYou can get details of your active subscriptions under\nthe [specified endpoint](#operations-User-get_user_). In addition, each curve object contains a\nfield called `subscriptions` which contains information about the subscription that gives you access\nto the curve (see more details at the [curve object](#model-Curve)).\n\n### Trial users\n\nMontel EQ limits history to 30 days for non-paying users. We may open up a time-limited\ntrial with 365 days history. For time series or market data requests, the **begin** and **end**\nparameters are being limited. For instances/forecast requests, the **issued** parameter (issue date)\nis limited.\n\n### Subscribers\n\nThere are no limitations for paying users, but when your subscription expires/terminates, you will\nlose access to the data.\n\n## Rate-limits\n\nThere are no rate limits implemented at this time. Therefore, we ask our users kindly to not spawn\nthreads and processes to send requests in parallel.\n\nThere may be rate limits added in the future.\n\n## Parameter types\n\n### Booleans\n\nAllowed values: `true` or `false`.\n\n### Numbers\n\nNumbers with base 10.\n\n### Strings\n\nAs strings may contain characters not allowed in URLs or query arguments, remember to `urlencode`\nthem. Most libraries do this automatically. Read more\non [Percent-encoding (Wikipedia)](https://en.wikipedia.org/wiki/Percent-encoding).\n\n### Curve names\n\nCurve names identify time series data. As curve names are strings and part of the URL, remember\nto `urlencode` them just like you would do with any string.\n\n### Date-times\n\nDate-times must be specified on any of the following formats:\n\n1. `YYYY-MM-DD`: Local date\n2. `YYYY-MM-DD HH:mm`: Local date-time with minute-precision\n3. `YYYY-MM-DD HH:mm:ss`: Local date-time with second-precision\n4. `YYYY-MM-DD HH:mm:ss.SSS`: Local date-time with millisecond-precision\n5. `YYYY-MM-DD HH:mm±hh:mm`: Date-time with minute-precision and timezone offset in hours/minutes\n6. `YYYY-MM-DD HH:mm:ss±hh:mm`: Date-time with second-precision and timezone offset in hours/minutes\n7. `YYYY-MM-DD HH:mm:ss.SSS±hh:mm`: Date-time with millisecond-precision and timezone offset in\n hours/minutes\n\nFor the first four formats, the date-times are parsed in the Curve's timezone (see `Curve` model).\n\nFor the remaining three formats, the date-times are parsed in the given timezone offset, then\nconverted to the curves timezone (at the same instant). Instead of specifying the timezone\noffset `±00:00`, you can simply write `Z` when the timezone is `UTC`.\n\n**Examples:\n** `2018-05-17`, `2018-05-17 13:35`, `2018-05-17 23:59:59.999`, `2018-05-17 23:59:59.999+02:00`,\n`1999-12-31 23:59:59.999Z`\n\n### Dates\n\nSpecify dates in the following format:\n\n1. `YYYY-MM-DD`: Local date\n\n### Time-of-day\n\nWhen specifying the time of the day, use any of the following formats:\n\n1. `HH:mm`: Local time with minute-precision\n2. `HH:mm:ss`: Local time with second-precision\n3. `HH:mm:ss.SSS`: Local time with millisecond-precision\n\n### Multiple parameters\n\nWhen specifying multiple parameters as query arguments, repeat the parameter as many times as\nrequired.\n\n**Example:** Filtering on **two tags** called **foo** and **bar**: `?tags=foo&tags=bar`\n\n## Response type\n\nThe API serves responses in `application/json` format primarily.\n\nHowever, because spreadsheet programs are quite popular in the energy sector, we also have the\noption to send **TSV (Tab-Separated-Values)** and **CSV (Comma-Separated-Values)** responses for the\nmost commonly used API endpoints.\n\nAPI endpoints supporting **TSV** and **CSV** responses can be identified by the possibility to\nselect the respective content types: `text/tab-separated-values` for TSV and `text/csv` for CSV as\nthe response content type in the below documentation. These endpoints take optional arguments to\nconfigure the format.\n\nFor TSV responses, the endpoints accept an optional argument `decimal-separator`, which allows you\nto specify the preferred decimal separator for your language settings. It can be set to\neither `COMMA` or `PERIOD`, with the default value being `PERIOD`.\n\nFor CSV responses, the endpoints accept two optional arguments. The first one\nis `decimal-separator`, which serves the same purpose as for TSV responses. The second argument\nis `delimiter`, which determines the delimiter used to separate values in the CSV file. It can be\nset to `COMMA` or `SEMICOLON`, with the default value being `COMMA`. Please note that it is not\nallowed to set `COMMA` for both `decimal-separator` and `delimiter`.\n\nIn order to obtain a TSV response, the `Accept` header should be configured\nas `text/tab-separated-values`. To obtain a CSV response, set the `Accept` header as `text/csv`. If\nit is set as `application/json`, a wildcard, or if no `Accept` header is provided, the response will\nbe in JSON format.\n\n## Terminology\n\n### Curve\n\nA **Curve** describes any time series data. The Curve's name is unique and identifies time series in\nthe API. The `Curve`-model contains all the meta-information which makes up its name, such as\ncategories, areas, unit and more.\n\nAdditionally, a Curve has a **Resolution**. It is made up by a **Frequency** and a **Timezone**.\nTogether, these two fields describe a fixed tick rate (i.e. 15-minute, hourly, daily, etc.) and the\nlocalization/timezone of the data in said Curve.\n\nThe Curve model also has a field called `curve_type`. The `curve_type` defines the kind of data\npresent in this Curve. It is also hints at which API endpoints to use for the Curve. When [querying\ncurves in the API](#operations-Metadata-get_metadata_curves_), you can filter on `curve_type` to get\nthe curves you need.\n\nThe different `curve_types` are:\n\n* `TIMESERIES`: Plain time series with (date, value) tuples. Use `/api/timeseries/*`.\n* `SCENARIO_TIMESERIES`: Plain time series with multiple values per date: (date, (v1, v2, v3, ..., v\n *n*)). Use `/api/timeseries/*`.\n* `INSTANCE`: A curve which consists of many time series, each identified by an `Instance`. Use\n the `/api/instances/*` endpoints to get data from these curves. For certain types of data, i.e.\n ensemble forecasts instance-based curves stores scenarios. In order to load these, use\n the `/api/ensembles/*` endpoints (which are identical the `/api/instances/*` endpoints, but loads\n the scenarios as well).\n* `PERIOD`: Period-based series consist of a list of periods (from – to) with a corresponding value.\n The periods do not follow a regular interval, like with time series. Use `/api/periods/*`.\n* `INSTANCE_PERIOD`: Like `PERIOD`, but with instances. Use `/api/period-instances/*`.\n* `OHLC`: Closing prices with open, high, low, close, volume and open interest.\n* `TRADES`: Intraday trades grouped by delivery contract and represented as OHLC series.\n* `PPA`: Power Purchase Agreement (PPA) price data. Use `/api/ppa/*`.\n\n### Instance\n\nCurves with `curve_type` equals `INSTANCE` or `INSTANCE_PERIOD` has data stored in multiple\ninstances. An instance is identified by the combination of two fields, `issued` and `tag`. `issued`\nis a date-time field (with timezone) and `tag` is a plain string in lowercase.\n\nOn the `Curve`-model, there is a field called `instance_issued_timezone`. This field describes the\ntimezone of the `issued`-field. When specifying `issued-at-latest` or `issued-at-earliest` when\nfetching instances, the provided date-time is parsed in the `instance_issued_timezone` timezone\nunless you specify a timezone in the provided date-times.\n\n### Place\n\nSome data, such as production data for a power plant, represents data for a geographical location.\nIn those cases, we use the `Place` model to describe the name, the geolocation and the type of\nthis \"place\". A place could be a power plant unit, a consumer, a city and more.\n\nWhen querying places in the API, each `Place`-object may return a list of all curves associated with\nthat particular place. Example: When you use `/metadata/places/` to query for `area=DE`\nand `fuel=Nuclear`, you get all nuclear power plant units in Germany with their corresponding\ncurves.\n\n### Resolution\n\nMontel EQ's time series data consists of regular time intervals with values. Just like\nproducts in the power markets, they are usually in a fixed frequency. Curves, the identifier of any\ntime series, have a resolution attribute indicating the **frequency** and **timezone** of the dates\nand values in the time series.\n\n### Frequency\n\nFrequencies use the **ISO-8601 Duration format**. Please refer\nto [Duration (Wikipedia)](https://en.wikipedia.org/wiki/ISO_8601#Durations) for an excellent\nexplanation of the format. Supported frequencies:\n\n* `P1Y` – Yearly\n* `P3M` – Quarterly\n* `P1M` – Monthly\n* `P1W` – Weekly\n* `P1D` – Daily\n* `PT1H` – Hourly\n* `PT30M` – 30 minutes\n* `PT15M` – 15 minutes\n* `PT10M` – 10 minutes\n* `PT5M` – 5 minutes\n* `PT1M` - 1 minute\n\nBesides, the following frequency constant is used when data does not follow a regular interval. It\nis an invalid frequency option for operations that involve the **Timeseries** model (i.e.\naggregations).\n\n* `NONE` – No frequency specified (i.e. tick data)\n\n### Timezone\n\nSupported timezones at this moment:\n\n* `UTC` – Coordinated Universal Time\n* `WET` – Western European Time\n* `CET` – Central European Time\n* `EET` – Eastern European Time\n* `Europe/Istanbul` – Turkey Time\n* `Europe/Moscow` – Russian/Moscow Time\n* `Europe/Gas_Day` – *(Non-standard timezone; not in the IANA timezone database)* European Gas Day\n at UTC-0500 (UTC-0400 during Daylight Saving Time). Starts at 06:00 in CE(S)T time. Used for the\n natural gas market in the European Union.\n\nSome endpoints accept a `timezone` parameter. If you set it to one of the values above, the\ndate-times are converted to the given timezone.\n\n### Unit\n\nConvert data to another unit. Supported units at this moment:\n\n* `°C` for temparatures in celsius degrees\n* `Degrees` for angles in degrees\n* `hPa` for pressure in hectopascal\n* `m` for length in meters\n* `m^2` for area in square meters\n* `m^3` for volume in cubic meters\n* `s` for time in seconds\n* `t` for weight in tons\n* `TW`, `GW`, `MW`, `kW`, `W` for power in watt\n* `TWh`, `GWh`, `MWh`, `kWh`, `Wh` for energy in watt-hours\n* `TWh/h`, `GWh/h`, `MWh/h`, `kWh/h`, `Wh/h` for average energy in watt-hours per hour\n* `therm` for heat energy in therms\n* `bbl` for volume in barrels\n* `gCO2eq` and `kgCO2eq` for grams and kilograms of carbon equivalents\n* `%` as percent\n* `EUR`, `USD`, `GBP`, `NOK`, `SEK`, `DKK`, `CHF`, `CZK`, `HUF`, `PLN`, `BGN`, `HRK`, `RUB`, `RON`,\n `TRY`, `pence`\n for currencies\n\n### Filters\n\nUsed for **filtering hours and days** in aggregations. Supported filters:\n\n* `BASE` – All hours\n* `PEAK` – Peak hours (8-20). For future contracts: Peak hours (8-20) during workdays\n* `OFFPEAK` – Offpeak (0-8 and 20-24). For future contracts: Offpeak hours (0-8 and 20-24) during\n workdays and all hours during the weekend\n* `WORKDAYS` – Monday, Tuesday, Wednesday, Thursday, Friday\n* `WEEKENDS` – Saturday, Sunday\n\nFor weekly, monthly, quarterly and yearly resolutions, `PEAK` is defined as `PEAK` hours\nduring `WORKDAYS` (8-20 during workdays). `OFFPEAK` is, for the same resolutions, defined\nas `OFFPEAK` hours during `WORKDAYS` and all hours during `WEEKENDS`.\n\nFor daily resolutions, `PEAK` and `OFFPEAK` do not make a distinction between workdays and weekends.\n\n### Threshold\n\nBy default, an aggregation returns empty values whenever one or more input values are missing. The\nparameter `threshold` defines how many values are allowed to be missing within a frame of the\nconverted frequency. If the number of missing values is less than or equal to the `threshold`,\naggregation is performed on the remaining non-empty values. Otherwise, an empty value is returned.\n\nFor example, you want to convert hourly values to daily values using the mean value. Let's assume\nthat some input values are missing. Instead of getting empty values, you want to get the average if\na maximum of four values are missing within a day. In this case, set the `threshold` to four.\n\n## Trade data\n\nCurves with `curve_type = TRADES` contain trades for a market or commodity. Unlike a regular time\nseries, each trade belongs both to a delivery contract and to a point in the contract's trading\nhistory. Trade data is therefore organized as one OHLC series per delivery contract.\n\n### Trade contracts\n\nA trade contract describes when the traded commodity will be delivered. It is identified by:\n\n* `period`: The delivery period, expressed as an ISO-8601 duration. It specifies the length of the\n delivery interval, for example `PT15M`, `PT30M` or `PT1H`.\n* `delivery`: The beginning of the delivery interval in the curve's timezone.\n\nTogether, these fields identify the delivery interval from `delivery` (inclusive) to\n`delivery + period` (exclusive). Contracts with the same delivery start but different\nperiods are different contracts.\n\nThe delivery period must not be confused with the frequency of the OHLC series. The period describes\ndelivery, while the series frequency describes how the preceding trading activity is divided into\ntime buckets.\n\n### Trade OHLC data\n\nThe trading history for a contract is represented as a time-ordered series of OHLC values. The\n`traded_at` field identifies the beginning of a trading-time bucket; it does not identify the\ncontract's delivery time.\n\nEach OHLC value contains:\n\n* `open`: The first traded price in the bucket.\n* `high`: The highest traded price in the bucket.\n* `low`: The lowest traded price in the bucket.\n* `close`: The last traded price in the bucket.\n* `vwap`: The volume-weighted average price in the bucket.\n* `volume`: The total traded volume in the bucket.\n* `count`: The number of trades represented by the bucket.\n\nThe curve's `unit` and `denominator` describe the price unit, for example `EUR/MWh`.\n\nBy default, up to 36 hours of trading history before delivery are returned. The\n`min-lead-time` and `max-lead-time` parameters select a smaller window using ISO-8601 durations\nbetween `PT0S` and `PT36H`. Lead time is the duration from `traded_at` until the beginning of\ndelivery: the minimum boundary is exclusive and the maximum boundary is inclusive. For example,\n`min-lead-time=PT1H&max-lead-time=PT6H` includes values traded more than one and at most six hours\nbefore delivery.\n\n### Aggregation\n\nA trade curve's resolution specifies the frequency of its source OHLC values. These values can be\ncombined into coarser trading-time buckets. During aggregation:\n\n* `open` is taken from the earliest bucket and `close` from the latest bucket.\n* `high` is the maximum and `low` is the minimum across the buckets.\n* `vwap` is weighted by the volume of the constituent buckets.\n* `volume` and `count` are summed.\n\nAggregation buckets are aligned backwards from the end of the selected trading window. This anchor\nis `delivery - min-lead-time`; with the default `min-lead-time=PT0S`, it is the beginning of the\ndelivery period. \"Backwards\" describes how bucket boundaries are calculated; it does not mean that\nthe resulting series is in reverse chronological order. Starting at the anchor, the requested\nfrequency is repeatedly subtracted to form trading-time buckets:\n\n```text\nanchor - frequency anchor\n |------------------------------------|\n final selected bucket\n\nanchor - 2 * frequency anchor - frequency\n |------------------------------------|\n preceding bucket\n```\n\nFor example, for a contract delivered at 12:45, aggregated to `PT1H`, and using the default\n`min-lead-time=PT0S`, the anchor is 12:45. The buckets are aligned to `:45` rather than to the\nwall-clock hour:\n\n```text\n09:45 10:45 11:45 12:45\n |------------------|------------------|------------------|\n earlier bucket preceding bucket final bucket delivery begins\n```\n\nThe last OHLC value has `traded_at` set to 11:45 and represents trades in `[11:45, 12:45)`: the\nstart is inclusive and the end is exclusive. The preceding values represent `[10:45, 11:45)` and\n`[09:45, 10:45)`. The last bucket is therefore a complete one-hour bucket ending exactly when\ndelivery begins, not a partial `[12:00, 12:45)` wall-clock bucket. The series is still returned in\nchronological order, and each `traded_at` value identifies the beginning of its bucket.\n\nSetting a minimum lead time moves the anchor away from delivery before the buckets are calculated.\nFor the same 12:45 delivery, `frequency=PT1H&min-lead-time=PT15M` makes 12:30 the exclusive end of\nthe selected trading window:\n\n```text\n09:30 10:30 11:30 12:30 12:45\n |------------------|------------------|------------------| |\n earlier bucket preceding bucket final bucket excluded delivery\n 15 minutes begins\n```\n\nThe final OHLC value now has `traded_at` set to 11:30 and represents `[11:30, 12:30)`. A source\nvalue with `traded_at=12:30` has exactly 15 minutes of lead time and is excluded because the minimum\nlead-time boundary is exclusive. Values after 12:30 are also excluded. Because the buckets are\naligned backwards from 12:30 rather than from 12:45, the final bucket still covers a full hour.\n\nAlignment is calculated independently for every contract. At the same `PT1H` frequency and the\ndefault `min-lead-time=PT0S`, a contract delivered at 13:00 has buckets beginning on the hour, while\na contract delivered at 12:45 has buckets beginning at `:45`. A non-zero minimum lead time shifts\neach contract's anchor by that duration as shown above.\n\nTrade data can also be aggregated across all selected trading-time buckets for each delivery\ncontract. Unlike fixed-frequency aggregation, this collapses the selected lead-time window into one\nOHLC value per contract while keeping contracts with different periods or delivery periods separate.\n\n## PPA data\n\nCurves with `curve_type = PPA` contain Power Purchase Agreement (PPA) price data. A PPA data point\nis a price quoted on a given date for a specific PPA **product**.\n\n### PPA product\n\nA PPA product identifies what is being priced. It is described by:\n\n* `technology`: The generation technology. One of `solar`, `wind_onshore`, `wind_offshore`.\n* `contract_structure`: The contract structure. One of `year` (yearly baseload), `month` (monthly\n baseload), `proxy` or `pay_as_produced`.\n* `delivery_begin`: The beginning of the delivery period.\n* `duration`: The duration of the contract, in years. One of `3`, `5`, `10`, `15`.\n\nTogether, these four fields identify a unique PPA product. The `date` field on the `PPA` object\nitself is the quote date: the date the `price` was quoted, not a delivery date.\n\n### PPA price\n\nEach `PPA` object contains a `price` for its product, quoted in the curve's `unit` and\n`denominator`, for example `EUR/MWh`. Use the `unit` parameter to convert the price into another\ncurrency or unit.\n\n### Filtering\n\nWhen loading PPA data, you can filter on `technology`, `contract-structure`, `delivery-begin`\nand/or `duration`. `technology`, `contract-structure` and `duration` accept multiple values (see\nMultiple parameters above): a PPA matches the filter if it has any of the given values. All given\nfilters must match (logical AND across filters, logical OR within repeated values of the same\nfilter).\n\n## Push Feed API\n\nThe Push Feed serves as a Web Socket endpoint designed to receive events related to updates on curve\ndata. Check out [our live demo](https://app.eqenergy.com/data/push-feed).\n\nEach event provides information regarding the specific curve and, optionally, the instance on which\nthe update was performed. Additionally, it includes details such as the `event_type`, the `begin`\nand `end` date and time of the changes, and the number of values that have been modified.\n\n### Initialising HTTP request\n\nFor more detailed information regarding the initialising request and its available options, please\nrefer to the documentation on [request initialisation](#operations-Push_Feed-get_events_).\n\n### Client messages\n\nTo establish effective communication with the client, it is important to include a string-type field\nnamed `type` in the message. This field serves to specify the purpose of the message accurately.\nFurthermore, for convenient tracking of responses, there is an optional `request_id` field that can\nbe included\nin [UUID Version 4 (MDN Web Docs)](https://developer.mozilla.org/en-US/docs/Glossary/UUID) format.\nThe following actions are supported:\n\n#### Get filters for curves\n\nSend this message to get the currently active filters. Use `curves.filters` as `type`.\nSee [`PFRequestCurvesFilters`](#model-PFRequestCurvesFilters) for the full definition.\nSee [`PFServerResponseCurvesFilter`](#model-PFServerResponseCurvesFilter) for the full definition of\nthe server's response. Here is an example:\n\n```json\n{\n \"type\": \"curves.filters\",\n \"request_id\": \"123e4567-e89b-12d3-a456-426614174000\"\n}\n```\n\n#### Subscribe to curves\n\nSend this message to subscribe to curves by providing a list of filters. You can combine any set of\nfilters, also different types of filters as explained in the next paragraph. If an event matches any\nof your filter configurations, it will be sent to you. Note that you must have a subscription to an\nevent's data to receive that event. Only events matching your subscription and at least one of your\nfilters will be forwarded to you. If you provide an empty list of filters, you'll receive all\nevents.\n\nYou can choose between two types of filters and combine them freely in the list of filters. Each of\nthem have their separate set of properties besides shared properties.\nSee [`PFRequestCurvesSubscribe`](#model-PFRequestCurvesSubscribe) for the full\ndefinition of shared properties.\n\nUse `curves.subscribe` as `type` and the properties of the filter. The server will send back a\nresponse with the new filter and the `last_id` if it has provided by your request. Here's an example\nresponse:\n\n```json\n{\n \"type\": \"curves.subscribe\",\n \"request_id\": \"123e4567-e89b-12d3-a456-426614174000\",\n \"status\": \"OK\",\n \"data\": {\n \"last_id\": \"1504224000000-0\",\n \"filters\": [\n {\n \"event_types\": [\n \"CURVE_UPDATE\"\n ],\n \"begin\": \"2023-01-01\",\n \"end\": \"2024-01-01\",\n \"curve_names\": [\n \"DE Wind Power Production MWh/h 15min Normal\",\n \"DE Solar Photovoltaic Production MWh/h 15min Normal\",\n \"DE Consumption MWh/h 15min Normal\"\n ]\n }\n ]\n }\n}\n```\n\nTo retrieve events between a specific event and your successful subscription, you can utilize\nthe `last_id` parameter. This feature proves valuable in scenarios where you've encountered downtime\nand want to ensure you capture all missed events during that period. To implement this, simply\nobtain the ID of the last event you received and include it in your curves.subscribe request. An\nexemplary ID follows this format: `1504224000000-0`. Notably, the first part of the ID represents\nthe event's creation timestamp in milliseconds, while the second part serves as a counter in case\ntwo events share the same timestamp. If needed, you can set an artificial `last_id` with a future\ntimestamp to commence listening from that point onward in time. Please be aware that providing an\ninvalid ID will result in an error message. For additional details regarding messages and errors,\nrefer to the information provided below.\n\n##### Limits\n\nAt present, our system stores the ~10.000 most recent events in its memory, which ideally spans the\nlast ten to 15 minutes. Any events older than this time frame are automatically discarded. Please\nkeep in mind that the number of past events available to you may vary depending on your\nsubscriptions. Consequently, the quantity of historical events accessible to you might be less than\n~10.000. The limit we've mentioned only pertains to the events provided through the push feed.\n\nYou can subscribe with at most 20 filters at a time.\n\n##### Common filter parameters\n\nBoth filter configurations have a set of common parameters, which are as follows:\n\n| Parameter | Description |\n|----------------|-----------------------------------------------------------|\n| `event_types` | Specify the types of events you wish to receive |\n| `begin` | Define the starting point for the event's affected values |\n| `end` | Define the ending point for the event's affected values |\n| `tags` | Filter to include instances with given tags. |\n| `exclude_tags` | Filter to exclude instances with given tags. |\n\n**Note:** The filter parameters `tags` and/or `exclude_tags` only affect events with an instance.\nEvents without an instance will ignore these parameters.\n\n##### 1. Curve name filter\n\nYou can filter by providing a list of curve names. If the curve of an event matches one of the given\ncurve names (and the common parameters if set), it will be sent to you.\nSee [`PFCurveNameFilter`](#model-PFCurveNameFilter) for the detailed definition. Here is an example:\n\n```json\n{\n \"type\": \"curves.subscribe\",\n \"request_id\": \"123e4567-e89b-12d3-a456-426614174000\",\n \"filters\": [\n {\n \"event_types\": [\n \"CURVE_UPDATE\"\n ],\n \"begin\": \"2023-01-01\",\n \"end\": \"2024-01-01\",\n \"curve_names\": [\n \"DE Wind Power Production MWh/h 15min Normal\",\n \"DE Solar Photovoltaic Production MWh/h 15min Normal\",\n \"DE Consumption MWh/h 15min Normal\"\n ]\n }\n ]\n}\n```\n\n##### 2. Curve attribute filter\n\nThis type of filter takes attributes that match curve parameters. An event must match at least one\nentry for each provided attribute. In the example below an event must fulfill the following\nattributes:\n\n- event type must be `CURVE_UPDATE`\n- **and** event time frame must overlap the time between `2023-01-01` and `2024-01-01`\n- **and** area must be `DE` **or** `FR`\n- **and** data type must be `Actual` **or** `Forecast`\n- **and** commodity must be `Power`\n- **and** the exact categories must be `Wind Power Production` **or**\n `Solar Photovoltaic Production`\n\nThe `areas` filter matches both areas of curves with two areas (e.g., exchange curves). Besides the\nattributes in the example, you can also filter on `categories` (any of the given categories),\n`frequencies`, `units`, `curve_types` and `sources`, like in the curve search.\n\nSee [`PFCurveAttributeFilter`](#model-PFCurveAttributeFilter) for the detailed definition. Here's\nan example with a few of the filter attributes:\n\n```json\n{\n \"type\": \"curves.subscribe\",\n \"request_id\": \"123e4567-e89b-12d3-a456-426614174000\",\n \"filters\": [\n {\n \"event_types\": [\n \"CURVE_UPDATE\"\n ],\n \"begin\": \"2023-01-01\",\n \"end\": \"2024-01-01\",\n \"areas\": [\n \"DE\",\n \"FR\"\n ],\n \"data_types\": [\n \"Actual\",\n \"Forecast\"\n ],\n \"commodities\": [\n \"Power\"\n ],\n \"exact_categories\": [\n \"Wind Power Production\",\n \"Solar Photovoltaic Production\"\n ]\n }\n ]\n}\n```\n\n### Server messages\n\nThe server sends various types of messages, each serving a different purpose. The JSON message\nincludes a root field called `type`, which is of type string and indicates the specific type of the\nmessage. Read more about the different message formats below:\n\n#### Informational messages\n\nInformational messages provide you with non functional information. They have the value `message`\nas `type`.\n\nSee [`PFServerMessageMessage`](#model-PFServerMessageMessage) for the full type definition. An\nexample you will receive after initialising the connection is the following message:\n\n```json\n{\n \"type\": \"message\",\n \"message\": \"To receive events, you must provide an initial filter. More information can be found here: https://app.energyquantified.com/api/docs/\"\n}\n```\n\n#### Event messages\n\nEvent messages are the curve update events. They have the value `curves.event` as `type` and\ndescribe the change to some curve data.\nSee [`PFServerMessageCurvesEvent`](#model-PFServerMessageCurvesEvent) for the full type definition.\nHere's an example describing some updated values for the German wind power production forecast:\n\n```json\n{\n \"type\": \"curves.event\",\n \"event\": {\n \"id\": \"1693919779423-1\",\n \"event_type\": \"CURVE_UPDATE\",\n \"curve\": {\n \"name\": \"DE Wind Power Production MWh/h 15min Forecast\",\n \"area\": \"DE\",\n \"categories\": [\n \"Wind\",\n \"Power\",\n \"Production\"\n ],\n \"resolution\": {\n \"frequency\": \"PT15M\",\n \"timezone\": \"CET\"\n },\n \"unit\": \"MWh/h\",\n \"data_type\": \"FORECAST\",\n \"curve_type\": \"INSTANCE\",\n \"instance_issued_timezone\": \"UTC\",\n \"access\": {\n \"by\": \"area\",\n \"package\": \"Power\"\n },\n \"subscription\": {\n \"access\": \"PAYING\",\n \"type\": \"package_area\",\n \"label\": \"Power - Germany\",\n \"package\": \"Power\",\n \"area\": \"DE\"\n },\n \"commodity\": \"Power\"\n },\n \"instance\": {\n \"issued\": \"2023-09-05 06:00:00Z\",\n \"tag\": \"ecsr-ens\",\n \"scenarios\": 51,\n \"created\": \"2023-09-05 14:44:02+02:00\",\n \"modified\": \"2023-09-05 15:17:06+02:00\"\n },\n \"begin\": \"2023-09-05 09:00:00+02:00\",\n \"end\": \"2023-09-11 02:00:00+02:00\",\n \"values_changed\": 548\n }\n}\n```\n\n### Server responses\n\nAll responses from the server to a request follow a consistent format and include the following\nfields:\n\n| Field | Description |\n|--------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `type` | This field reflects the same type as the corresponding request (e.g., `curves.subscribe`). |\n| `request_id` | It contains the `request_id` from the original request. If the initial request did not provide a `request_id`, the response will generate a self-contained ID. |\n| `status` | This field indicates either `OK` or `ERROR`, depending on whether the request was successful or not. |\n| `data` | The response data varies for each type of request and is included only when the request succeeds (status `OK`). |\n| `errors` | This field contains a list of error messages and is included only when the request fails (status `ERROR`). |\n\nRefer to [`PFServerResponse`](#model-PFServerResponse) for the full definition.\n\n#### Subscribe response\n\nIn case the subscription to curves has been updated, this message contains the set of the updated\nfilters and optionally the last ID. This responses has the value `curves.subscribe` as `type`.\n\nSee [`PFServerResponseCurvesSubscribe`](#model-PFServerResponseCurvesSubscribe) for the full type\ndefinition. Here's an example of a succeeded request:\n\n```json\n{\n \"type\": \"curves.subscribe\",\n \"request_id\": \"123e4567-e89b-12d3-a456-426614174000\",\n \"status\": \"OK\",\n \"data\": {\n \"last_id\": \"1504224000000-0\",\n \"filters\": [\n {\n \"begin\": \"2023-01-01 00:00Z\",\n \"end\": \"2024-01-01 00:00Z\",\n \"event_types\": [\n \"CURVE_UPDATE\"\n ],\n \"curve_names\": [\n \"DE Solar Photovoltaic Production MWh/h 15min Normal\",\n \"DE Wind Power Production MWh/h 15min Normal\",\n \"DE Consumption MWh/h 15min Normal\"\n ]\n }\n ]\n }\n}\n```\n\n#### Filter response\n\nIn case the currently active set filters are requested, this message contains a set of these\nfilters. This response has the value `curves.filters` as `type`.\n\nSee [`PFServerResponseCurvesFilter`](#model-PFServerResponseCurvesFilter) for the full type\ndefinition. Here's an example of a succeeded request:\n\n```json\n{\n \"type\": \"curves.filters\",\n \"request_id\": \"123e4567-e89b-12d3-a456-426614174000\",\n \"status\": \"OK\",\n \"data\": {\n \"filters\": [\n {\n \"begin\": \"2023-01-01 00:00Z\",\n \"end\": \"2024-01-01 00:00Z\",\n \"event_types\": [\n \"CURVE_UPDATE\"\n ],\n \"curve_names\": [\n \"DE Solar Photovoltaic Production MWh/h 15min Normal\",\n \"DE Wind Power Production MWh/h 15min Normal\",\n \"DE Consumption MWh/h 15min Normal\"\n ]\n }\n ]\n }\n}\n```\n\n#### Error responses\n\nError responses indicate the presence of an error, and they are identified by having `ERROR` as\ntheir `status`. These types of messages include a `errors` list that provides a description of the\nencountered errors. Here's an example:\n\n```json\n{\n \"type\": \"curves.subscribe\",\n \"request_id\": \"123e4567-e89b-12d3-a456-426614174000\",\n \"status\": \"ERROR\",\n \"errors\": [\n \"Invalid pattern in field 'last_id': 'foo'. Expected 'last_id' to be a string of two numbers separated by a dash ('-'), where the first number is exactly 13 digits long and the second number at most 18 digits long (e.g., '1234567890123-0', '1234567890123-5', '1234567890123-77').\"\n ]\n}\n```\n\n## Changelog\n\n#### v0.37\n\n* **Push Feed**\n * Add the filters `frequencies`, `units`, `curve_types` and `sources` to the curve attribute\n filter, matching the filters in the curve search. Units and sources are case-sensitive. Use\n the string `\"null\"` in `sources` to match curves without a source.\n * The `areas` filter now matches on both source and sink areas (e.g., the sink area of exchange\n curves). Previously, it only matched on the source area.\n * `exact_categories` now ignores case and extra whitespace (e.g., `\" wind POWER production \"`\n matches `Wind Power Production`).\n * Increase the maximum number of filters per subscription from 10 to 20.\n * Fix filters returned in `curves.subscribe` and `curves.filters` responses not matching the\n values accepted when subscribing. Some areas, categories and commodities were returned with\n different names (e.g., `IT_NORD` instead of `IT-NORD`), so the returned filters could not be\n used to subscribe again.\n * Other minor bugfixes and performance improvements\n\n#### v0.36\n\n* Add support for **intraday trade data** with `TRADES` curves, delivery contracts and OHLC series\n in JSON, CSV and TSV formats.\n * Add trade endpoints for listing contracts and loading trade OHLC series for multiple\n contracts.\n * `/trades/{curve-name}/contracts/`\n * `/trades/{curve-name}/ohlc/`\n * Add trade contract filtering when loading multiple contracts. Contract intervals are limited\n to\n one week.\n * Add frequency and delivery aggregation for trade OHLC data, with frequency buckets aligned\n backwards from delivery.\n * Add lead-time filtering for trade OHLC data.\n* Add frequency `PT1M`.\n* Add support for **Power Purchase Agreement (PPA) price data** with `PPA` curves, in JSON, CSV and\n TSV formats.\n * Add PPA endpoints for loading PPA price data for a date range and for the latest quote date.\n * `/ppa/{curve-name}/`\n * `/ppa/{curve-name}/latest/`\n * Add filtering on technology, contract structure, delivery start date and duration when loading\n PPA data.\n * Add unit and currency conversion for PPA data.\n\n#### v0.35\n\n* Add `description` field to `Curve` model. This field contains a human-readable description of the\n curve, which may be helpful to understand the content of the curve and its source.\n* Remove deprecated field `Curve.access`. Use `Curve.subscription` instead to get information about\n the subscription that gives you access to the curve.\n\n#### v0.34\n\n* Add support for specifying `threshold` parameter as a percentage in addition to an absolute number\n\n#### v0.33\n\n* Restrict the `begin`-`end` interval of rolling forecasts to maximum one year\n\n#### v0.32\n\n* Add `tags` and `exclude_tags` as filter parameters in the Push Feed API\n\n#### v0.31\n\n* Add `emission_type` parameter to `/carbon/calculate/{area}/` to distinguish between lifecycle and\n operational emissions\n\n#### v0.30\n\n* Loading subsets of forecasts with the `begin` and `end` parameters is now supported in the\n following endpoints:\n * `/instances/{curve-name}/`\n * `/instances/{curve-name}/get/latest/`\n * `/instances/{curve-name}/get/{issued}/`\n * `/instances/{curve-name}/get/{issued}/{tag}/`\n\n#### v0.29\n\n* API endpoints for periods and period instances now support CSV and TSV output formats in addition\n to JSON. This affects the following endpoints:\n * `/periods/{curve}/`\n * `/period-instances/{curve}/`\n * `/period-instances/{curve}/get/{issued}/`\n * `/period-instances/{curve}/get/{issued}/{tag}/`\n * `/period-instances/{curve}/get/latest/`\n * `/period-instances/{curve}/get/relative/`\n\n#### v0.28\n\n* Add `gCO2eq` and `kgCO2eq` as units for carbon emissions\n* Add `mm` as unit for millimeters\n* Add `Green` as commodity\n* Add `gas-storage`, `gas-lng-terminal` and `gas-interconnector` as place types\n\n#### v0.27\n\n* A new API endpoint to calculate carbon emissions `/carbon/calculate/{area}/`\n* Add support for custom consumption data to calculate carbon emissions with the new API endpoint\n `POST /carbon/calculate/`\n\n#### v0.26\n\n* Add support for filtering on commodities through the `q` parameter in `/metadata/curves/`\n* Add member `denominator` in `AbsoluteResult` from `/instances//get/absolute/`\n* Add support for filtering instances by issued time through the `issued-time-of-day` parameter in\n the following endpoints:\n * `/instances/{curve-name}/`\n * `/instances/{curve-name}/get/latest/`\n * `/instances/{curve-name}/list/`\n * `/ensembles/{curve-name}/`\n * `/ensembles/{curve-name}/get/latest/`\n\n#### v0.25\n\n* Enable unit conversion in `/ohlc/` and `/srmc/` endpoints\n* Add members `unit` and `denominator` in `PeriodSeries`\n* Add members `unit` and `denominator` in `OHLC` and `SRMC` responses\n\n#### v0.24\n\n* Add option to filter by `curve-type` in `/metadata/curves/`\n\n#### v0.23\n\n* Add `modified-at-latest` parameter to `/instances/{curve-name}/get/relative/`\n* Fix crash due to incorrect content-type handling in\n endpoint `/instances//get/rolling/`\n* Add `threshold` parameter in documentation for endpoint `/instances//get/rolling/`\n\n#### v0.22\n\n* Added a WebSockets-based **Push Feed API** – our new feature that provides real-time updates\n on curve data.\n* Relative query API endpoint for period-instances\n * Added as endpoint `/period-instances//get/relative/`.\n * Lets you select the latest available instance before a given time of day, per day,\n for **n** days-ahead. Great for extracting known available capacities for REMIT data.\n * Responses as a period series or sampled to a fixed-resolution as a time series.\n* API endpoint for rolling forecast\n * Introduced a novel API endpoint `/instances//get/rolling/`, enabling users to\n access rolling forecasts for specified curves. This feature empowers users to dynamically\n project future performance by utilizing forecasts generated at different timestamps.\n* API endpoint for absolute forecasts\n * Added as endpoint `/instances//get/absolute/`.\n * It allows users to obtain predictions for a specific delivery product (i.e. the forecasted\n power price for a specific day). Useful to see how forecasts develop over time.\n* Deprecated explicit TSV endpoints.\n * The explicit TSV endpoints have been removed from the documentation, but they continue to\n function and will do so in the future. However, they are marked as deprecated. We kindly\n request that you transition to the new solution at your earliest convenience.\n * Added support for TSV on generic endpoints. Users can include `text/tab-separated-values` in\n the `Accept` header of requests to receive responses in TSV format.\n * The TSV parameter `separator` has undergone a name change and is now referred to\n as `decimal-separator`. However, the deprecated TSV endpoints retain the previous name to\n maintain compatibility with older versions.\n* Added support for CSV as Content-Type.\n * Users can now include `text/csv` in the `Accept` header of requests to receive responses in\n CSV format.\n * The CSV configuration can be fine-tuned using the `delimiter` and `decimal-separator`\n parameters.\n* Introduced the `timezone` parameter, which facilitates timezone conversion for enhanced\n flexibility in data interpretation.\n* Introduced the `unit` parameter, allowing users to perform unit conversion for more comprehensive\n data analysis and interpretation.\n* Introduced a new API endpoint `/user/` that provides access to comprehensive user details,\n encompassing personal information and subscription data. This endpoint empowers users to retrieve\n their account-related information and subscription details.\n* Implemented the `Curve.subscription` object field to enhance the representation of curves. This\n field contains details about the subscription that covers the respective curve. This addition\n offers improved visibility into the relationship between curves and their associated\n subscriptions.\n* Deprecated the `Curve.access` field. While this field previously served to indicate access\n permissions, it is now considered deprecated and will no longer be actively supported. Users are\n encouraged to transition to utilizing the enhanced `Curve.subscription` field for\n subscription-related information and access details.\n* Upgraded this documentation to OpenAPI 3.0.1 from OpenAPI 2.0 (also known as Swagger).\n\n#### v0.21\n\n* Add `threshold` parameter.\n\n#### v0.20\n\n* No longer requires parameter `period` and either `front` or `delivery` to be set\n for `/srmc/`. These were required before, but this API operation works similar\n to `/ohlc/`.\n* Allow to supply `front` without supplying `period` for the `/srmc/`\n and `/ohlc/` endpoints.\n* Add `weekend` to list of allowed `period` types in OHLC endpoints.\n\n#### v0.19\n\n* Add field `Curve.commodity`. It is typically set to `Power`, `Gas`, `Oil` etc. When a curve is\n uncategorized, it is set to `None`.\n* Allow filtering by `commodity` in `/metadata/curves/`.\n* Update `Curve.data_type` (`DATA_TYPES` enum) to contain all data types. A few was missing from the\n Swagger documentation.\n* Bugfix: Wrong type for `front` parameter in OHLC and SRMC operations.\n\n#### v0.18\n\n* Add boolean parameter `only-subscribed` to `/metadata/curves/` and `/metadata/curves/data.tsv`\n\n#### v0.17\n\n* Add TSV response support for period-instance\n operations: `/period-instances//get/latest/timeseries/data.tsv`\n and `/period-instances//timeseries/data.tsv`.\n* Add missing parameter `separator` to `/periods//timeseries/data.tsv`.\n\n#### v0.16\n\n* Improve descriptions for OHLC and SRMC operations.\n* Add **fill** parameter for historical OHLC and SRMC operations where the result is converted to a\n time series.\n* Add **carbon-tax-area** parameter to all SRMC operations.\n* Fix bugs in SRMC JSON response schema.\n* Remove invalid parameter **frequency** from `/srmc//timeseries/`\n\n#### v0.15\n\n* Add OHLC operations for converting all contracts for a day a continuous\n series: `/ohlc//latest/periods//`\n and `/ohlc//latest/timeseries//`.\n* Add SRMC operations in TSV format.\n* Fix a bug in OHLC and SRMC conversion to time series for a few corner cases.\n* Fix a bug in the swagger documentation.\n* Add a link to Python client in the beginning of this description.\n", "contact": { "name": "Montel EQ", "url": "https://www.energyquantified.com", "email": "contact@energyquantified.com" }, "version": "0.37" }, "servers": [ { "url": "https://app.energyquantified.com/api" } ], "security": [ { "APIKeyHeader": [] }, { "APIKeyQueryParam": [] } ], "tags": [ { "name": "Metadata", "description": "Search in metadata" }, { "name": "Instances", "description": "Get instance-based time series data (i.e. forecasts)" }, { "name": "Ensemble-instances", "description": "Get instance-based time series data with ensembles/scenarios (i.e. forecasts)" }, { "name": "Time series", "description": "Get time series data" }, { "name": "Period series", "description": "Get period-based series data" }, { "name": "Period series – instances", "description": "Get instances for period-based series data (i.e. forecasts)" }, { "name": "Closing prices", "description": "Get market data from exchanges" }, { "name": "SRMC", "description": "Short-run marginal costs calculated from OHLC data" }, { "name": "Trades", "description": "Get trades from exchanges" }, { "name": "PPA", "description": "Get Power Purchase Agreement (PPA) price data" }, { "name": "Carbon", "description": "Carbon related endpoints." }, { "name": "Collections", "description": "Collections of private curves per customer" } ], "paths": { "/metadata/curves/": { "get": { "tags": [ "Metadata" ], "summary": "Search curves", "description": "Full-text search for curves with filtering on attributes.\n", "parameters": [ { "name": "q", "in": "query", "description": "Full-text search field for curve name", "schema": { "type": "string" } }, { "name": "area", "in": "query", "description": "Filter by area (country, price area or region). If multiple areas are given, the curve must match all of them. Examples: DE, DK, DK1, DK2, NP, IT, IT-NORD etc.", "example": "DE", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "curve-type", "in": "query", "description": "Filter by curve type (i.e. Timeseries, Instance).", "example": "TIMESERIES", "style": "form", "explode": true, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CurveType" } } }, { "name": "data-type", "in": "query", "description": "Filter by data type (i.e. Actual, Forecast).", "example": "ACTUAL", "style": "form", "explode": true, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DataType" } } }, { "name": "category", "in": "query", "description": "Filter by specifying one or more categories. Must specify the exact, case-sensitive name. A Curve always has one or more categories (see Curve model).", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "exact-category", "in": "query", "description": "Filter by an exact combination of categories in curve names (i.e. 'Wind Power Production', 'Spot Price').", "schema": { "type": "string" } }, { "name": "frequency", "in": "query", "description": "Filter by specifying one or more curve frequencies (i.e. PT1H, P1D).", "style": "form", "explode": true, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Frequency" } } }, { "name": "unit", "in": "query", "description": "Filter by specifying one or more units (i.e. MW, MWh/h, EUR). Must specify the exact, case-sensitive name. A curve always has a unit (see Curve model).", "style": "form", "explode": true, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Unit" } } }, { "name": "has-place", "in": "query", "description": "Filter curves by whether or not they do have a `Curve.place` reference. `true` only includes curves with places, `false` excludes curves with places, `all` (default) does not filter at all.", "schema": { "type": "string", "default": "all", "enum": [ "true", "false", "all" ] } }, { "name": "commodity", "in": "query", "description": "Filter by specifying one or more commodities (i.e. Power, Carbon).", "style": "form", "explode": true, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Commodity" } } }, { "name": "source", "in": "query", "description": "Filter by specifying one or more sources (i.e., the origin of data - e.g., NordPool). The string \"null\" matches curves without a source.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "only-subscribed", "in": "query", "description": "List curves included in my subscription only.", "schema": { "type": "boolean" } }, { "name": "page", "in": "query", "description": "Select page.", "schema": { "type": "integer", "default": 1 } }, { "name": "page-size", "in": "query", "description": "Select page size. Allowed pages sizes are between 10 and 250.", "schema": { "maximum": 250, "minimum": 10, "type": "integer", "default": 250 } }, { "name": "delimiter", "in": "query", "description": "Only CSV: Delimiter for values. Possible values are `COMMA` (`a,b,c`) and `SEMICOLON` (`a;b;c`).", "schema": { "$ref": "#/components/schemas/Delimiter" } }, { "name": "decimal-separator", "in": "query", "description": "Only TSV and CSV: Decimal separator for numbers (`PERIOD` for 1.23 or `COMMA` for 1,23).", "schema": { "$ref": "#/components/schemas/DecimalSeparator" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Total-Items": { "description": "The total number of items found", "schema": { "type": "integer" } }, "X-Current-Page": { "description": "The current page", "schema": { "type": "integer" } }, "X-Last-Page": { "description": "The last page", "schema": { "type": "integer" } }, "X-Page-Size": { "description": "Number of items per page", "schema": { "type": "integer" } }, "X-First-Page": { "description": "The first page", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Curve" } } }, "text/tab-separated-values": { "schema": { "type": "string" } }, "text/csv": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/AuthenticationError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/metadata/curves/{curve-name}/": { "get": { "tags": [ "Metadata" ], "summary": "Load metadata for a curve", "description": "Get the `Curve` object for the specified curve name.\n", "parameters": [ { "name": "curve-name", "in": "path", "description": "An urlencoded *curve-name* (see Curve model).", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Curve" } } } }, "401": { "$ref": "#/components/responses/AuthenticationError" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/metadata/places/": { "get": { "tags": [ "Metadata" ], "summary": "Search places", "description": "Full-text search for places with filtering on attributes.\n", "parameters": [ { "name": "q", "in": "query", "description": "Full-text search field for curve name", "schema": { "type": "string" } }, { "name": "area", "in": "query", "description": "Filter by area (country, price area or region). Examples: DE, DK, DK1, DK2, NP, IT, IT-NORD etc.", "schema": { "type": "string" } }, { "name": "fuel", "in": "query", "description": "Filter by fuel types.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "Biomass", "Fossil", "Lignite", "Derived gas", "Natural gas", "Hard coal", "Oil", "Oil shale", "Peat", "Geothermal", "Hydro", "Pumped storage", "Run-of-river", "Water reservoir", "Marine", "Nuclear", "Waste", "Renewable", "Solar", "Wind", "Offshore", "Onshore", "Other" ] } } }, { "name": "type", "in": "query", "description": "Filter by specifying one or place types.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "city", "consumer", "producer", "river", "weatherstation", "other" ] } } }, { "name": "tree", "in": "query", "description": "Defaults to `false`. When `true` this end point will return a list of the top-level places matching given filters and then include their children in the response. When `false` this end point will return all matching places without any hierarchy in the response.", "schema": { "type": "boolean", "default": false } }, { "name": "page", "in": "query", "description": "Select page.", "schema": { "type": "integer", "default": 1 } }, { "name": "page-size", "in": "query", "description": "Select page size. Allowed pages sizes are between 10 and 250.", "schema": { "maximum": 250, "minimum": 10, "type": "integer", "default": 250 } }, { "name": "delimiter", "in": "query", "description": "Only CSV: Delimiter for values. Possible values are `COMMA` (`a,b,c`) and `SEMICOLON` (`a;b;c`).", "schema": { "$ref": "#/components/schemas/Delimiter" } }, { "name": "decimal-separator", "in": "query", "description": "Only TSV and CSV: Decimal separator for numbers (`PERIOD` for 1.23 or `COMMA` for 1,23).", "schema": { "$ref": "#/components/schemas/DecimalSeparator" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Total-Items": { "description": "The total number of items found", "schema": { "type": "integer" } }, "X-Current-Page": { "description": "The current page", "schema": { "type": "integer" } }, "X-Last-Page": { "description": "The last page", "schema": { "type": "integer" } }, "X-Page-Size": { "description": "Number of items per page", "schema": { "type": "integer" } }, "X-First-Page": { "description": "The first page", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Place" } } }, "text/tab-separated-values": { "schema": { "type": "string" } }, "text/csv": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/AuthenticationError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/events/": { "get": { "tags": [ "Push Feed" ], "summary": "Get curve update events", "description": "The Push Feed is a Web Socket endpoint to receive events on updates on curve data. For more information see the description further up.\n", "responses": { "101": { "description": "Switching Protocols" }, "401": { "$ref": "#/components/responses/AuthenticationError" }, "403": { "$ref": "#/components/responses/AccessDenied" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/instances/{curve-name}/": { "get": { "tags": [ "Instances" ], "summary": "Load instances", "description": "Load multiple instances, ordered descending by issue date, for a curve. The instances can be filtered by the issue date and the tag.\n\n**Note:** This operation works for curves with `curve_type = INSTANCE` only.\n", "parameters": [ { "name": "curve-name", "in": "path", "description": "An urlencoded *curve-name* (see Curve model).", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Maximum number of instances to fetch.", "schema": { "maximum": 100, "minimum": 1, "type": "number", "format": "int32", "default": 20 } }, { "name": "tags", "in": "query", "description": "Filter query to include instances with given tags.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "exclude-tags", "in": "query", "description": "Filter query to exclude instances with given tags.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "issued-at-earliest", "in": "query", "description": "The earliest issue date (inclusive).", "schema": { "type": "string", "format": "date-time" } }, { "name": "issued-at-latest", "in": "query", "description": "The latest issue date (inclusive).", "schema": { "type": "string", "format": "date-time" } }, { "name": "issued-time-of-day", "in": "query", "description": "Filter query to include instances issued at any of the given times of day (**HH:mm:ss.SSS** in the instance zone).", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "format": "time" } } }, { "name": "begin", "in": "query", "description": "The ``begin`` and ``end`` parameters can be used to only load a subset of the instances' \ndata. Data points outside this range will be excluded. The range is inclusive and \nexclusive, respectively. The date(time) must be in the curve's resolution.\n\n**Note:** that begin/end does **not** filter which instance(s) to load, only which data points to include.\n\n**Note:** either both of ``begin`` and ``end`` parameters must be provided, or neither.\n", "schema": { "type": "string", "format": "date-time" } }, { "name": "end", "in": "query", "description": "The ``begin`` and ``end`` parameters can be used to only load a subset of the instances' \ndata. Data points outside this range will be excluded. The range is inclusive and \nexclusive, respectively. The date(time) must be in the curve's resolution.\n\n**Note:** that begin/end does **not** filter which instance(s) to load, only which data points to include.\n\n**Note:** either both of ``begin`` and ``end`` parameters must be provided, or neither.\n", "schema": { "type": "string", "format": "date-time" } }, { "name": "timezone", "in": "query", "description": "Convert data into given timezone.", "schema": { "$ref": "#/components/schemas/Timezone" } }, { "name": "unit", "in": "query", "description": "Convert data into given unit.", "schema": { "$ref": "#/components/schemas/Unit" } }, { "name": "frequency", "in": "query", "description": "Aggregate to frequency. Must be equal to or lower than the Curve's original frequency. If equal to Curve's frequency, no aggregation will be performed.", "schema": { "$ref": "#/components/schemas/Frequency" } }, { "name": "aggregation", "in": "query", "description": "Aggregation method when *frequency* is specified.", "schema": { "$ref": "#/components/schemas/Aggregation" } }, { "name": "hour-filter", "in": "query", "description": "Hours to be included (base, peak, etc.) in aggregation when *frequency* is specified.", "schema": { "$ref": "#/components/schemas/Filter" } }, { "$ref": "#/components/parameters/Threshold" }, { "name": "delimiter", "in": "query", "description": "Only CSV: Delimiter for values. Possible values are `COMMA` (`a,b,c`) and `SEMICOLON` (`a;b;c`).", "schema": { "$ref": "#/components/schemas/Delimiter" } }, { "name": "decimal-separator", "in": "query", "description": "Only TSV and CSV: Decimal separator for numbers (`PERIOD` for 1.23 or `COMMA` for 1,23).", "schema": { "$ref": "#/components/schemas/DecimalSeparator" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Timeseries" } } }, "text/tab-separated-values": { "schema": { "type": "string" } }, "text/csv": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/AuthenticationError" }, "403": { "$ref": "#/components/responses/AccessDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/instances/{curve-name}/get/latest/": { "get": { "tags": [ "Instances" ], "summary": "Load the latest instance", "description": "Loads the latest instance for a curve based on the issue date. If no instance is available for the curve (meaning; there is no data), an HTTP 404 response will be returned.\n\n**Note:** This operation works for curves with `curve_type = INSTANCE` only.\n", "parameters": [ { "name": "curve-name", "in": "path", "description": "An urlencoded *curve-name* (see Curve model).", "required": true, "schema": { "type": "string" } }, { "name": "tags", "in": "query", "description": "Filter query to include instances with given tags.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "issued-at-latest", "in": "query", "description": "The latest issue date (inclusive).", "schema": { "type": "string", "format": "date-time" } }, { "name": "issued-time-of-day", "in": "query", "description": "Filter query to include instances issued at any of the given times of day (**HH:mm:ss.SSS** in the instance zone).", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "format": "time" } } }, { "name": "begin", "in": "query", "description": "The ``begin`` and ``end`` parameters can be used to only load a subset of the instances' \ndata. Data points outside this range will be excluded. The range is inclusive and \nexclusive, respectively. The date(time) must be in the curve's resolution.\n\n**Note:** that begin/end does **not** filter which instance(s) to load, only which data points to include.\n\n**Note:** either both of ``begin`` and ``end`` parameters must be provided, or neither.\n", "schema": { "type": "string", "format": "date-time" } }, { "name": "end", "in": "query", "description": "The ``begin`` and ``end`` parameters can be used to only load a subset of the instances' \ndata. Data points outside this range will be excluded. The range is inclusive and \nexclusive, respectively. The date(time) must be in the curve's resolution.\n\n**Note:** that begin/end does **not** filter which instance(s) to load, only which data points to include.\n\n**Note:** either both of ``begin`` and ``end`` parameters must be provided, or neither.\n", "schema": { "type": "string", "format": "date-time" } }, { "name": "timezone", "in": "query", "description": "Convert data into given timezone.", "schema": { "$ref": "#/components/schemas/Timezone" } }, { "name": "unit", "in": "query", "description": "Convert data into given unit.", "schema": { "$ref": "#/components/schemas/Unit" } }, { "name": "frequency", "in": "query", "description": "Aggregate to frequency. Must be equal to or lower than the Curve's original frequency. If equal to Curve's frequency, no aggregation will be performed.", "schema": { "$ref": "#/components/schemas/Frequency" } }, { "name": "aggregation", "in": "query", "description": "Aggregation method when *frequency* is specified.", "schema": { "$ref": "#/components/schemas/Aggregation" } }, { "name": "hour-filter", "in": "query", "description": "Hours to be included (base, peak, etc.) in aggregation when *frequency* is specified.", "schema": { "$ref": "#/components/schemas/Filter" } }, { "$ref": "#/components/parameters/Threshold" }, { "name": "delimiter", "in": "query", "description": "Only CSV: Delimiter for values. Possible values are `COMMA` (`a,b,c`) and `SEMICOLON` (`a;b;c`).", "schema": { "$ref": "#/components/schemas/Delimiter" } }, { "name": "decimal-separator", "in": "query", "description": "Only TSV and CSV: Decimal separator for numbers (`PERIOD` for 1.23 or `COMMA` for 1,23).", "schema": { "$ref": "#/components/schemas/DecimalSeparator" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Timeseries" } }, "text/tab-separated-values": { "schema": { "type": "string" } }, "text/csv": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/AuthenticationError" }, "403": { "$ref": "#/components/responses/AccessDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/instances/{curve-name}/get/{issued}/": { "get": { "tags": [ "Instances" ], "summary": "Get an instance (with blank tag)", "description": "Loads an instance for a curve by the issue date only, meaning the instance tag is blank. If the instance does not exist, an HTTP 404 response will be returned.\n\nIf the instance you want to load has a tag, use `/instances/{curve-name}/get/{issued}/{tag}/` instead.\n\n**Note:** This operation works for curves with `curve_type = INSTANCE` only.\n", "parameters": [ { "name": "curve-name", "in": "path", "description": "An urlencoded *curve-name* (see Curve model).", "required": true, "schema": { "type": "string" } }, { "name": "issued", "in": "path", "description": "The issue date of an Instance.", "required": true, "schema": { "type": "string", "format": "date-time" } }, { "name": "begin", "in": "query", "description": "The ``begin`` and ``end`` parameters can be used to only load a subset of the instances' \ndata. Data points outside this range will be excluded. The range is inclusive and \nexclusive, respectively. The date(time) must be in the curve's resolution.\n\n**Note:** that begin/end does **not** filter which instance(s) to load, only which data points to include.\n\n**Note:** either both of ``begin`` and ``end`` parameters must be provided, or neither.\n", "schema": { "type": "string", "format": "date-time" } }, { "name": "end", "in": "query", "description": "The ``begin`` and ``end`` parameters can be used to only load a subset of the instances' \ndata. Data points outside this range will be excluded. The range is inclusive and \nexclusive, respectively. The date(time) must be in the curve's resolution.\n\n**Note:** that begin/end does **not** filter which instance(s) to load, only which data points to include.\n\n**Note:** either both of ``begin`` and ``end`` parameters must be provided, or neither.\n", "schema": { "type": "string", "format": "date-time" } }, { "name": "timezone", "in": "query", "description": "Convert data into given timezone.", "schema": { "$ref": "#/components/schemas/Timezone" } }, { "name": "unit", "in": "query", "description": "Convert data into given unit.", "schema": { "$ref": "#/components/schemas/Unit" } }, { "name": "frequency", "in": "query", "description": "Aggregate to frequency. Must be equal to or lower than the Curve's original frequency. If equal to Curve's frequency, no aggregation will be performed.", "schema": { "$ref": "#/components/schemas/Frequency" } }, { "name": "aggregation", "in": "query", "description": "Aggregation method when *frequency* is specified.", "schema": { "$ref": "#/components/schemas/Aggregation" } }, { "name": "hour-filter", "in": "query", "description": "Hours to be included (base, peak, etc.) in aggregation when *frequency* is specified.", "schema": { "$ref": "#/components/schemas/Filter" } }, { "$ref": "#/components/parameters/Threshold" }, { "name": "delimiter", "in": "query", "description": "Only CSV: Delimiter for values. Possible values are `COMMA` (`a,b,c`) and `SEMICOLON` (`a;b;c`).", "schema": { "$ref": "#/components/schemas/Delimiter" } }, { "name": "decimal-separator", "in": "query", "description": "Only TSV and CSV: Decimal separator for numbers (`PERIOD` for 1.23 or `COMMA` for 1,23).", "schema": { "$ref": "#/components/schemas/DecimalSeparator" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Timeseries" } }, "text/tab-separated-values": { "schema": { "type": "string" } }, "text/csv": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/AuthenticationError" }, "403": { "$ref": "#/components/responses/AccessDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/instances/{curve-name}/get/{issued}/{tag}/": { "get": { "tags": [ "Instances" ], "summary": "Get an instance", "description": "Loads an instance for a curve by the issue date and a tag. If the instance does not exist, an HTTP 404 response will be returned.\n\nIf the instance you want to load has a blank tag, use `/instances/{curve-name}/get/{issued}/` instead.\n\n**Note:** This operation works for curves with `curve_type = INSTANCE` only.\n", "parameters": [ { "name": "curve-name", "in": "path", "description": "An urlencoded *curve-name* (see Curve model).", "required": true, "schema": { "type": "string" } }, { "name": "issued", "in": "path", "description": "The *issued* field of an Instance.", "required": true, "schema": { "type": "string", "format": "date-time" } }, { "name": "tag", "in": "path", "description": "the *tag* field of an Instance. Cannot be blank.", "required": true, "schema": { "type": "string" } }, { "name": "begin", "in": "query", "description": "The ``begin`` and ``end`` parameters can be used to only load a subset of the instances' \ndata. Data points outside this range will be excluded. The range is inclusive and \nexclusive, respectively. The date(time) must be in the curve's resolution.\n\n**Note:** that begin/end does **not** filter which instance(s) to load, only which data points to include.\n\n**Note:** either both of ``begin`` and ``end`` parameters must be provided, or neither.\n", "schema": { "type": "string", "format": "date-time" } }, { "name": "end", "in": "query", "description": "The ``begin`` and ``end`` parameters can be used to only load a subset of the instances' \ndata. Data points outside this range will be excluded. The range is inclusive and \nexclusive, respectively. The date(time) must be in the curve's resolution.\n\n**Note:** that begin/end does **not** filter which instance(s) to load, only which data points to include.\n\n**Note:** either both of ``begin`` and ``end`` parameters must be provided, or neither.\n", "schema": { "type": "string", "format": "date-time" } }, { "name": "timezone", "in": "query", "description": "Convert data into given timezone.", "schema": { "$ref": "#/components/schemas/Timezone" } }, { "name": "unit", "in": "query", "description": "Convert data into given unit.", "schema": { "$ref": "#/components/schemas/Unit" } }, { "name": "frequency", "in": "query", "description": "Aggregate to frequency. Must be equal to or lower than the Curve's original frequency. If equal to Curve's frequency, no aggregation will be performed.", "schema": { "$ref": "#/components/schemas/Frequency" } }, { "name": "aggregation", "in": "query", "description": "Aggregation method when *frequency* is specified.", "schema": { "$ref": "#/components/schemas/Aggregation" } }, { "name": "hour-filter", "in": "query", "description": "Hours to be included (base, peak, etc.) in aggregation when *frequency* is specified.", "schema": { "$ref": "#/components/schemas/Filter" } }, { "$ref": "#/components/parameters/Threshold" }, { "name": "delimiter", "in": "query", "description": "Only CSV: Delimiter for values. Possible values are `COMMA` (`a,b,c`) and `SEMICOLON` (`a;b;c`).", "schema": { "$ref": "#/components/schemas/Delimiter" } }, { "name": "decimal-separator", "in": "query", "description": "Only TSV and CSV: Decimal separator for numbers (`PERIOD` for 1.23 or `COMMA` for 1,23).", "schema": { "$ref": "#/components/schemas/DecimalSeparator" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Timeseries" } }, "text/tab-separated-values": { "schema": { "type": "string" } }, "text/csv": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/AuthenticationError" }, "403": { "$ref": "#/components/responses/AccessDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/instances/{curve-name}/get/absolute/": { "get": { "tags": [ "Instances" ], "summary": "Load an absolute forecast", "description": "Load various forecasted values for a specific moment in time and analyze the progression of the value over a period.\n\nChoose the desired point in time for the absolute forecast by configuring the `delivery` parameter. Define the time range for selecting instances using the `begin` and `end` parameters. \nAbsolute forecast is not supported for curves with frequency lower than P1D.\n\n**Note:** This operation works for curves with `curve_type = INSTANCE` only.\n", "parameters": [ { "name": "curve-name", "in": "path", "description": "An urlencoded *curve-name* (see Curve model).", "required": true, "schema": { "type": "string" } }, { "name": "delivery", "in": "query", "description": "The point in time to find forecasted values for. If time zone information is not present in the formatted date time, then it will be parsed in the Curve's time zone.", "required": true, "schema": { "type": "string", "format": "date-time" } }, { "name": "begin", "in": "query", "description": "The earliest issued date time (inclusive) an instance can have to be included. If the time zone information is not present in the formatted date time, then it will be parsed in the Curve's instance zone.", "required": true, "schema": { "type": "string", "format": "date-time" } }, { "name": "end", "in": "query", "description": "The latest issued date time (exclusive) an instance can have to be included. If the time zone information is not present in the formatted date time, then it will be parsed in the Curve's instance zone.", "required": true, "schema": { "type": "string", "format": "date-time" } }, { "name": "frequency", "in": "query", "description": "Aggregate to frequency. Must be equal or lower than the Curve's original frequency. Defaults to the Curve's original frequency if not provided.\n", "schema": { "$ref": "#/components/schemas/Frequency" } }, { "name": "hour-filter", "in": "query", "description": "Hours to be included (base, peak, etc.) in aggregation when *frequency* is specified.", "schema": { "$ref": "#/components/schemas/Filter" } }, { "name": "timezone", "in": "query", "description": "Convert data into given timezone. Defaults to the Curve's timezone if not provided.", "schema": { "$ref": "#/components/schemas/Timezone" } }, { "name": "unit", "in": "query", "description": "Convert data into given unit.", "schema": { "$ref": "#/components/schemas/Unit" } }, { "name": "aggregation", "in": "query", "description": "Aggregation method when supplying a frequency that is lower than the Curve's original frequency.", "schema": { "$ref": "#/components/schemas/Aggregation" } }, { "name": "tags", "in": "query", "description": "Filter query to include instances with given tags.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "exclude-tags", "in": "query", "description": "Filter query to exclude instances with given tags.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "delimiter", "in": "query", "description": "Only CSV: Delimiter for values. Possible values are `COMMA` (`a,b,c`) and `SEMICOLON` (`a;b;c`).", "schema": { "$ref": "#/components/schemas/Delimiter" } }, { "name": "decimal-separator", "in": "query", "description": "Only TSV and CSV: Decimal separator for numbers (`PERIOD` for 1.23 or `COMMA` for 1,23).", "schema": { "$ref": "#/components/schemas/DecimalSeparator" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AbsoluteResult" } }, "text/tab-separated-values": { "schema": { "type": "string" } }, "text/csv": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/AuthenticationError" }, "403": { "$ref": "#/components/responses/AccessDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/instances/{curve-name}/get/relative/": { "get": { "tags": [ "Instances" ], "summary": "Load relative instances", "description": "Loads instances *n* days-ahead and stitches them together to a single, continuous time series.\n\nYou must filter the instances by a tag. By default, this operation selects the latest instance for that tag per day (based on its issue date). You can override this behaviour by specifying one the following parameters: *time-of-day* (exact issue time), *after-time-of-day* (issued after some time of the day), or *before-time-of-day* (issued before some time of the day). In addition, you may choose whether to select the *earliest* or the *latest* instance to match those filters from each issue day.\n\nThis operation is useful for loading historical day-ahead forecasts.\n\n**Note:** This operation works for curves with `curve_type = INSTANCE` only.\n", "parameters": [ { "name": "curve-name", "in": "path", "description": "An urlencoded *curve-name* (see Curve model).", "required": true, "schema": { "type": "string" } }, { "name": "days-ahead", "in": "query", "description": "The *N* days ahead of the Instance's issue date. days-head = 0 means intraday forecasts, days-ahead = 1 means day-ahead, days-ahead = 2 means the day after day-ahead, and so on.", "required": true, "schema": { "minimum": 0, "type": "number", "format": "int32" } }, { "name": "begin", "in": "query", "description": "The begin date (inclusive) in the resulting time series. If timezone information is not present in the formatted date time, then it will be parsed in the Curve's timezone", "required": true, "schema": { "type": "string", "format": "date-time" } }, { "name": "end", "in": "query", "description": "The end date (exclusive) in the resulting time series. If timezone information is not present in the formatted date time, then it will be parsed in the Curve's timezone", "required": true, "schema": { "type": "string", "format": "date-time" } }, { "name": "tag", "in": "query", "description": "Filter on the *tag* field of an Instance. One tag allowed only.", "required": true, "schema": { "type": "string" } }, { "name": "time-of-day", "in": "query", "description": "The **time**-part (**HH:mm:ss.SSS**) of the `Instance.issued` must be equal to this specific time of the day. The time is in the same timezone as the `Instance.issued` time. The zone can also be found in the `instance_issued_timezone` field on the `Curve`.", "schema": { "type": "string", "format": "time" } }, { "name": "after-time-of-day", "in": "query", "description": "The **time**-part (**HH:mm:ss.SSS**) of the `Instance.issued` must be **after this time of the day (inclusive)**. The time is in the same timezone as the `Instance.issued` time. The zone can also be found in the `instance_issued_timezone` field on the `Curve`.", "schema": { "type": "string", "format": "time" } }, { "name": "before-time-of-day", "in": "query", "description": "The **time**-part (**HH:mm:ss.SSS**) of the `Instance.issued` must be **before this time of the day (exclusive)**. The time is in the same timezone as the `Instance.issued` time. The zone can also be found in the `instance_issued_timezone` field on the `Curve`.", "schema": { "type": "string", "format": "time" } }, { "name": "issued", "in": "query", "description": "Whether to select the earliest or the latest published instance from each day matching the above time-of-day filters. Default: latest.", "schema": { "type": "string", "enum": [ "earliest", "latest" ] } }, { "name": "modified-at-latest", "in": "query", "description": "The **time**-part (**HH:mm:ss.SSS**) of the `Instance.modified` (or `Instance.created` if `modified` is `null`) must be **before this time of the day (exclusive)**.", "schema": { "type": "string", "format": "time" } }, { "name": "timezone", "in": "query", "description": "Convert data into given timezone.", "schema": { "$ref": "#/components/schemas/Timezone" } }, { "name": "unit", "in": "query", "description": "Convert data into given unit.", "schema": { "$ref": "#/components/schemas/Unit" } }, { "name": "frequency", "in": "query", "description": "Aggregate to frequency. Must be equal to or lower than the Curve's original frequency. If equal to Curve's frequency, no aggregation will be performed.", "schema": { "$ref": "#/components/schemas/Frequency" } }, { "name": "aggregation", "in": "query", "description": "Aggregation method when *frequency* is specified.", "schema": { "$ref": "#/components/schemas/Aggregation" } }, { "name": "hour-filter", "in": "query", "description": "Hours to be included (base, peak, etc.) in aggregation when *frequency* is specified.", "schema": { "$ref": "#/components/schemas/Filter" } }, { "$ref": "#/components/parameters/Threshold" }, { "name": "delimiter", "in": "query", "description": "Only CSV: Delimiter for values. Possible values are `COMMA` (`a,b,c`) and `SEMICOLON` (`a;b;c`).", "schema": { "$ref": "#/components/schemas/Delimiter" } }, { "name": "decimal-separator", "in": "query", "description": "Only TSV and CSV: Decimal separator for numbers (`PERIOD` for 1.23 or `COMMA` for 1,23).", "schema": { "$ref": "#/components/schemas/DecimalSeparator" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Timeseries" } }, "text/tab-separated-values": { "schema": { "type": "string" } }, "text/csv": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/AuthenticationError" }, "403": { "$ref": "#/components/responses/AccessDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/instances/{curve-name}/get/rolling/": { "get": { "tags": [ "Instances" ], "summary": "Load a rolling forecast", "description": "This endpoint allows you to retrieve a rolling forecast for a specified curve. The rolling forecast is generated based on instances created at different timestamps, taking into account the values that fall within a specified time range.\n\nUse the `hours_ahead` parameter to determine the minimum number of hours that must have passed between the created datetime of an instance and its values to be considered in the rolling forecast. The value must be between 0 and 24 (inclusive).\n\nPlease note that the rolling forecast only considers the first 72 hours of the instance's values. If the instance has values beyond this period, they will not be included in the rolling forecast.\n\n**Note:** This operation works for curves with `curve_type = INSTANCE` only.\n", "parameters": [ { "name": "curve-name", "in": "path", "description": "An urlencoded *curve-name* (see Curve model).", "required": true, "schema": { "type": "string" } }, { "name": "hours-ahead", "in": "query", "description": "The minimum number of hours that must have passed between the created datetime of an instance and its values to be considered in the rolling forecast. The value must be between 0 and 24 (inclusive).", "required": true, "schema": { "maximum": 24, "minimum": 0, "type": "number", "format": "int32" } }, { "name": "begin", "in": "query", "description": "The begin date (inclusive) in the resulting time series. If time zone information is not present in the formatted date time, then it will be parsed in the Curve's time zone.", "required": true, "schema": { "type": "string", "format": "date-time" } }, { "name": "end", "in": "query", "description": "The end date (exclusive) in the resulting time series. If time zone information is not present in the formatted date time, then it will be parsed in the Curve's time zone.", "required": true, "schema": { "type": "string", "format": "date-time" } }, { "name": "tags", "in": "query", "description": "Filter query to include instances with given tags.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "exclude-tags", "in": "query", "description": "Filter query to exclude instances with given tags.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "frequency", "in": "query", "description": "Aggregate to frequency. Must be equal to or lower than the Curve's original frequency. If equal to Curve's frequency, no aggregation will be performed.", "schema": { "$ref": "#/components/schemas/Frequency" } }, { "name": "aggregation", "in": "query", "description": "Aggregation method when *frequency* is specified.", "schema": { "$ref": "#/components/schemas/Aggregation" } }, { "name": "hour-filter", "in": "query", "description": "Hours to be included (base, peak, etc.) in aggregation when *frequency* is specified.", "schema": { "$ref": "#/components/schemas/Filter" } }, { "name": "timezone", "in": "query", "description": "Convert data into given timezone.", "schema": { "$ref": "#/components/schemas/Timezone" } }, { "$ref": "#/components/parameters/Threshold" }, { "name": "unit", "in": "query", "description": "Convert data into given unit.", "schema": { "$ref": "#/components/schemas/Unit" } }, { "name": "delimiter", "in": "query", "description": "Only CSV: Delimiter for values. Possible values are `COMMA` (`a,b,c`) and `SEMICOLON` (`a;b;c`).", "schema": { "$ref": "#/components/schemas/Delimiter" } }, { "name": "decimal-separator", "in": "query", "description": "Only TSV and CSV: Decimal separator for numbers (`PERIOD` for 1.23 or `COMMA` for 1,23).", "schema": { "$ref": "#/components/schemas/DecimalSeparator" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Timeseries" } }, "text/tab-separated-values": { "schema": { "type": "string" } }, "text/csv": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/AuthenticationError" }, "403": { "$ref": "#/components/responses/AccessDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/instances/{curve-name}/list/": { "get": { "tags": [ "Instances" ], "summary": "List instances", "description": "Lists the instance objects only (no time series data is loaded by this operation).\n\n**Note:** This operation works for curves with `curve_type = INSTANCE` only.\n", "parameters": [ { "name": "curve-name", "in": "path", "description": "An urlencoded *curve-name* (see Curve model).", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Maximum number of instances to fetch.", "schema": { "maximum": 100, "minimum": 1, "type": "number", "format": "int32", "default": 20 } }, { "name": "tags", "in": "query", "description": "Filter query to include instances with given tags.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "exclude-tags", "in": "query", "description": "Filter query to exclude instances with given tags.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "issued-at-earliest", "in": "query", "description": "The earliest issue date (inclusive).", "schema": { "type": "string", "format": "date-time" } }, { "name": "issued-at-latest", "in": "query", "description": "The latest issue date (inclusive).", "schema": { "type": "string", "format": "date-time" } }, { "name": "issued-time-of-day", "in": "query", "description": "Filter query to include instances issued at any of the given times of day (**HH:mm:ss.SSS** in the instance zone).", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "format": "time" } } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Instance" } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/AuthenticationError" }, "403": { "$ref": "#/components/responses/AccessDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/instances/{curve-name}/tags/": { "get": { "tags": [ "Instances" ], "summary": "List tags", "description": "List all available tags for a curve.\n\n**Note:** This operation works for curves with `curve_type = INSTANCE` only.\n", "parameters": [ { "name": "curve-name", "in": "path", "description": "An urlencoded *curve-name* (see Curve model).", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } } } } }, "401": { "$ref": "#/components/responses/AuthenticationError" }, "403": { "$ref": "#/components/responses/AccessDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/ensembles/{curve-name}/": { "get": { "tags": [ "Ensemble-instances" ], "summary": "Load instances with scenarios/ensembles", "description": "Load multiple instances, ordered descending by issue date, for a curve. The instances can be filtered by the issue date and the tag.\n\nSimilar to `/instances/{curve-name}/`, but this end point also loads scenarios (if there are any). Because the scenarios can be quite costly to retrieve, the limit for how many instances you can load per request is reduced.\n\n**Note:** This operation works for curves with `curve_type = INSTANCE` only.\n", "parameters": [ { "name": "curve-name", "in": "path", "description": "An urlencoded *curve-name* (see Curve model).", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Maximum number of instances to fetch.", "schema": { "maximum": 20, "minimum": 1, "type": "number", "format": "int32", "default": 5 } }, { "name": "tags", "in": "query", "description": "Filter query to include instances with given tags.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "exclude-tags", "in": "query", "description": "Filter query to exclude instances with given tags.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "issued-at-earliest", "in": "query", "description": "The earliest issue date (inclusive).", "schema": { "type": "string", "format": "date-time" } }, { "name": "issued-at-latest", "in": "query", "description": "The latest issue date (inclusive).", "schema": { "type": "string", "format": "date-time" } }, { "name": "issued-time-of-day", "in": "query", "description": "Filter query to include instances issued at any of the given times of day (**HH:mm:ss.SSS** in the instance zone).", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "format": "time" } } }, { "name": "timezone", "in": "query", "description": "Convert data into given timezone.", "schema": { "$ref": "#/components/schemas/Timezone" } }, { "name": "unit", "in": "query", "description": "Convert data into given unit.", "schema": { "$ref": "#/components/schemas/Unit" } }, { "name": "frequency", "in": "query", "description": "Aggregate to frequency. Must be equal to or lower than the Curve's original frequency. If equal to Curve's frequency, no aggregation will be performed.", "schema": { "$ref": "#/components/schemas/Frequency" } }, { "name": "aggregation", "in": "query", "description": "Aggregation method when *frequency* is specified.", "schema": { "$ref": "#/components/schemas/Aggregation" } }, { "name": "hour-filter", "in": "query", "description": "Hours to be included (base, peak, etc.) in aggregation when *frequency* is specified.", "schema": { "$ref": "#/components/schemas/Filter" } }, { "$ref": "#/components/parameters/Threshold" }, { "name": "delimiter", "in": "query", "description": "Only CSV: Delimiter for values. Possible values are `COMMA` (`a,b,c`) and `SEMICOLON` (`a;b;c`).", "schema": { "$ref": "#/components/schemas/Delimiter" } }, { "name": "decimal-separator", "in": "query", "description": "Only TSV and CSV: Decimal separator for numbers (`PERIOD` for 1.23 or `COMMA` for 1,23).", "schema": { "$ref": "#/components/schemas/DecimalSeparator" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Timeseries" } } }, "text/tab-separated-values": { "schema": { "type": "string" } }, "text/csv": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/AuthenticationError" }, "403": { "$ref": "#/components/responses/AccessDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/ensembles/{curve-name}/get/latest/": { "get": { "tags": [ "Ensemble-instances" ], "summary": "Load the latest instance with scenarios/ensembles", "description": "Loads the latest instance for a curve based on the issue date. If no instance is available for the curve (meaning; there is no data), an HTTP 404 response will be returned.\n\n**Note:** This operation works for curves with `curve_type = INSTANCE` only.\n", "parameters": [ { "name": "curve-name", "in": "path", "description": "An urlencoded *curve-name* (see Curve model).", "required": true, "schema": { "type": "string" } }, { "name": "tags", "in": "query", "description": "Filter query to include instances with given tags.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "issued-at-latest", "in": "query", "description": "The latest issue date (inclusive).", "schema": { "type": "string", "format": "date-time" } }, { "name": "issued-time-of-day", "in": "query", "description": "Filter query to include instances issued at any of the given times of day (**HH:mm:ss.SSS** in the instance zone).", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "format": "time" } } }, { "name": "timezone", "in": "query", "description": "Convert data into given timezone.", "schema": { "$ref": "#/components/schemas/Timezone" } }, { "name": "unit", "in": "query", "description": "Convert data into given unit.", "schema": { "$ref": "#/components/schemas/Unit" } }, { "name": "frequency", "in": "query", "description": "Aggregate to frequency. Must be equal to or lower than the Curve's original frequency. If equal to Curve's frequency, no aggregation will be performed.", "schema": { "$ref": "#/components/schemas/Frequency" } }, { "name": "aggregation", "in": "query", "description": "Aggregation method when *frequency* is specified.", "schema": { "$ref": "#/components/schemas/Aggregation" } }, { "name": "hour-filter", "in": "query", "description": "Hours to be included (base, peak, etc.) in aggregation when *frequency* is specified.", "schema": { "$ref": "#/components/schemas/Filter" } }, { "$ref": "#/components/parameters/Threshold" }, { "name": "delimiter", "in": "query", "description": "Only CSV: Delimiter for values. Possible values are `COMMA` (`a,b,c`) and `SEMICOLON` (`a;b;c`).", "schema": { "$ref": "#/components/schemas/Delimiter" } }, { "name": "decimal-separator", "in": "query", "description": "Only TSV and CSV: Decimal separator for numbers (`PERIOD` for 1.23 or `COMMA` for 1,23).", "schema": { "$ref": "#/components/schemas/DecimalSeparator" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Timeseries" } }, "text/tab-separated-values": { "schema": { "type": "string" } }, "text/csv": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/AuthenticationError" }, "403": { "$ref": "#/components/responses/AccessDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/ensembles/{curve-name}/get/{issued}/": { "get": { "tags": [ "Ensemble-instances" ], "summary": "Get an instance including scenarios/ensembles (with blank tag)", "description": "Loads an instance for a curve by the issue date only, meaning the instance tag is blank. If the instance does not exist, an HTTP 404 response will be returned.\n\nIf the instance you want to load has a tag, use `/ensembles/{curve-name}/get/{issued}/{tag}/` instead.\n\n**Note:** This operation works for curves with `curve_type = INSTANCE` only.\n", "parameters": [ { "name": "curve-name", "in": "path", "description": "An urlencoded *curve-name* (see Curve model).", "required": true, "schema": { "type": "string" } }, { "name": "issued", "in": "path", "description": "The *issued* field of an Instance.", "required": true, "schema": { "type": "string", "format": "date-time" } }, { "name": "timezone", "in": "query", "description": "Convert data into given timezone.", "schema": { "$ref": "#/components/schemas/Timezone" } }, { "name": "unit", "in": "query", "description": "Convert data into given unit.", "schema": { "$ref": "#/components/schemas/Unit" } }, { "name": "frequency", "in": "query", "description": "Aggregate to frequency. Must be equal to or lower than the Curve's original frequency. If equal to Curve's frequency, no aggregation will be performed.", "schema": { "$ref": "#/components/schemas/Frequency" } }, { "name": "aggregation", "in": "query", "description": "Aggregation method when *frequency* is specified.", "schema": { "$ref": "#/components/schemas/Aggregation" } }, { "name": "hour-filter", "in": "query", "description": "Hours to be included (base, peak, etc.) in aggregation when *frequency* is specified.", "schema": { "$ref": "#/components/schemas/Filter" } }, { "$ref": "#/components/parameters/Threshold" }, { "name": "delimiter", "in": "query", "description": "Only CSV: Delimiter for values. Possible values are `COMMA` (`a,b,c`) and `SEMICOLON` (`a;b;c`).", "schema": { "$ref": "#/components/schemas/Delimiter" } }, { "name": "decimal-separator", "in": "query", "description": "Only TSV and CSV: Decimal separator for numbers (`PERIOD` for 1.23 or `COMMA` for 1,23).", "schema": { "$ref": "#/components/schemas/DecimalSeparator" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Timeseries" } }, "text/tab-separated-values": { "schema": { "type": "string" } }, "text/csv": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/AuthenticationError" }, "403": { "$ref": "#/components/responses/AccessDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/ensembles/{curve-name}/get/{issued}/{tag}/": { "get": { "tags": [ "Ensemble-instances" ], "summary": "Get an instance including scenarios/ensembles", "description": "Loads an instance for a curve by the issue date and a tag. If the instance does not exist, an HTTP 404 response will be returned.\n\nIf the instance you want to load has a blank tag, use `/ensembles/{curve-name}/get/{issued}/` instead.\n\n**Note:** This operation works for curves with `curve_type = INSTANCE` only.\n", "parameters": [ { "name": "curve-name", "in": "path", "description": "An urlencoded *curve-name* (see Curve model).", "required": true, "schema": { "type": "string" } }, { "name": "issued", "in": "path", "description": "The *issued* field of an Instance.", "required": true, "schema": { "type": "string", "format": "date-time" } }, { "name": "tag", "in": "path", "description": "the *tag* field of an Instance.", "required": true, "schema": { "type": "string" } }, { "name": "timezone", "in": "query", "description": "Convert data into given timezone.", "schema": { "$ref": "#/components/schemas/Timezone" } }, { "name": "unit", "in": "query", "description": "Convert data into given unit.", "schema": { "$ref": "#/components/schemas/Unit" } }, { "name": "frequency", "in": "query", "description": "Aggregate to frequency. Must be equal to or lower than the Curve's original frequency. If equal to Curve's frequency, no aggregation will be performed.", "schema": { "$ref": "#/components/schemas/Frequency" } }, { "name": "aggregation", "in": "query", "description": "Aggregation method when *frequency* is specified.", "schema": { "$ref": "#/components/schemas/Aggregation" } }, { "name": "hour-filter", "in": "query", "description": "Hours to be included (base, peak, etc.) in aggregation when *frequency* is specified.", "schema": { "$ref": "#/components/schemas/Filter" } }, { "$ref": "#/components/parameters/Threshold" }, { "name": "delimiter", "in": "query", "description": "Only CSV: Delimiter for values. Possible values are `COMMA` (`a,b,c`) and `SEMICOLON` (`a;b;c`).", "schema": { "$ref": "#/components/schemas/Delimiter" } }, { "name": "decimal-separator", "in": "query", "description": "Only TSV and CSV: Decimal separator for numbers (`PERIOD` for 1.23 or `COMMA` for 1,23).", "schema": { "$ref": "#/components/schemas/DecimalSeparator" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Timeseries" } }, "text/tab-separated-values": { "schema": { "type": "string" } }, "text/csv": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/AuthenticationError" }, "403": { "$ref": "#/components/responses/AccessDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/timeseries/{curve-name}/": { "get": { "tags": [ "Time series" ], "summary": "Load a time series", "description": "Loads time series data for a curve. The *begin* and *end* query arguments are required.\n\n**Note:** This operation works for curves with `curve_type = TIMESERIES | SCENARIO_TIMESERIES` only.\n", "parameters": [ { "name": "curve-name", "in": "path", "description": "An urlencoded *curve-name* (see Curve model).", "required": true, "schema": { "type": "string" } }, { "name": "begin", "in": "query", "description": "The begin date (inclusive). If timezone information is not present in the formatted date time, then it will be parsed in the Curve's timezone", "required": true, "schema": { "type": "string", "format": "date-time" } }, { "name": "end", "in": "query", "description": "The end date (exclusive). If timezone information is not present in the formatted date time, then it will be parsed in the Curve's timezone", "required": true, "schema": { "type": "string", "format": "date-time" } }, { "name": "timezone", "in": "query", "description": "Convert data into given timezone.", "schema": { "$ref": "#/components/schemas/Timezone" } }, { "name": "unit", "in": "query", "description": "Convert data into given unit.", "schema": { "$ref": "#/components/schemas/Unit" } }, { "name": "frequency", "in": "query", "description": "Aggregate to frequency. Must be equal to or lower than the Curve's original frequency. If equal to Curve's frequency, no aggregation will be performed.", "schema": { "$ref": "#/components/schemas/Frequency" } }, { "name": "aggregation", "in": "query", "description": "Aggregation method when *frequency* is specified.", "schema": { "$ref": "#/components/schemas/Aggregation" } }, { "name": "hour-filter", "in": "query", "description": "Hours to be included (base, peak, etc.) in aggregation when *frequency* is specified.", "schema": { "$ref": "#/components/schemas/Filter" } }, { "$ref": "#/components/parameters/Threshold" }, { "name": "delimiter", "in": "query", "description": "Only CSV: Delimiter for values. Possible values are `COMMA` (`a,b,c`) and `SEMICOLON` (`a;b;c`).", "schema": { "$ref": "#/components/schemas/Delimiter" } }, { "name": "decimal-separator", "in": "query", "description": "Only TSV and CSV: Decimal separator for numbers (`PERIOD` for 1.23 or `COMMA` for 1,23).", "schema": { "$ref": "#/components/schemas/DecimalSeparator" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Timeseries" } }, "text/tab-separated-values": { "schema": { "type": "string" } }, "text/csv": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/AuthenticationError" }, "403": { "$ref": "#/components/responses/AccessDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/periods/{curve-name}/": { "get": { "tags": [ "Period series" ], "summary": "Load a period-based series", "description": "While regular time series has data on a fixed interval, period-based series consists of a list of date intervals with one value per interval. The intervals cannot overlap, but there may be holes where data is missing.\n\nIf you would like to download a period-based as a regular time series, see `/periods/{curve-name}/timeseries/`.\n\n**Note:** This operation works for curves with `curve_type = PERIOD | INSTANCE_PERIOD` only. When `curve_type = INSTANCE_PERIOD`, this operation will load the latest instance for that curve. If no instance is available, an empty period series will be returned.\n", "parameters": [ { "name": "curve-name", "in": "path", "description": "An urlencoded *curve-name* (see Curve model). `Curve.curve_type` must be either `PERIOD` or `INSTANCE_PERIOD`. In the case when a curve is of type `INSTANCE_PERIOD`, the latest instance will be loaded.", "required": true, "schema": { "type": "string" } }, { "name": "begin", "in": "query", "description": "The begin date (inclusive). If timezone information is not present in the formatted date time, then it will be parsed in the Curve's timezone", "required": true, "schema": { "type": "string", "format": "date-time" } }, { "name": "end", "in": "query", "description": "The end date (exclusive). If timezone information is not present in the formatted date time, then it will be parsed in the Curve's timezone", "required": true, "schema": { "type": "string", "format": "date-time" } }, { "name": "timezone", "in": "query", "description": "Convert data into given timezone.", "schema": { "$ref": "#/components/schemas/Timezone" } }, { "name": "unit", "in": "query", "description": "Convert data into given unit.", "schema": { "$ref": "#/components/schemas/Unit" } }, { "name": "delimiter", "in": "query", "description": "Only CSV: Delimiter for values. Possible values are `COMMA` (`a,b,c`) and `SEMICOLON` (`a;b;c`).", "schema": { "$ref": "#/components/schemas/Delimiter" } }, { "name": "decimal-separator", "in": "query", "description": "Only TSV and CSV: Decimal separator for numbers (`PERIOD` for 1.23 or `COMMA` for 1,23).", "schema": { "$ref": "#/components/schemas/DecimalSeparator" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Periodseries" } }, "text/tab-separated-values": { "schema": { "type": "string" } }, "text/csv": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/AuthenticationError" }, "403": { "$ref": "#/components/responses/AccessDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/periods/{curve-name}/timeseries/": { "get": { "tags": [ "Period series" ], "summary": "Load a period-based series as a time series", "description": "Loads a period-based series, converted to a regular time series.\n\nBecause period-based series' do not have a frequency (or rather has `frequency = NONE`), you must specify the *frequency* for the resulting time series in this operation. The returned time series will be the *weighted-average values* of the original periods when periods do not align with the given frequency.\n\n**Note:** This operation works for curves with `curve_type = PERIOD | INSTANCE_PERIOD` only. When `curve_type = INSTANCE_PERIOD`, this operation will load the latest instance for that curve. If no instance is available, an empty period series will be returned.\n", "parameters": [ { "name": "curve-name", "in": "path", "description": "An urlencoded *curve-name* (see Curve model). `Curve.curve_type` must be either `PERIOD` or `INSTANCE_PERIOD`. In the case when a curve is of type `INSTANCE_PERIOD`, the latest instance will be loaded.", "required": true, "schema": { "type": "string" } }, { "name": "frequency", "in": "query", "description": "The frequency of the resulting time series.", "required": true, "schema": { "$ref": "#/components/schemas/Frequency" } }, { "name": "begin", "in": "query", "description": "The begin date (inclusive). If timezone information is not present in the formatted date time, then it will be parsed in the Curve's timezone", "required": true, "schema": { "type": "string", "format": "date-time" } }, { "name": "end", "in": "query", "description": "The end date (exclusive). If time zone information is not present in the formatted date time, then it will be parsed in the Curve's time zone.", "required": true, "schema": { "type": "string", "format": "date-time" } }, { "name": "delimiter", "in": "query", "description": "Only CSV: Delimiter for values. Possible values are `COMMA` (`a,b,c`) and `SEMICOLON` (`a;b;c`).", "schema": { "$ref": "#/components/schemas/Delimiter" } }, { "name": "decimal-separator", "in": "query", "description": "Only TSV and CSV: Decimal separator for numbers (`PERIOD` for 1.23 or `COMMA` for 1,23).", "schema": { "$ref": "#/components/schemas/DecimalSeparator" } }, { "name": "timezone", "in": "query", "description": "Convert data into given timezone.", "schema": { "$ref": "#/components/schemas/Timezone" } }, { "name": "unit", "in": "query", "description": "Convert data into given unit.", "schema": { "$ref": "#/components/schemas/Unit" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Timeseries" } }, "text/tab-separated-values": { "schema": { "type": "string" } }, "text/csv": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/AuthenticationError" }, "403": { "$ref": "#/components/responses/AccessDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/period-instances/{curve-name}/": { "get": { "tags": [ "Period series – instances" ], "summary": "Load period-based series instances", "description": "Loads multiple instances of period-based series (i.e. different forecasts or REMIT capacities updated at different times).\n\nWhile regular time series has data on a fixed interval, period-based series consists of a list of date intervals with one value per interval. The intervals cannot overlap, but there may be holes where data is missing.\n\nIf you would like to download the instances as regular time series, see `/period-instances/{curve-name}/timeseries/`.\n\n**Note:** This operation works for curves with `curve_type = INSTANCE_PERIOD` only.\n", "parameters": [ { "name": "curve-name", "in": "path", "description": "An urlencoded *curve-name* (see Curve model).", "required": true, "schema": { "type": "string" } }, { "name": "begin", "in": "query", "description": "The begin date (inclusive). If timezone information is not present in the formatted date time, then it will be parsed in the Curve's timezone", "required": true, "schema": { "type": "string", "format": "date-time" } }, { "name": "end", "in": "query", "description": "The end date (exclusive). If timezone information is not present in the formatted date time, then it will be parsed in the Curve's timezone", "required": true, "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "description": "Maximum number of instances to fetch.", "schema": { "maximum": 20, "minimum": 1, "type": "number", "format": "int32", "default": 5 } }, { "name": "tags", "in": "query", "description": "Filter query to include instances with given tags.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "exclude-tags", "in": "query", "description": "Filter query to exclude instances with given tags.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "issued-at-earliest", "in": "query", "description": "The earliest issue date (inclusive).", "schema": { "type": "string", "format": "date-time" } }, { "name": "issued-at-latest", "in": "query", "description": "The latest issue date (inclusive).", "schema": { "type": "string", "format": "date-time" } }, { "name": "timezone", "in": "query", "description": "Convert data into given timezone.", "schema": { "$ref": "#/components/schemas/Timezone" } }, { "name": "unit", "in": "query", "description": "Convert data into given unit.", "schema": { "$ref": "#/components/schemas/Unit" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Periodseries" } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/AuthenticationError" }, "403": { "$ref": "#/components/responses/AccessDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/period-instances/{curve-name}/timeseries/": { "get": { "tags": [ "Period series – instances" ], "summary": "Load period-based series instances as time series", "description": "Loads multiple instances of period-based series, converted to time series'.\n\nBecause period-based series' do not have a frequency (or rather has `frequency = NONE`), you must specify the *frequency* for the resulting time series in this operation. The returned time series will be the *weighted-average values* of the original periods when periods do not align with the given frequency.\n\nIf you would like to download the instances as period-based series, see `/period-instances/{curve-name}/`.\n\n**Note:** This operation works for curves with `curve_type = INSTANCE_PERIOD` only.\n", "parameters": [ { "name": "curve-name", "in": "path", "description": "An urlencoded *curve-name* (see Curve model).", "required": true, "schema": { "type": "string" } }, { "name": "frequency", "in": "query", "description": "The frequency of the output time series.", "required": true, "schema": { "$ref": "#/components/schemas/Frequency" } }, { "name": "begin", "in": "query", "description": "The begin date (inclusive). If timezone information is not present in the formatted date time, then it will be parsed in the Curve's timezone", "required": true, "schema": { "type": "string", "format": "date-time" } }, { "name": "end", "in": "query", "description": "The end date (exclusive). If timezone information is not present in the formatted date time, then it will be parsed in the Curve's timezone", "required": true, "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "description": "Maximum number of instances to fetch.", "schema": { "maximum": 20, "minimum": 1, "type": "number", "format": "int32", "default": 5 } }, { "name": "tags", "in": "query", "description": "Filter query to include instances with given tags.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "exclude-tags", "in": "query", "description": "Filter query to exclude instances with given tags.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "issued-at-earliest", "in": "query", "description": "The earliest issue date (inclusive).", "schema": { "type": "string", "format": "date-time" } }, { "name": "issued-at-latest", "in": "query", "description": "The latest issue date (inclusive).", "schema": { "type": "string", "format": "date-time" } }, { "name": "delimiter", "in": "query", "description": "Only CSV: Delimiter for values. Possible values are `COMMA` (`a,b,c`) and `SEMICOLON` (`a;b;c`).", "schema": { "$ref": "#/components/schemas/Delimiter" } }, { "name": "decimal-separator", "in": "query", "description": "Only TSV and CSV: Decimal separator for numbers (`PERIOD` for 1.23 or `COMMA` for 1,23).", "schema": { "$ref": "#/components/schemas/DecimalSeparator" } }, { "name": "timezone", "in": "query", "description": "Convert data into given timezone.", "schema": { "$ref": "#/components/schemas/Timezone" } }, { "name": "unit", "in": "query", "description": "Convert data into given unit.", "schema": { "$ref": "#/components/schemas/Unit" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Timeseries" } } }, "text/tab-separated-values": { "schema": { "type": "string" } }, "text/csv": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/AuthenticationError" }, "403": { "$ref": "#/components/responses/AccessDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/period-instances/{curve-name}/get/latest/": { "get": { "tags": [ "Period series – instances" ], "summary": "Get the latest period-based series instance", "description": "Loads the latest period-based series instance.\n\nWhile regular time series has data on a fixed interval, period-based series consists of a list of date intervals with one value per interval. The intervals cannot overlap, but there may be holes where data is missing.\n\nIf you would like to download the instance as a regular time series, see `/period-instances/{curve-name}/get/latest/timeseries/`.\n\n**Note:** This operation works for curves with `curve_type = INSTANCE_PERIOD` only.\n", "parameters": [ { "name": "curve-name", "in": "path", "description": "An urlencoded *curve-name* (see Curve model).", "required": true, "schema": { "type": "string" } }, { "name": "begin", "in": "query", "description": "The begin date (inclusive). If timezone information is not present in the formatted date time, then it will be parsed in the Curve's timezone", "required": true, "schema": { "type": "string", "format": "date-time" } }, { "name": "end", "in": "query", "description": "The end date (exclusive). If timezone information is not present in the formatted date time, then it will be parsed in the Curve's timezone", "required": true, "schema": { "type": "string", "format": "date-time" } }, { "name": "issued-at-latest", "in": "query", "description": "The latest issue date (inclusive).", "schema": { "type": "string", "format": "date-time" } }, { "name": "timezone", "in": "query", "description": "Convert data into given timezone.", "schema": { "$ref": "#/components/schemas/Timezone" } }, { "name": "unit", "in": "query", "description": "Convert data into given unit.", "schema": { "$ref": "#/components/schemas/Unit" } }, { "name": "delimiter", "in": "query", "description": "Only CSV: Delimiter for values. Possible values are `COMMA` (`a,b,c`) and `SEMICOLON` (`a;b;c`).", "schema": { "$ref": "#/components/schemas/Delimiter" } }, { "name": "decimal-separator", "in": "query", "description": "Only TSV and CSV: Decimal separator for numbers (`PERIOD` for 1.23 or `COMMA` for 1,23).", "schema": { "$ref": "#/components/schemas/DecimalSeparator" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Periodseries" } }, "text/tab-separated-values": { "schema": { "type": "string" } }, "text/csv": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/AuthenticationError" }, "403": { "$ref": "#/components/responses/AccessDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/period-instances/{curve-name}/get/latest/timeseries/": { "get": { "tags": [ "Period series – instances" ], "summary": "Get the latest period-based series instance as time series", "description": "Loads the latest period-based series instance, converted to a time series.\n\nBecause period-based series' do not have a frequency (or rather has `frequency = NONE`), you must specify the *frequency* for the resulting time series in this operation. The returned time series will be the *weighted-average values* of the original periods when periods do not align with the given frequency.\n\nIf you would like to download the instance as a period-based series, see `/period-instances/{curve-name}/get/latest/`.\n\n**Note:** This operation works for curves with `curve_type = INSTANCE_PERIOD` only.\n", "parameters": [ { "name": "curve-name", "in": "path", "description": "An urlencoded *curve-name* (see Curve model).", "required": true, "schema": { "type": "string" } }, { "name": "frequency", "in": "query", "description": "The frequency of the output time series.", "required": true, "schema": { "$ref": "#/components/schemas/Frequency" } }, { "name": "begin", "in": "query", "description": "The begin date (inclusive). If timezone information is not present in the formatted date time, then it will be parsed in the Curve's timezone", "required": true, "schema": { "type": "string", "format": "date-time" } }, { "name": "end", "in": "query", "description": "The end date (exclusive). If timezone information is not present in the formatted date time, then it will be parsed in the Curve's timezone", "required": true, "schema": { "type": "string", "format": "date-time" } }, { "name": "issued-at-latest", "in": "query", "description": "The latest issue date (inclusive).", "schema": { "type": "string", "format": "date-time" } }, { "name": "delimiter", "in": "query", "description": "Only CSV: Delimiter for values. Possible values are `COMMA` (`a,b,c`) and `SEMICOLON` (`a;b;c`).", "schema": { "$ref": "#/components/schemas/Delimiter" } }, { "name": "decimal-separator", "in": "query", "description": "Only TSV and CSV: Decimal separator for numbers (`PERIOD` for 1.23 or `COMMA` for 1,23).", "schema": { "$ref": "#/components/schemas/DecimalSeparator" } }, { "name": "timezone", "in": "query", "description": "Convert data into given timezone.", "schema": { "$ref": "#/components/schemas/Timezone" } }, { "name": "unit", "in": "query", "description": "Convert data into given unit.", "schema": { "$ref": "#/components/schemas/Unit" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Timeseries" } }, "text/tab-separated-values": { "schema": { "type": "string" } }, "text/csv": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/AuthenticationError" }, "403": { "$ref": "#/components/responses/AccessDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/period-instances/{curve-name}/get/relative/": { "get": { "tags": [ "Period series – instances" ], "summary": "Get a relative forecast for period-based series instances", "description": "Loads period-based series instances *n* days-ahead and stitches them together to a single, continuous period series.\n\nThis operation is useful for loading historical day-ahead forecasts.\n\nWhile regular time series has data on a fixed interval, period-based series consists of a list of date intervals with one value per interval. The intervals cannot overlap, but there may be holes where data is missing.\n\nIf you would like to download the relative forecast as a regular time series, see `/period-instances/{curve-name}/get/relative/timeseries/`.\n\n**Note:** This operation works for curves with `curve_type = INSTANCE_PERIOD` only.\n", "parameters": [ { "name": "curve-name", "in": "path", "description": "An urlencoded *curve-name* (see Curve model).", "required": true, "schema": { "type": "string" } }, { "name": "begin", "in": "query", "description": "The begin date (inclusive). If timezone information is not present in the formatted date time, then it will be parsed in the Curve's timezone", "required": true, "schema": { "type": "string", "format": "date-time" } }, { "name": "end", "in": "query", "description": "The end date (exclusive). If timezone information is not present in the formatted date time, then it will be parsed in the Curve's timezone", "required": true, "schema": { "type": "string", "format": "date-time" } }, { "name": "days-ahead", "in": "query", "description": "The *n* days ahead of the instance's issue date. days-head = 0 means intraday forecasts, days-ahead = 1 means day-ahead, days-ahead = 2 means the day after day-ahead, and so on.", "required": true, "schema": { "minimum": 0, "type": "number", "format": "int32" } }, { "name": "before-time-of-day", "in": "query", "description": "The **time**-part (**HH:mm:ss.SSS**) of the `Instance.issued` must be **before this time of the day (exclusive)**. The time is in the same timezone as the `Instance.issued` time. The zone can also be found in the `instance_issued_timezone` field on the `Curve`.", "schema": { "type": "string", "format": "time" } }, { "name": "timezone", "in": "query", "description": "Convert data into given timezone.", "schema": { "$ref": "#/components/schemas/Timezone" } }, { "name": "unit", "in": "query", "description": "Convert data into given unit.", "schema": { "$ref": "#/components/schemas/Unit" } }, { "name": "delimiter", "in": "query", "description": "Only CSV: Delimiter for values. Possible values are `COMMA` (`a,b,c`) and `SEMICOLON` (`a;b;c`).", "schema": { "$ref": "#/components/schemas/Delimiter" } }, { "name": "decimal-separator", "in": "query", "description": "Only TSV and CSV: Decimal separator for numbers (`PERIOD` for 1.23 or `COMMA` for 1,23).", "schema": { "$ref": "#/components/schemas/DecimalSeparator" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Periodseries" } }, "text/tab-separated-values": { "schema": { "type": "string" } }, "text/csv": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/AuthenticationError" }, "403": { "$ref": "#/components/responses/AccessDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/period-instances/{curve-name}/get/relative/timeseries/": { "get": { "tags": [ "Period series – instances" ], "summary": "Get a relative forecast for period-based series instances as time series", "description": "Loads period-based series instances *n* days-ahead and stitches them together to a single, continuous time series.\n\nThis operation is useful for loading historical day-ahead forecasts.\n\nBecause period-based series' do not have a frequency (or rather has `frequency = NONE`), you must specify the *frequency* for the resulting time series in this operation. The returned time series will be the *weighted-average values* of the original periods when periods do not align with the given frequency.\n\nIf you would like to download the relative forecast as a period-based series, see `/period-instances/{curve-name}/get/relative/`.\n\n**Note:** This operation works for curves with `curve_type = INSTANCE_PERIOD` only.\n", "parameters": [ { "name": "curve-name", "in": "path", "description": "An urlencoded *curve-name* (see Curve model).", "required": true, "schema": { "type": "string" } }, { "name": "frequency", "in": "query", "description": "The frequency of the output time series.", "required": true, "schema": { "$ref": "#/components/schemas/Frequency" } }, { "name": "begin", "in": "query", "description": "The begin date (inclusive). If timezone information is not present in the formatted date time, then it will be parsed in the Curve's timezone", "required": true, "schema": { "type": "string", "format": "date-time" } }, { "name": "end", "in": "query", "description": "The end date (exclusive). If timezone information is not present in the formatted date time, then it will be parsed in the Curve's timezone", "required": true, "schema": { "type": "string", "format": "date-time" } }, { "name": "days-ahead", "in": "query", "description": "The *n* days ahead of the instance's issue date. days-head = 0 means intraday forecasts, days-ahead = 1 means day-ahead, days-ahead = 2 means the day after day-ahead, and so on.", "required": true, "schema": { "minimum": 0, "type": "number", "format": "int32" } }, { "name": "before-time-of-day", "in": "query", "description": "The **time**-part (**HH:mm:ss.SSS**) of the `Instance.issued` must be **before this time of the day (exclusive)**. The time is in the same timezone as the `Instance.issued` time. The zone can also be found in the `instance_issued_timezone` field on the `Curve`.", "schema": { "type": "string", "format": "time" } }, { "name": "delimiter", "in": "query", "description": "Only CSV: Delimiter for values. Possible values are `COMMA` (`a,b,c`) and `SEMICOLON` (`a;b;c`).", "schema": { "$ref": "#/components/schemas/Delimiter" } }, { "name": "decimal-separator", "in": "query", "description": "Only TSV and CSV: Decimal separator for numbers (`PERIOD` for 1.23 or `COMMA` for 1,23).", "schema": { "$ref": "#/components/schemas/DecimalSeparator" } }, { "name": "timezone", "in": "query", "description": "Convert data into given timezone.", "schema": { "$ref": "#/components/schemas/Timezone" } }, { "name": "unit", "in": "query", "description": "Convert data into given unit.", "schema": { "$ref": "#/components/schemas/Unit" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Timeseries" } }, "text/tab-separated-values": { "schema": { "type": "string" } }, "text/csv": { "schema": { "type": "string" } } } } } } }, "/period-instances/{curve-name}/get/{issued}/": { "get": { "tags": [ "Period series – instances" ], "summary": "Get a period-based series instance (with blank tag)", "description": "Loads a period-based series instance by the issue date. The instance must have a blank tag. If the instance does not exist, an HTTP 404 response will be returned.\n\nWhile regular time series has data on a fixed interval, period-based series consists of a list of date intervals with one value per interval. The intervals cannot overlap, but there may be holes where data is missing.\n\nIf you would like to download the instance as a regular time series, see `/period-instances/{curve-name}/get/{issued}/timeseries/`.\n\n**Note:** This operation works for curves with `curve_type = INSTANCE_PERIOD` only.\n", "parameters": [ { "name": "curve-name", "in": "path", "description": "An urlencoded *curve-name* (see Curve model).", "required": true, "schema": { "type": "string" } }, { "name": "issued", "in": "path", "description": "The *issued* field of an Instance.", "required": true, "schema": { "type": "string", "format": "date-time" } }, { "name": "begin", "in": "query", "description": "The begin date (inclusive). If timezone information is not present in the formatted date time, then it will be parsed in the Curve's timezone", "required": true, "schema": { "type": "string", "format": "date-time" } }, { "name": "end", "in": "query", "description": "The end date (exclusive). If timezone information is not present in the formatted date time, then it will be parsed in the Curve's timezone", "required": true, "schema": { "type": "string", "format": "date-time" } }, { "name": "timezone", "in": "query", "description": "Convert data into given timezone.", "schema": { "$ref": "#/components/schemas/Timezone" } }, { "name": "unit", "in": "query", "description": "Convert data into given unit.", "schema": { "$ref": "#/components/schemas/Unit" } }, { "name": "delimiter", "in": "query", "description": "Only CSV: Delimiter for values. Possible values are `COMMA` (`a,b,c`) and `SEMICOLON` (`a;b;c`).", "schema": { "$ref": "#/components/schemas/Delimiter" } }, { "name": "decimal-separator", "in": "query", "description": "Only TSV and CSV: Decimal separator for numbers (`PERIOD` for 1.23 or `COMMA` for 1,23).", "schema": { "$ref": "#/components/schemas/DecimalSeparator" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Periodseries" } }, "text/tab-separated-values": { "schema": { "type": "string" } }, "text/csv": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/AuthenticationError" }, "403": { "$ref": "#/components/responses/AccessDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/period-instances/{curve-name}/get/{issued}/timeseries/": { "get": { "tags": [ "Period series – instances" ], "summary": "Get a period-based series instance as time series (with blank tag)", "description": "Loads a period-based series instance by the issue date. The instance must have a blank tag. If the instance does not exist, an HTTP 404 response will be returned.\n\nBecause period-based series' do not have a frequency (or rather has `frequency = NONE`), you must specify the *frequency* for the resulting time series in this operation. The returned time series will be the *weighted-average values* of the original periods when periods do not align with the given frequency.\n\nIf you would like to download the instance as a period-based series, see `/period-instances/{curve-name}/get/{issued}/`.\n\n**Note:** This operation works for curves with `curve_type = INSTANCE_PERIOD` only.\n", "parameters": [ { "name": "curve-name", "in": "path", "description": "An urlencoded *curve-name* (see Curve model).", "required": true, "schema": { "type": "string" } }, { "name": "issued", "in": "path", "description": "The *issued* field of an Instance.", "required": true, "schema": { "type": "string", "format": "date-time" } }, { "name": "frequency", "in": "query", "description": "The frequency of the output time series.", "required": true, "schema": { "$ref": "#/components/schemas/Frequency" } }, { "name": "begin", "in": "query", "description": "The begin date (inclusive). If timezone information is not present in the formatted date time, then it will be parsed in the Curve's timezone", "required": true, "schema": { "type": "string", "format": "date-time" } }, { "name": "end", "in": "query", "description": "The end date (exclusive). If time zone information is not present in the formatted date time, then it will be parsed in the Curve's time zone.", "required": true, "schema": { "type": "string", "format": "date-time" } }, { "name": "delimiter", "in": "query", "description": "Only CSV: Delimiter for values. Possible values are `COMMA` (`a,b,c`) and `SEMICOLON` (`a;b;c`).", "schema": { "$ref": "#/components/schemas/Delimiter" } }, { "name": "decimal-separator", "in": "query", "description": "Only TSV and CSV: Decimal separator for numbers (`PERIOD` for 1.23 or `COMMA` for 1,23).", "schema": { "$ref": "#/components/schemas/DecimalSeparator" } }, { "name": "timezone", "in": "query", "description": "Convert data into given timezone.", "schema": { "$ref": "#/components/schemas/Timezone" } }, { "name": "unit", "in": "query", "description": "Convert data into given unit.", "schema": { "$ref": "#/components/schemas/Unit" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Timeseries" } }, "text/tab-separated-values": { "schema": { "type": "string" } }, "text/csv": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/AuthenticationError" }, "403": { "$ref": "#/components/responses/AccessDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/period-instances/{curve-name}/get/{issued}/{tag}/": { "get": { "tags": [ "Period series – instances" ], "summary": "Get a period-based series instance", "description": "Loads a period-based series instance by the issue date and tag. If the instance does not exist, an HTTP 404 response will be returned.\n\nBecause period-based series' do not have a frequency (or rather has `frequency = NONE`), you must specify the *frequency* for the resulting time series in this operation. The returned time series will be the *weighted-average values* of the original periods when periods do not align with the given frequency.\n\nIf you would like to download the instance as a time series, see `/period-instances/{curve-name}/get/{issued}/{tag}/timeseries/`.\n\n**Note:** This operation works for curves with `curve_type = INSTANCE_PERIOD` only.\n", "parameters": [ { "name": "curve-name", "in": "path", "description": "An urlencoded *curve-name* (see Curve model).", "required": true, "schema": { "type": "string" } }, { "name": "issued", "in": "path", "description": "The *issued* field of an Instance.", "required": true, "schema": { "type": "string", "format": "date-time" } }, { "name": "tag", "in": "path", "description": "the *tag* field of an Instance.", "required": true, "schema": { "type": "string" } }, { "name": "begin", "in": "query", "description": "The begin date (inclusive). If timezone information is not present in the formatted date time, then it will be parsed in the Curve's timezone", "required": true, "schema": { "type": "string", "format": "date-time" } }, { "name": "end", "in": "query", "description": "The end date (exclusive). If timezone information is not present in the formatted date time, then it will be parsed in the Curve's timezone", "required": true, "schema": { "type": "string", "format": "date-time" } }, { "name": "timezone", "in": "query", "description": "Convert data into given timezone.", "schema": { "$ref": "#/components/schemas/Timezone" } }, { "name": "unit", "in": "query", "description": "Convert data into given unit.", "schema": { "$ref": "#/components/schemas/Unit" } }, { "name": "delimiter", "in": "query", "description": "Only CSV: Delimiter for values. Possible values are `COMMA` (`a,b,c`) and `SEMICOLON` (`a;b;c`).", "schema": { "$ref": "#/components/schemas/Delimiter" } }, { "name": "decimal-separator", "in": "query", "description": "Only TSV and CSV: Decimal separator for numbers (`PERIOD` for 1.23 or `COMMA` for 1,23).", "schema": { "$ref": "#/components/schemas/DecimalSeparator" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Periodseries" } }, "text/tab-separated-values": { "schema": { "type": "string" } }, "text/csv": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/AuthenticationError" }, "403": { "$ref": "#/components/responses/AccessDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/period-instances/{curve-name}/get/{issued}/{tag}/timeseries/": { "get": { "tags": [ "Period series – instances" ], "summary": "Get a period-based series instance as time series", "description": "Loads a period-based series instance by the issue date and tag. If the instance does not exist, an HTTP 404 response will be returned.\n\nBecause period-based series' do not have a frequency (or rather has `frequency = NONE`), you must specify the *frequency* for the resulting time series in this operation. The returned time series will be the *weighted-average values* of the original periods when periods do not align with the given frequency.\n\nIf you would like to download the instance as a period-based series, see `/period-instances/{curve-name}/get/{issued}/{tag}/`.\n\n**Note:** This operation works for curves with `curve_type = INSTANCE_PERIOD` only.\n", "parameters": [ { "name": "curve-name", "in": "path", "description": "An urlencoded *curve-name* (see Curve model).", "required": true, "schema": { "type": "string" } }, { "name": "issued", "in": "path", "description": "The *issued* field of an Instance.", "required": true, "schema": { "type": "string", "format": "date-time" } }, { "name": "tag", "in": "path", "description": "the *tag* field of an Instance.", "required": true, "schema": { "type": "string" } }, { "name": "frequency", "in": "query", "description": "The frequency of the output time series.", "required": true, "schema": { "$ref": "#/components/schemas/Frequency" } }, { "name": "begin", "in": "query", "description": "The begin date (inclusive). If timezone information is not present in the formatted date time, then it will be parsed in the Curve's timezone", "required": true, "schema": { "type": "string", "format": "date-time" } }, { "name": "end", "in": "query", "description": "The end date (exclusive). If time zone information is not present in the formatted date time, then it will be parsed in the Curve's time zone.", "required": true, "schema": { "type": "string", "format": "date-time" } }, { "name": "delimiter", "in": "query", "description": "Only CSV: Delimiter for values. Possible values are `COMMA` (`a,b,c`) and `SEMICOLON` (`a;b;c`).", "schema": { "$ref": "#/components/schemas/Delimiter" } }, { "name": "decimal-separator", "in": "query", "description": "Only TSV and CSV: Decimal separator for numbers (`PERIOD` for 1.23 or `COMMA` for 1,23).", "schema": { "$ref": "#/components/schemas/DecimalSeparator" } }, { "name": "timezone", "in": "query", "description": "Convert data into given timezone.", "schema": { "$ref": "#/components/schemas/Timezone" } }, { "name": "unit", "in": "query", "description": "Convert data into given unit.", "schema": { "$ref": "#/components/schemas/Unit" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Timeseries" } }, "text/tab-separated-values": { "schema": { "type": "string" } }, "text/csv": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/AuthenticationError" }, "403": { "$ref": "#/components/responses/AccessDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/period-instances/{curve-name}/list/": { "get": { "tags": [ "Period series – instances" ], "summary": "List period-based instances", "description": "Lists the instance objects only (no period-based series data is loaded by this operation).\n\n**Note:** This operation works for curves with `curve_type = INSTANCE_PERIOD` only.\n", "parameters": [ { "name": "curve-name", "in": "path", "description": "An urlencoded *curve-name* (see Curve model).", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Maximum number of instances to fetch.", "schema": { "maximum": 20, "minimum": 1, "type": "number", "format": "int32", "default": 5 } }, { "name": "tags", "in": "query", "description": "Filter query to include instances with given tags.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "exclude-tags", "in": "query", "description": "Filter query to exclude instances with given tags.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "issued-at-earliest", "in": "query", "description": "The earliest issue date (inclusive).", "schema": { "type": "string", "format": "date-time" } }, { "name": "issued-at-latest", "in": "query", "description": "The latest issue date (inclusive).", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Instance" } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/AuthenticationError" }, "403": { "$ref": "#/components/responses/AccessDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/ohlc/{curve-name}/": { "get": { "tags": [ "Closing prices" ], "summary": "Load OHLC data", "description": "Load OHLC statistics for traded contracts between two specified dates. By default, this operation loads all available contracts (daily, weekly, monthly, quarterly, yearly etc.) for the interval.\n\nYou can filter the returned contracts by specifying a **period** and optionally one of: **delivery** or **front**.\n\nOHLC means *open*, *high*, *low*, *close*. This operation returns open, high, low, close, settlement, volume and open interest. Keep in mind that settlement is the only required field.\n\n**Note:** This operation works for curves with `curve_type = OHLC` only.\n", "parameters": [ { "name": "curve-name", "in": "path", "description": "An urlencoded *curve-name* (see Curve model).", "required": true, "schema": { "type": "string" } }, { "name": "begin", "in": "query", "description": "The begin trading date (inclusive).", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "end", "in": "query", "description": "The end trading date (exclusive).", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "period", "in": "query", "description": "Filter on contract period (yearly, quarterly, monthly)", "schema": { "$ref": "#/components/schemas/Period" } }, { "name": "delivery", "in": "query", "description": "Filter on a specific delivery date for the contract.\n\n * **May only be used** when the `period` parameter is set\n * **Cannot be used** in combination with the `front` parameter\n", "schema": { "type": "string", "format": "date" } }, { "name": "front", "in": "query", "description": "Filter on a specific front contract relative to each trading day.\n\n * **Cannot be used** in combination with the `delivery` parameter\n", "schema": { "maximum": 100, "minimum": 0, "type": "number", "format": "int32" } }, { "name": "unit", "in": "query", "description": "Convert data into given unit.", "schema": { "$ref": "#/components/schemas/Unit" } }, { "name": "delimiter", "in": "query", "description": "Only CSV: Delimiter for values. Possible values are `COMMA` (`a,b,c`) and `SEMICOLON` (`a;b;c`).", "schema": { "$ref": "#/components/schemas/Delimiter" } }, { "name": "decimal-separator", "in": "query", "description": "Only TSV and CSV: Decimal separator for numbers (`PERIOD` for 1.23 or `COMMA` for 1,23).", "schema": { "$ref": "#/components/schemas/DecimalSeparator" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "required": [ "curve", "unit", "denominator", "data" ], "type": "object", "properties": { "curve": { "$ref": "#/components/schemas/Curve" }, "unit": { "$ref": "#/components/schemas/Unit" }, "denominator": { "$ref": "#/components/schemas/Unit" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/OHLC" } } } } }, "text/tab-separated-values": { "schema": { "type": "string" } }, "text/csv": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/AuthenticationError" }, "403": { "$ref": "#/components/responses/AccessDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/ohlc/{curve-name}/timeseries/{field}/": { "get": { "tags": [ "Closing prices" ], "summary": "Load OHLC data as time series", "description": "Select a field (close, settlement etc.) and load data for that field as a time series. The resulting time series with have a **contract** attribute.\n\nYou **must** set the **period** parameter, and exactly one of the following parameters: **delivery** or **front**.\n\n**Note:** This operation works for curves with `curve_type = OHLC` only.\n", "parameters": [ { "name": "curve-name", "in": "path", "description": "An urlencoded *curve-name* (see Curve model).", "required": true, "schema": { "type": "string" } }, { "name": "field", "in": "path", "description": "The `OHLCField` to load when converting to a time series", "required": true, "schema": { "$ref": "#/components/schemas/OHLCField" } }, { "name": "period", "in": "query", "description": "Filter on contract period (yearly, quarterly, monthly)", "required": true, "schema": { "$ref": "#/components/schemas/Period" } }, { "name": "delivery", "in": "query", "description": "Filter on a specific delivery date for the contract.\n\n**Cannot be used** in combination with the `front` parameter\n", "schema": { "type": "string", "format": "date" } }, { "name": "front", "in": "query", "description": "Filter on a specific front contract relative to each trading day.\n\n**Cannot be used** in combination with the `delivery` parameter\n", "schema": { "maximum": 100, "minimum": 0, "type": "number", "format": "int32" } }, { "name": "begin", "in": "query", "description": "The begin trading date (inclusive).", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "end", "in": "query", "description": "The end trading date (exclusive).", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "fill", "in": "query", "description": "How to fill holes on days without any trades. Defaults to *no-fill*. Possible values are `no-fill`, `forward-fill` and `fill-holes`.\n", "schema": { "$ref": "#/components/schemas/Fill" } }, { "name": "unit", "in": "query", "description": "Convert data into given unit.", "schema": { "$ref": "#/components/schemas/Unit" } }, { "name": "delimiter", "in": "query", "description": "Only CSV: Delimiter for values. Possible values are `COMMA` (`a,b,c`) and `SEMICOLON` (`a;b;c`).", "schema": { "$ref": "#/components/schemas/Delimiter" } }, { "name": "decimal-separator", "in": "query", "description": "Only TSV and CSV: Decimal separator for numbers (`PERIOD` for 1.23 or `COMMA` for 1,23).", "schema": { "$ref": "#/components/schemas/DecimalSeparator" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Timeseries" } }, "text/tab-separated-values": { "schema": { "type": "string" } }, "text/csv": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/AuthenticationError" }, "403": { "$ref": "#/components/responses/AccessDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/ohlc/{curve-name}/latest/": { "get": { "tags": [ "Closing prices" ], "summary": "Load OHLC data for a trading day", "description": "Load OHLC statistics for traded contracts on the latest trading date. This operation loads all available contracts (daily, weekly, monthly, quarterly, yearly etc.).\n\nWhen **date** parameter is given, this operation will try to load OHLC data traded on that date. If **date** is on a weekend or is a holiday, this operation will return data for the most recent trading date before given date.\n\n**Note:** This operation works for curves with `curve_type = OHLC` only.\n", "parameters": [ { "name": "curve-name", "in": "path", "description": "An urlencoded *curve-name* (see Curve model).", "required": true, "schema": { "type": "string" } }, { "name": "date", "in": "query", "description": "The trading date (if on a weekend or holiday, then returning data for the most recent trading date before given date)", "schema": { "type": "string", "format": "date" } }, { "name": "unit", "in": "query", "description": "Convert data into given unit.", "schema": { "$ref": "#/components/schemas/Unit" } }, { "name": "delimiter", "in": "query", "description": "Only CSV: Delimiter for values. Possible values are `COMMA` (`a,b,c`) and `SEMICOLON` (`a;b;c`).", "schema": { "$ref": "#/components/schemas/Delimiter" } }, { "name": "decimal-separator", "in": "query", "description": "Only TSV and CSV: Decimal separator for numbers (`PERIOD` for 1.23 or `COMMA` for 1,23).", "schema": { "$ref": "#/components/schemas/DecimalSeparator" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "required": [ "curve", "unit", "denominator", "data" ], "type": "object", "properties": { "curve": { "$ref": "#/components/schemas/Curve" }, "unit": { "$ref": "#/components/schemas/Unit" }, "denominator": { "$ref": "#/components/schemas/Unit" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/OHLC" } } } } }, "text/tab-separated-values": { "schema": { "type": "string" } }, "text/csv": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/AuthenticationError" }, "403": { "$ref": "#/components/responses/AccessDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/ohlc/{curve-name}/latest/periods/{field}/": { "get": { "tags": [ "Closing prices" ], "summary": "Load OHLC data for a trading day, converted to a continuous period series", "description": "Load a field from OHLC statistics for traded contracts on the latest trading date. This operation loads all available contracts (daily, weekly, monthly, quarterly, yearly etc.), sorts them, and merges/converts them a continuous **period-based series**.\n\nWhen **date** parameter is given, this operation will try to load OHLC data traded on that date. If **date** is on a weekend or is a holiday, this operation will return data for the most recent trading date before given date.\n\n**Note:** This operation works for curves with `curve_type = OHLC` only.\n", "parameters": [ { "name": "curve-name", "in": "path", "description": "An urlencoded *curve-name* (see Curve model).", "required": true, "schema": { "type": "string" } }, { "name": "field", "in": "path", "description": "The `OHLCField` to load when converting to a time series", "required": true, "schema": { "$ref": "#/components/schemas/OHLCField" } }, { "name": "date", "in": "query", "description": "The trading date (if on a weekend or holiday, then returning data for the most recent trading date before given date)", "schema": { "type": "string", "format": "date" } }, { "name": "timezone", "in": "query", "description": "Convert data into given timezone.", "schema": { "$ref": "#/components/schemas/Timezone" } }, { "name": "unit", "in": "query", "description": "Convert data into given unit.", "schema": { "$ref": "#/components/schemas/Unit" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Periodseries" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/AuthenticationError" }, "403": { "$ref": "#/components/responses/AccessDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/ohlc/{curve-name}/latest/timeseries/{field}/": { "get": { "tags": [ "Closing prices" ], "summary": "Load OHLC data for a trading day, converted to a continuous time series", "description": "Load a field from OHLC statistics for traded contracts on the latest trading date. This operation loads all available contracts (daily, weekly, monthly, quarterly, yearly etc.), sorts them, and merges/converts them a continuous **time series**.\n\nWhen **date** parameter is given, this operation will try to load OHLC data traded on that date. If **date** is on a weekend or is a holiday, this operation will return data for the most recent trading date before given date.\n\n**Note:** This operation works for curves with `curve_type = OHLC` only.\n", "parameters": [ { "name": "curve-name", "in": "path", "description": "An urlencoded *curve-name* (see Curve model).", "required": true, "schema": { "type": "string" } }, { "name": "field", "in": "path", "description": "The `OHLCField` to load when converting to a time series", "required": true, "schema": { "$ref": "#/components/schemas/OHLCField" } }, { "name": "frequency", "in": "query", "description": "The frequency of the output time series", "required": true, "schema": { "allOf": [ { "$ref": "#/components/schemas/Frequency" }, { "default": "P1W" } ] } }, { "name": "date", "in": "query", "description": "The trading date (if on a weekend or holiday, then returning data for the most recent trading date before given date)", "schema": { "type": "string", "format": "date" } }, { "name": "timezone", "in": "query", "description": "Convert data into given timezone.", "schema": { "$ref": "#/components/schemas/Timezone" } }, { "name": "unit", "in": "query", "description": "Convert data into given unit.", "schema": { "$ref": "#/components/schemas/Unit" } }, { "name": "delimiter", "in": "query", "description": "Only CSV: Delimiter for values. Possible values are `COMMA` (`a,b,c`) and `SEMICOLON` (`a;b;c`).", "schema": { "$ref": "#/components/schemas/Delimiter" } }, { "name": "decimal-separator", "in": "query", "description": "Only TSV and CSV: Decimal separator for numbers (`PERIOD` for 1.23 or `COMMA` for 1,23).", "schema": { "$ref": "#/components/schemas/DecimalSeparator" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Timeseries" } }, "text/tab-separated-values": { "schema": { "type": "string" } }, "text/csv": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/AuthenticationError" }, "403": { "$ref": "#/components/responses/AccessDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/trades/{curve-name}/contracts/": { "get": { "tags": [ "Trades" ], "summary": "List trade contracts", "description": "Lists trade contracts whose delivery start is between `begin` (inclusive) and `end` (exclusive).\n\nThe interval from `begin` to `end` cannot exceed one week. Contracts are grouped by period and ordered by delivery start within each period.\n", "parameters": [ { "$ref": "#/components/parameters/TradeCurveName" }, { "$ref": "#/components/parameters/TradeBegin" }, { "$ref": "#/components/parameters/TradeEnd" }, { "$ref": "#/components/parameters/TradeAfterTimeOfDay" }, { "$ref": "#/components/parameters/TradeBeforeTimeOfDay" }, { "$ref": "#/components/parameters/TradePeriods" }, { "$ref": "#/components/parameters/TradeExcludePeriods" } ], "responses": { "200": { "description": "Matching trade contracts", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TradeContract" } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/AuthenticationError" }, "403": { "$ref": "#/components/responses/AccessDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/trades/{curve-name}/ohlc/": { "get": { "tags": [ "Trades" ], "summary": "Load trade OHLC data for multiple contracts", "description": "Loads trade OHLC data for contracts whose delivery start is between `begin` (inclusive) and `end` (exclusive).\n\nThe interval from `begin` to `end` cannot exceed one week. Contracts are grouped by period and ordered by delivery start within each period.\n\nBy default, the stored `PT1M` trade data is returned without aggregation. Set `frequency` to aggregate the trade data into buckets aligned backwards from `delivery - min-lead-time` for each contract. With the default `min-lead-time=PT0S`, delivery itself is the anchor. For example, delivery at 12:45 with `frequency=PT1H&min-lead-time=PT15M` produces a final bucket of `[11:30, 12:30)`. Alternatively, set `aggregate-by-contract=true` to return one OHLC value per contract. These two aggregation parameters cannot be used together.\n\nBy default, values from up to 36 hours before delivery are included. Use `min-lead-time` and `max-lead-time` to select a smaller trading-time window.\n", "parameters": [ { "$ref": "#/components/parameters/TradeCurveName" }, { "$ref": "#/components/parameters/TradeBegin" }, { "$ref": "#/components/parameters/TradeEnd" }, { "$ref": "#/components/parameters/TradeAfterTimeOfDay" }, { "$ref": "#/components/parameters/TradeBeforeTimeOfDay" }, { "$ref": "#/components/parameters/TradePeriods" }, { "$ref": "#/components/parameters/TradeExcludePeriods" }, { "name": "frequency", "in": "query", "description": "Aggregate trade data to this frequency. It must be between `PT1M` and `PT1H`, inclusive. Cannot be combined with `aggregate-by-contract=true`.", "schema": { "$ref": "#/components/schemas/Frequency" } }, { "name": "aggregate-by-contract", "in": "query", "description": "Aggregate all trade data selected by the lead-time window for each contract into one OHLC value. Cannot be combined with `frequency`.", "schema": { "type": "boolean", "default": false } }, { "$ref": "#/components/parameters/TradeMinLeadTime" }, { "$ref": "#/components/parameters/TradeMaxLeadTime" }, { "name": "unit", "in": "query", "description": "Convert prices into the given unit.", "schema": { "$ref": "#/components/schemas/Unit" } }, { "name": "delimiter", "in": "query", "description": "Only CSV: Delimiter for values. Possible values are `COMMA` (`a,b,c`) and `SEMICOLON` (`a;b;c`).", "schema": { "$ref": "#/components/schemas/Delimiter" } }, { "name": "decimal-separator", "in": "query", "description": "Only TSV and CSV: Decimal separator for numbers (`PERIOD` for 1.23 or `COMMA` for 1,23).", "schema": { "$ref": "#/components/schemas/DecimalSeparator" } } ], "responses": { "200": { "description": "Trade OHLC series for the matching contracts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TradeOHLCResponse" } }, "text/tab-separated-values": { "schema": { "type": "string" } }, "text/csv": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/AuthenticationError" }, "403": { "$ref": "#/components/responses/AccessDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/srmc/{curve-name}/": { "get": { "tags": [ "SRMC" ], "summary": "Calculate SRMC from OHLC data", "description": "Calculate SRMC from OHLC statistics for traded contracts between two specified dates.\n\nYou can filter the returned contracts by specifying a **period** and optionally one of: **delivery** or **front**.\n\n**Note:** This operation works for **gas** and **coal** curves with `curve_type = OHLC` only.\n", "parameters": [ { "name": "curve-name", "in": "path", "description": "An urlencoded *curve-name* (see Curve model).", "required": true, "schema": { "type": "string" } }, { "name": "begin", "in": "query", "description": "The begin trading date (inclusive).", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "end", "in": "query", "description": "The end trading date (exclusive).", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "period", "in": "query", "description": "Filter on contract period (yearly, quarterly, monthly)", "schema": { "$ref": "#/components/schemas/Period" } }, { "name": "delivery", "in": "query", "description": "Filter on a specific delivery date for the contract.\n\n * **May only be used** when the `period` parameter is set\n * **Cannot be used** in combination with the `front` parameter.\n", "schema": { "type": "string", "format": "date" } }, { "name": "front", "in": "query", "description": "Filter on a specific front contract relative to each trading day.\n\n * **Cannot be used** in combination with the `delivery` parameter\n", "schema": { "maximum": 100, "minimum": 0, "type": "number", "format": "int32" } }, { "name": "gas-therm-to-mwh", "in": "query", "description": "Conversion from pence/therm to GBP/MWh. This value defaults to 0.029307.\n", "schema": { "type": "number", "format": "double" } }, { "name": "api2-tonne-to-mwh", "in": "query", "description": "Conversion from API2 coal to MWh. Defaults to 6.978.\n", "schema": { "type": "number", "format": "double" } }, { "name": "carbon-emissions", "in": "query", "description": "The carbon content as tCO2/MWh. This value varies between coal and gas.\nFor coal, the default factor is 0.34056. For gas, the default factor is 0.18404.\n", "schema": { "type": "number", "format": "double" } }, { "name": "efficiency", "in": "query", "description": "The energy efficiency. For coal, the default factor is 0.42. For gas, the\ndefault factor is 0.55.\n", "schema": { "type": "number", "format": "double" } }, { "name": "carbon-tax-area", "in": "query", "description": "Provide an area, such as ``GB``, for including local carbon tax. This\nis very handy for calculating carbon tax in, i.e., Great Britain.\n", "schema": { "type": "string" } }, { "name": "unit", "in": "query", "description": "Convert data into given unit.", "schema": { "$ref": "#/components/schemas/Unit" } }, { "name": "delimiter", "in": "query", "description": "Only CSV: Delimiter for values. Possible values are `COMMA` (`a,b,c`) and `SEMICOLON` (`a;b;c`).", "schema": { "$ref": "#/components/schemas/Delimiter" } }, { "name": "decimal-separator", "in": "query", "description": "Only TSV and CSV: Decimal separator for numbers (`PERIOD` for 1.23 or `COMMA` for 1,23).", "schema": { "$ref": "#/components/schemas/DecimalSeparator" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "required": [ "curve", "srmc_options", "unit", "denominator", "ohlc" ], "type": "object", "properties": { "curve": { "$ref": "#/components/schemas/Curve" }, "contract": { "$ref": "#/components/schemas/Contract" }, "srmc_options": { "$ref": "#/components/schemas/SRMCOptions" }, "unit": { "$ref": "#/components/schemas/Unit" }, "denominator": { "$ref": "#/components/schemas/Unit" }, "ohlc": { "type": "array", "items": { "$ref": "#/components/schemas/OHLC" } } } } }, "text/tab-separated-values": { "schema": { "type": "string" } }, "text/csv": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/AuthenticationError" }, "403": { "$ref": "#/components/responses/AccessDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/srmc/{curve-name}/timeseries/": { "get": { "tags": [ "SRMC" ], "summary": "Calculate SRMC from OHLC data – converted to time series", "description": "Calculate SRMC from OHLC statistics for traded contracts between two specified dates. Converts the result to a daily time series.\n\nYou **must** filter the returned contracts by specifying a **period** and *exactly* one of: **delivery** or **front**.\n\n**Note:** This operation works for **gas** and **coal** curves with `curve_type = OHLC` only.\n", "parameters": [ { "name": "curve-name", "in": "path", "description": "An urlencoded *curve-name* (see Curve model).", "required": true, "schema": { "type": "string" } }, { "name": "begin", "in": "query", "description": "The begin trading date (inclusive).", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "end", "in": "query", "description": "The end trading date (exclusive).", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "period", "in": "query", "description": "Filter on contract period (yearly, quarterly, monthly)", "required": true, "schema": { "$ref": "#/components/schemas/Period" } }, { "name": "delivery", "in": "query", "description": "Filter on a specific delivery date for the contract.\n\n**Cannot be used** in combination with the `front` parameter.\n", "schema": { "type": "string", "format": "date" } }, { "name": "front", "in": "query", "description": "Filter on a specific front contract relative to each trading day.\n\n**Cannot be used** in combination with the `delivery` parameter.\n", "schema": { "maximum": 100, "minimum": 0, "type": "number", "format": "int32" } }, { "name": "fill", "in": "query", "description": "How to fill holes on days without any trades. Defaults to *no-fill*. Possible values are `no-fill`, `forward-fill` and `fill-holes`.\n", "schema": { "$ref": "#/components/schemas/Fill" } }, { "name": "gas-therm-to-mwh", "in": "query", "description": "Conversion from pence/therm to GBP/MWh. This value defaults to 0.029307.\n", "schema": { "type": "number", "format": "double" } }, { "name": "api2-tonne-to-mwh", "in": "query", "description": "Conversion from API2 coal to MWh. Defaults to 6.978.\n", "schema": { "type": "number", "format": "double" } }, { "name": "carbon-emissions", "in": "query", "description": "The carbon content as tCO2/MWh. This value varies between coal and gas.\nFor coal, the default factor is 0.34056. For gas, the default factor is 0.18404.\n", "schema": { "type": "number", "format": "double" } }, { "name": "efficiency", "in": "query", "description": "The energy efficiency. For coal, the default factor is 0.42. For gas, the\ndefault factor is 0.55.\n", "schema": { "type": "number", "format": "double" } }, { "name": "carbon-tax-area", "in": "query", "description": "Provide an area, such as ``GB``, for including local carbon tax. This\nis very handy for calculating carbon tax in, i.e., Great Britain.\n", "schema": { "type": "string" } }, { "name": "unit", "in": "query", "description": "Convert data into given unit.", "schema": { "$ref": "#/components/schemas/Unit" } }, { "name": "delimiter", "in": "query", "description": "Only CSV: Delimiter for values. Possible values are `COMMA` (`a,b,c`) and `SEMICOLON` (`a;b;c`).", "schema": { "$ref": "#/components/schemas/Delimiter" } }, { "name": "decimal-separator", "in": "query", "description": "Only TSV and CSV: Decimal separator for numbers (`PERIOD` for 1.23 or `COMMA` for 1,23).", "schema": { "$ref": "#/components/schemas/DecimalSeparator" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "required": [ "curve", "srmc_options", "unit", "denominator", "timeseries" ], "type": "object", "properties": { "curve": { "$ref": "#/components/schemas/Curve" }, "contract": { "$ref": "#/components/schemas/Contract" }, "srmc_options": { "$ref": "#/components/schemas/SRMCOptions" }, "unit": { "$ref": "#/components/schemas/Unit" }, "denominator": { "$ref": "#/components/schemas/Unit" }, "timeseries": { "$ref": "#/components/schemas/Timeseries" } } } }, "text/tab-separated-values": { "schema": { "type": "string" } }, "text/csv": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/AuthenticationError" }, "403": { "$ref": "#/components/responses/AccessDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/srmc/{curve-name}/latest/": { "get": { "tags": [ "SRMC" ], "summary": "Calculate SRMC for all contracts for a trading day", "description": "Calculate SRMC from OHLC statistics for traded contracts on the latest trading date. This operation calculates SRMC for all available contracts (daily, weekly, monthly, quarterly, yearly etc.).\n\nWhen **date** parameter is given, this operation will try to load OHLC data traded on that date. If **date** is on a weekend or is a holiday, this operation will return data for the most recent trading date before given date.\n\n**Note:** This operation works for **gas** and **coal** curves with `curve_type = OHLC` only.\n", "parameters": [ { "name": "curve-name", "in": "path", "description": "An urlencoded *curve-name* (see Curve model).", "required": true, "schema": { "type": "string" } }, { "name": "date", "in": "query", "description": "The trading date (if on a weekend or holiday, then returning data for the most recent trading date before given date).", "schema": { "type": "string", "format": "date" } }, { "name": "gas-therm-to-mwh", "in": "query", "description": "Conversion from pence/therm to GBP/MWh. This value defaults to 0.029307.\n", "schema": { "type": "number", "format": "double" } }, { "name": "api2-tonne-to-mwh", "in": "query", "description": "Conversion from API2 coal to MWh. Defaults to 6.978.\n", "schema": { "type": "number", "format": "double" } }, { "name": "carbon-emissions", "in": "query", "description": "The carbon content as tCO2/MWh. This value varies between coal and gas.\nFor coal, the default factor is 0.34056. For gas, the default factor is 0.18404.\n", "schema": { "type": "number", "format": "double" } }, { "name": "efficiency", "in": "query", "description": "The energy efficiency. For coal, the default factor is 0.42. For gas, the\ndefault factor is 0.55.\n", "schema": { "type": "number", "format": "double" } }, { "name": "carbon-tax-area", "in": "query", "description": "Provide an area, such as ``GB``, for including local carbon tax. This\nis very handy for calculating carbon tax in, i.e., Great Britain.\n", "schema": { "type": "string" } }, { "name": "unit", "in": "query", "description": "Convert data into given unit.", "schema": { "$ref": "#/components/schemas/Unit" } }, { "name": "delimiter", "in": "query", "description": "Only CSV: Delimiter for values. Possible values are `COMMA` (`a,b,c`) and `SEMICOLON` (`a;b;c`).", "schema": { "$ref": "#/components/schemas/Delimiter" } }, { "name": "decimal-separator", "in": "query", "description": "Only TSV and CSV: Decimal separator for numbers (`PERIOD` for 1.23 or `COMMA` for 1,23).", "schema": { "$ref": "#/components/schemas/DecimalSeparator" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "required": [ "curve", "srmc_options", "unit", "denominator", "ohlc" ], "type": "object", "properties": { "curve": { "$ref": "#/components/schemas/Curve" }, "srmc_options": { "$ref": "#/components/schemas/SRMCOptions" }, "unit": { "$ref": "#/components/schemas/Unit" }, "denominator": { "$ref": "#/components/schemas/Unit" }, "ohlc": { "type": "array", "items": { "$ref": "#/components/schemas/OHLC" } } } } }, "text/tab-separated-values": { "schema": { "type": "string" } }, "text/csv": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/AuthenticationError" }, "403": { "$ref": "#/components/responses/AccessDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/srmc/{curve-name}/latest/periods/": { "get": { "tags": [ "SRMC" ], "summary": "Calculate SRMC for all contracts for a trading day converted to periods", "description": "Calculates SRMC for all available contracts on the latest trading date (daily, weekly, monthly, quarterly, yearly etc.), sorts them, and merges/converts them a continuous **period-based series**.\n\nWhen **date** parameter is given, this operation will try to load OHLC data traded on that date. If **date** is on a weekend or is a holiday, this operation will return data for the most recent trading date before given date.\n\n**Note:** This operation works for **gas** and **coal** curves with `curve_type = OHLC` only.\n", "parameters": [ { "name": "curve-name", "in": "path", "description": "An urlencoded *curve-name* (see Curve model).", "required": true, "schema": { "type": "string" } }, { "name": "date", "in": "query", "description": "The trading date (if on a weekend or holiday, then returning data for the most recent trading date before given date)", "schema": { "type": "string", "format": "date" } }, { "name": "gas-therm-to-mwh", "in": "query", "description": "Conversion from pence/therm to GBP/MWh. This value defaults to 0.029307.\n", "schema": { "type": "number", "format": "double" } }, { "name": "api2-tonne-to-mwh", "in": "query", "description": "Conversion from API2 coal to MWh. Defaults to 6.978.\n", "schema": { "type": "number", "format": "double" } }, { "name": "carbon-emissions", "in": "query", "description": "The carbon content as tCO2/MWh. This value varies between coal and gas.\nFor coal, the default factor is 0.34056. For gas, the default factor is 0.18404.\n", "schema": { "type": "number", "format": "double" } }, { "name": "efficiency", "in": "query", "description": "The energy efficiency. For coal, the default factor is 0.42. For gas, the\ndefault factor is 0.55.\n", "schema": { "type": "number", "format": "double" } }, { "name": "carbon-tax-area", "in": "query", "description": "Provide an area, such as ``GB``, for including local carbon tax. This\nis very handy for calculating carbon tax in, i.e., Great Britain.\n", "schema": { "type": "string" } }, { "name": "timezone", "in": "query", "description": "Convert data into given timezone.", "schema": { "$ref": "#/components/schemas/Timezone" } }, { "name": "unit", "in": "query", "description": "Convert data into given unit.", "schema": { "$ref": "#/components/schemas/Unit" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "required": [ "curve", "srmc_options", "unit", "denominator", "periodseries" ], "type": "object", "properties": { "curve": { "$ref": "#/components/schemas/Curve" }, "srmc_options": { "$ref": "#/components/schemas/SRMCOptions" }, "unit": { "$ref": "#/components/schemas/Unit" }, "denominator": { "$ref": "#/components/schemas/Unit" }, "periodseries": { "$ref": "#/components/schemas/Periodseries" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/AuthenticationError" }, "403": { "$ref": "#/components/responses/AccessDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/srmc/{curve-name}/latest/timeseries/": { "get": { "tags": [ "SRMC" ], "summary": "Calculate SRMC for all contracts for a trading day converted to a time series", "description": "Calculates SRMC for all available contracts on the latest trading date (daily, weekly, monthly, quarterly, yearly etc.), sorts them, and merges/converts them a continuous **time series**.\n\nWhen **date** parameter is given, this operation will try to load OHLC data traded on that date. If **date** is on a weekend or is a holiday, this operation will return data for the most recent trading date before given date.\n\n**Note:** This operation works for **gas** and **coal** curves with `curve_type = OHLC` only.\n", "parameters": [ { "name": "curve-name", "in": "path", "description": "An urlencoded *curve-name* (see Curve model).", "required": true, "schema": { "type": "string" } }, { "name": "date", "in": "query", "description": "The trading date (if on a weekend or holiday, then returning data for the most recent trading date before given date)", "schema": { "type": "string", "format": "date" } }, { "name": "frequency", "in": "query", "description": "The frequency of the output time series", "required": true, "schema": { "$ref": "#/components/schemas/Frequency" } }, { "name": "gas-therm-to-mwh", "in": "query", "description": "Conversion from pence/therm to GBP/MWh. This value defaults to 0.029307.\n", "schema": { "type": "number", "format": "double" } }, { "name": "api2-tonne-to-mwh", "in": "query", "description": "Conversion from API2 coal to MWh. Defaults to 6.978.\n", "schema": { "type": "number", "format": "double" } }, { "name": "carbon-emissions", "in": "query", "description": "The carbon content as tCO2/MWh. This value varies between coal and gas.\nFor coal, the default factor is 0.34056. For gas, the default factor is 0.18404.\n", "schema": { "type": "number", "format": "double" } }, { "name": "efficiency", "in": "query", "description": "The energy efficiency. For coal, the default factor is 0.42. For gas, the\ndefault factor is 0.55.\n", "schema": { "type": "number", "format": "double" } }, { "name": "carbon-tax-area", "in": "query", "description": "Provide an area, such as ``GB``, for including local carbon tax. This\nis very handy for calculating carbon tax in, i.e., Great Britain.\n", "schema": { "type": "string" } }, { "name": "delimiter", "in": "query", "description": "Only CSV: Delimiter for values. Possible values are `COMMA` (`a,b,c`) and `SEMICOLON` (`a;b;c`).", "schema": { "$ref": "#/components/schemas/Delimiter" } }, { "name": "decimal-separator", "in": "query", "description": "Only TSV and CSV: Decimal separator for numbers (`PERIOD` for 1.23 or `COMMA` for 1,23).", "schema": { "$ref": "#/components/schemas/DecimalSeparator" } }, { "name": "timezone", "in": "query", "description": "Convert data into given timezone.", "schema": { "$ref": "#/components/schemas/Timezone" } }, { "name": "unit", "in": "query", "description": "Convert data into given unit.", "schema": { "$ref": "#/components/schemas/Unit" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "required": [ "curve", "srmc_options", "unit", "denominator", "timeseries" ], "type": "object", "properties": { "curve": { "$ref": "#/components/schemas/Curve" }, "srmc_options": { "$ref": "#/components/schemas/SRMCOptions" }, "unit": { "$ref": "#/components/schemas/Unit" }, "denominator": { "$ref": "#/components/schemas/Unit" }, "timeseries": { "$ref": "#/components/schemas/Timeseries" } } } }, "text/tab-separated-values": { "schema": { "type": "string" } }, "text/csv": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/AuthenticationError" }, "403": { "$ref": "#/components/responses/AccessDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/ppa/{curve-name}/": { "get": { "tags": [ "PPA" ], "summary": "Load PPA data", "description": "Load Power Purchase Agreement (PPA) price data for traded products between two specified quote dates.\n\nA PPA data point is identified by its quote **date**, together with the product it quotes a price for: **technology**, **contract structure**, delivery start date and duration.\n\nYou can narrow the returned data by filtering on **technology**, **contract-structure**, **delivery-begin** and/or **duration**. When multiple values are given for **technology**, **contract-structure** or **duration**, a PPA matches if it has any of the given values for that filter. All given filters must match (logical AND across filters, logical OR within repeated values of the same filter).\n\n**Note:** This operation works for curves with `curve_type = PPA` only.\n", "parameters": [ { "name": "curve-name", "in": "path", "description": "An urlencoded *curve-name* (see Curve model).", "required": true, "schema": { "type": "string" } }, { "name": "begin", "in": "query", "description": "The begin quote date (inclusive).", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "end", "in": "query", "description": "The end quote date (exclusive).", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "technology", "in": "query", "description": "Filter by one or more generation technologies.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Technology" } } }, { "name": "contract-structure", "in": "query", "description": "Filter by one or more contract structures.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ContractStructure" } } }, { "name": "delivery-begin", "in": "query", "description": "Filter by a specific delivery start date.", "schema": { "type": "string", "format": "date" } }, { "name": "duration", "in": "query", "description": "Filter by one or more contract durations, in years.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PPADuration" } } }, { "name": "unit", "in": "query", "description": "Convert data into given unit.", "schema": { "$ref": "#/components/schemas/Unit" } }, { "name": "delimiter", "in": "query", "description": "Only CSV: Delimiter for values. Possible values are `COMMA` (`a,b,c`) and `SEMICOLON` (`a;b;c`).", "schema": { "$ref": "#/components/schemas/Delimiter" } }, { "name": "decimal-separator", "in": "query", "description": "Only TSV and CSV: Decimal separator for numbers (`PERIOD` for 1.23 or `COMMA` for 1,23).", "schema": { "$ref": "#/components/schemas/DecimalSeparator" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "required": [ "curve", "unit", "denominator", "data" ], "type": "object", "properties": { "curve": { "$ref": "#/components/schemas/Curve" }, "unit": { "$ref": "#/components/schemas/Unit" }, "denominator": { "$ref": "#/components/schemas/Unit" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/PPA" } } } } }, "text/tab-separated-values": { "schema": { "type": "string" } }, "text/csv": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/AuthenticationError" }, "403": { "$ref": "#/components/responses/AccessDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/ppa/{curve-name}/latest/": { "get": { "tags": [ "PPA" ], "summary": "Load PPA data for the latest quote date", "description": "Load PPA price data for the latest available quote date. This operation returns every PPA product quoted on that date.\n\nWhen the **date** parameter is given, this operation will try to load PPA data quoted on that date. If no data exists on the exact date, this operation returns data for the most recent quote date before the given date.\n\nThe same filters as for the non-latest operation apply: **technology**, **contract-structure**, **delivery-begin** and **duration**.\n\n**Note:** This operation works for curves with `curve_type = PPA` only.\n", "parameters": [ { "name": "curve-name", "in": "path", "description": "An urlencoded *curve-name* (see Curve model).", "required": true, "schema": { "type": "string" } }, { "name": "date", "in": "query", "description": "The latest quote date (if no data exists on the exact date, returns data for the most recent quote date before the given date).", "schema": { "type": "string", "format": "date" } }, { "name": "technology", "in": "query", "description": "Filter by one or more generation technologies.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Technology" } } }, { "name": "contract-structure", "in": "query", "description": "Filter by one or more contract structures.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ContractStructure" } } }, { "name": "delivery-begin", "in": "query", "description": "Filter by a specific delivery start date.", "schema": { "type": "string", "format": "date" } }, { "name": "duration", "in": "query", "description": "Filter by one or more contract durations, in years.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PPADuration" } } }, { "name": "unit", "in": "query", "description": "Convert data into given unit.", "schema": { "$ref": "#/components/schemas/Unit" } }, { "name": "delimiter", "in": "query", "description": "Only CSV: Delimiter for values. Possible values are `COMMA` (`a,b,c`) and `SEMICOLON` (`a;b;c`).", "schema": { "$ref": "#/components/schemas/Delimiter" } }, { "name": "decimal-separator", "in": "query", "description": "Only TSV and CSV: Decimal separator for numbers (`PERIOD` for 1.23 or `COMMA` for 1,23).", "schema": { "$ref": "#/components/schemas/DecimalSeparator" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "required": [ "curve", "unit", "denominator", "data" ], "type": "object", "properties": { "curve": { "$ref": "#/components/schemas/Curve" }, "unit": { "$ref": "#/components/schemas/Unit" }, "denominator": { "$ref": "#/components/schemas/Unit" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/PPA" } } } } }, "text/tab-separated-values": { "schema": { "type": "string" } }, "text/csv": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/AuthenticationError" }, "403": { "$ref": "#/components/responses/AccessDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/collections/": { "get": { "tags": [ "Collections" ], "summary": "List collections with private curves", "description": "List collections with the corresponding permissions and private curves.\n\nUsers do not have any collections with private curves, unless you have ordered local forecasts or some ad-hoc data analysis or delivery.\n\nLoad the data from the curves using the operations you would normally use, such as `/timeseries/{curve-name}`, `/instances/{curve-name}/*` etc.\n", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Collection" } } } } }, "401": { "$ref": "#/components/responses/AuthenticationError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/carbon/calculate/{area}/": { "get": { "tags": [ "Carbon" ], "summary": "Calculate carbon emissions", "description": "Calculate your carbon emissions from your electricity consumption.\n", "parameters": [ { "name": "area", "in": "path", "description": "A tag representing an area (country, price area or region). Examples: DE, DK, DK1, DK2, NP, IT, IT-NORD etc.\n\nCarbon intensity data must be available for this area in order to calculate carbon emissions.\n", "required": true, "schema": { "type": "string" } }, { "name": "emission-type", "in": "query", "description": "The type of carbon emissions.", "schema": { "$ref": "#/components/schemas/EmissionType" } }, { "name": "profile", "in": "query", "required": true, "description": "The consumption profile.", "schema": { "$ref": "#/components/schemas/ConsumptionProfile" } }, { "name": "consumption", "in": "query", "required": true, "description": "The total consumption in MWh or kWh.", "schema": { "type": "number", "format": "double", "minimum": 0 } }, { "name": "unit", "in": "query", "description": "The unit of the total consumption. Available values: `MWH` and `kWh`.\n\n**Note**: The selection influences the unit of the response. If `MWh` is selected, the results will be in `kgCO2eq`, while if `kWh` is selected, the results will be in `gCO2eq`.\n", "schema": { "type": "string", "default": "MWh", "enum": [ "kWh", "MWh" ] } }, { "name": "begin", "in": "query", "description": "The begin of the consumption. Must be earliest at 2019-01-01.\n", "required": true, "schema": { "type": "string", "format": "date-time" } }, { "name": "end", "in": "query", "description": "The end of the consumption. Must be after `begin` and before the latest available data (which is normally today).\n", "required": true, "schema": { "type": "string", "format": "date-time" } }, { "name": "frequency", "in": "query", "description": "The frequency of the output time series", "schema": { "$ref": "#/components/schemas/Frequency" } }, { "name": "timezone", "in": "query", "description": "Convert data into given timezone.", "schema": { "$ref": "#/components/schemas/Timezone" } }, { "name": "delimiter", "in": "query", "description": "Only CSV: Delimiter for values. Possible values are `COMMA` (`a,b,c`) and `SEMICOLON` (`a;b;c`).", "schema": { "$ref": "#/components/schemas/Delimiter" } }, { "name": "decimal-separator", "in": "query", "description": "Only TSV and CSV: Decimal separator for numbers (`PERIOD` for 1.23 or `COMMA` for 1,23).", "schema": { "$ref": "#/components/schemas/DecimalSeparator" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "required": [ "parameters", "metadata", "carbon_emissions", "carbon_intensity", "consumption" ], "type": "object", "properties": { "parameters": { "description": "The parameters as given by the user to calculate carbon emissions.\n", "required": [ "area", "emission_type", "profile", "consumption", "begin", "end" ], "type": "object", "properties": { "area": { "type": "string" }, "emission_type": { "$ref": "#/components/schemas/EmissionType" }, "profile": { "$ref": "#/components/schemas/ConsumptionProfile" }, "consumption": { "type": "number", "format": "double", "minimum": 0 }, "unit": { "type": "string", "default": "MWh", "enum": [ "kWh", "MWh" ] }, "frequency": { "$ref": "#/components/schemas/Frequency" }, "zone": { "$ref": "#/components/schemas/Timezone" }, "begin": { "type": "string", "format": "date-time" }, "end": { "type": "string", "format": "date-time" } } }, "access": { "$ref": "#/components/schemas/Subscription" }, "metadata": { "required": [ "consumption", "begin", "end" ], "type": "object", "properties": { "consumption": { "description": "The total consumption. It might be different to the `consumption` parameter due to adjusted `begin` and `end`.\n", "type": "number", "format": "double", "minimum": 0 }, "begin": { "description": "The begin of consumption. Might be adjusted due to access restrictions and data availability.\n", "type": "string", "format": "date-time" }, "end": { "description": "The end of consumption. Might be adjusted due to access restrictions and data availability.\n", "type": "string", "format": "date-time" }, "resolution": { "$ref": "#/components/schemas/Resolution" } } }, "carbon_emissions": { "$ref": "#/components/schemas/Timeseries" }, "carbon_intensity": { "$ref": "#/components/schemas/Timeseries" }, "consumption": { "$ref": "#/components/schemas/Timeseries" } } } }, "text/tab-separated-values": { "schema": { "type": "string" } }, "text/csv": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/AuthenticationError" }, "403": { "$ref": "#/components/responses/AccessDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "tags": [ "Carbon" ], "summary": "Calculate carbon emissions", "description": "Calculate your carbon emissions from your electricity consumption.\n\nThis operation allows you to calculate carbon emissions from your own consumption data.\n", "parameters": [ { "name": "area", "in": "path", "description": "A tag representing an area (country, price area or region). Examples: DE, DK, DK1, DK2, NP, IT, IT-NORD etc.\n\nCarbon intensity data must be available for this area in order to calculate carbon emissions.\n", "required": true, "schema": { "type": "string" } }, { "name": "emission-type", "in": "query", "description": "The type of carbon emissions.", "schema": { "$ref": "#/components/schemas/EmissionType" } }, { "name": "unit", "in": "query", "description": "The unit of the consumption. Available values: `MWh` and `kWh`.\n\n**Note**: The selection influences the unit of the response. If `MWh` is selected, the results will be in `kgCO2eq`, while if `kWh` is selected, the results will be in `gCO2eq`.\n", "schema": { "type": "string", "default": "MWh", "enum": [ "kWh", "MWh" ] } }, { "name": "frequency", "in": "query", "description": "The frequency of the output time series.\n\n**Note**: If no frequency is given, the frequency of the input consumption data is used.\n", "schema": { "$ref": "#/components/schemas/Frequency" } }, { "name": "timezone", "in": "query", "description": "Convert data into given timezone. If no timezone is given, the timezone of the input consumption data is used. If the input data has no timezone, the timezone UTC is used.", "schema": { "$ref": "#/components/schemas/Timezone" } }, { "name": "input-frequency", "in": "query", "required": true, "description": "The frequency of the input time series. Available values: `PT15M`, `PT30M`, `PT1H`, `P1D`, `P1W`, `P1M`.\n", "schema": { "$ref": "#/components/schemas/Frequency" } }, { "name": "input-timezone", "in": "query", "required": true, "description": "The timezone of the input data.\n", "schema": { "$ref": "#/components/schemas/Timezone" } }, { "name": "fill", "in": "query", "description": "Filling method for missing consumption data. Defaults to `no-fill`.", "schema": { "$ref": "#/components/schemas/Fill" } }, { "name": "fill-value", "in": "query", "description": "If filling method is `value-fill`, this is the value to fill with.", "schema": { "type": "number", "format": "double", "minimum": 0 } }, { "name": "has-header-row", "in": "query", "description": "Only CSV and TSV: If the input data has a header row. Defaults to `true`.", "schema": { "type": "boolean", "default": true } }, { "name": "delimiter", "in": "query", "description": "Only CSV: Delimiter for values. Possible values are `COMMA` ('a,b,c') and `SEMICOLON` ('a;b;c').", "schema": { "$ref": "#/components/schemas/Delimiter" } }, { "name": "decimal-separator", "in": "query", "description": "Only TSV and CSV: Decimal separator for numbers (`PERIOD` for 1.23 or `COMMA` for 1,23).", "schema": { "$ref": "#/components/schemas/DecimalSeparator" } } ], "requestBody": { "description": "Your power consumption data. A CSV or TSV with the two columns (rows can be named whatever you like):\n\n 1. `timestamp` – The timestamp in ISO-8601 format. The format depends on the selected `input-frequency`. Supported formats are a year-month (e.g. `2024-03`) for P1M, a date (e.g. `2024-03-02`) for P1M, P1W, and P1D, and a date-time with an optional offset (e.g. `2024-03-02T12:00+01:00` or `2024-03-02T12:00`) for PT1H, PT30M, and PT15M. Note: Only offsets are allowed, no named timezones.\n 2. `consumption` – The consumption in MWh or kWh. Must be a number equal zero or positive.\n\nIf your data does not fulfil this format, the request will be aborted.\n", "required": true, "content": { "text/csv": { "schema": { "type": "string" }, "example": "timestamp,consumption\n2024-01-01T00:00+01:00,1.0\n2024-01-01T01:00+01:00,2.0\n2024-01-01T02:00+01:00,3.0\n2024-01-01T03:00+01:00,4.0\n" }, "text/tab-separated-values": { "schema": { "type": "string" }, "example": "timestamp timezone consumption\n2024-01-01T00:00+01:00 1.0\n2024-01-01T01:00+01:00 2.0\n2024-01-01T02:00+01:00 3.0\n2024-01-01T03:00+01:00 4.0\n" } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "required": [ "parameters", "metadata", "carbon_emissions", "carbon_intensity", "consumption" ], "type": "object", "properties": { "parameters": { "description": "The parameters as given by the user to calculate carbon emissions.\n", "required": [ "area", "emission_type", "unit", "input_frequency", "input_timezone", "has_header_row", "fill" ], "type": "object", "properties": { "area": { "type": "string" }, "emission_type": { "$ref": "#/components/schemas/EmissionType" }, "unit": { "type": "string", "default": "MWh", "enum": [ "kWh", "MWh" ] }, "input_frequency": { "$ref": "#/components/schemas/Frequency" }, "input_timezone": { "$ref": "#/components/schemas/Timezone" }, "has_header_row": { "type": "boolean" }, "fill": { "type": "boolean" }, "fill_value": { "type": "number" } } }, "access": { "$ref": "#/components/schemas/Subscription" }, "metadata": { "required": [ "consumption", "begin", "end" ], "type": "object", "properties": { "consumption": { "description": "The total consumption. It might be different to the `consumption` parameter due to adjusted `begin` and `end`.\n", "type": "number", "format": "double", "minimum": 0 }, "begin": { "description": "The begin of consumption. Might be adjusted due to access restrictions and data availability.\n", "type": "string", "format": "date-time" }, "end": { "description": "The end of consumption. Might be adjusted due to access restrictions and data availability.\n", "type": "string", "format": "date-time" }, "resolution": { "$ref": "#/components/schemas/Resolution" } } }, "carbon_emissions": { "$ref": "#/components/schemas/Timeseries" }, "carbon_intensity": { "$ref": "#/components/schemas/Timeseries" }, "consumption": { "$ref": "#/components/schemas/Timeseries" } } } }, "text/tab-separated-values": { "schema": { "type": "string" } }, "text/csv": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/AuthenticationError" }, "403": { "$ref": "#/components/responses/AccessDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/user/": { "get": { "tags": [ "User" ], "summary": "Get details about the current user", "description": "Receive details about the current users' properties including personal details and active subscriptions.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/AuthenticationError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } } }, "components": { "schemas": { "Resolution": { "required": [ "frequency", "timezone" ], "type": "object", "properties": { "frequency": { "$ref": "#/components/schemas/Frequency" }, "timezone": { "$ref": "#/components/schemas/Timezone" } }, "example": { "frequency": "PT1H", "timezone": "CET" } }, "Frequency": { "type": "string", "description": "Frequency represented in ISO-8601 Duration format (except from `NONE`). Please refer to [Duration (Wikipedia)](https://en.wikipedia.org/wiki/ISO_8601#Durations) for an excellent explanation of the format. Supported frequencies:\n\n * `P1Y` – Yearly\n * `P3M` – Quarterly\n * `P1M` – Monthly\n * `P1W` – Weekly\n * `P1D` – Daily\n * `PT1H` – Hourly\n * `PT30M` – 30 minutes\n * `PT15M` – 15 minutes\n * `PT10M` – 10 minutes\n * `PT5M` – 5 minutes\n * `PT1M` – 1 minute\n * `NONE` – No frequency specified (i.e. tick data)\n", "enum": [ "P1Y", "P3M", "P1M", "P1W", "P1D", "PT1H", "PT30M", "PT15M", "PT10M", "PT5M", "PT1M", "NONE" ] }, "Unit": { "type": "string", "description": "Supported units:\n\n * `°C` for temparatures in celsius degrees\n * `Degrees` for angles in degrees\n * `hPa` for pressure in hectopascal\n * `m` for length in meters\n * `m^2` for area in square meters\n * `m^3` for volume in cubic meters\n * `s` for time in seconds\n * `t` for weight in tons\n * `TW`, `GW`, `MW`, `kW`, `W` for power in watt\n * `TWh`, `GWh`, `MWh`, `kWh`, `Wh` for energy in watt-hours\n * `TWh/h`, `GWh/h`, `MWh/h`, `kWh/h`, `Wh/h` for average energy in watt-hours per hour\n * `therm` for heat energy in therms\n * `bbl` for volume in barrels\n * `gCO2eq` and `kgCO2eq` for grams and kilograms of carbon equivalents\n * `%` as percent\n * `EUR`, `USD`, `GBP`, `NOK`, `SEK`, `DKK`, `CHF`, `CZK`, `HUF`, `PLN`, `BGN`, `HRK`, `RUB`, `RON`, `TRY`, `pence` for currencies\n", "enum": [ "°C", "Degrees", "hPa", "mm", "m", "m^2", "m^3", "s", "t", "TW", "GW", "MW", "kW", "W", "TWh", "GWh", "MWh", "kWh", "Wh", "TWh/h", "GWh/h", "MWh/h", "kWh/h", "Wh/h", "therm", "bbl", "gCO2eq", "kgCO2eq", "%", "EUR", "USD", "GBP", "NOK", "SEK", "DKK", "CHF", "CZK", "HUF", "PLN", "BGN", "HRK", "RUB", "RON", "TRY", "pence" ] }, "Timezone": { "type": "string", "description": "Supported timezones:\n\n * `UTC` – Coordinated Universal Time\n * `WET` – Western European Time\n * `CET` – Central European Time\n * `EET` – Eastern European Time\n * `Europe/Istanbul` – Turkey Time\n * `Europe/Moscow` – Russian/Moscow Time\n * `Europe/Gas_Day` – *(Non-standard timezone; not in the IANA timezone database)* European Gas Day. UTC-0500 with UTC-0400 during Daylight Saving Time. Starts at 06:00 in CE(S)T time. Used for the natural gas market in the European Union.\n", "enum": [ "UTC", "CET", "WET", "EET", "Europe/Istanbul", "Europe/Moscow", "Europe/Gas_Day" ] }, "Commodity": { "type": "string", "description": "The type of commodity a *Curve* belongs to (e.g., Power, Gas, Coal, etc). If a curve does not have a commodity, it is set to None.\n", "enum": [ "None", "Power", "Gas", "Oil", "Carbon", "Coal" ] }, "DataType": { "type": "string", "description": "The data type of a *Curve* describes the type of data.", "enum": [ "ACTUAL", "BACKCAST", "CAPACITY", "CLIMATE", "FORECAST", "FOREX", "NORMAL", "REMIT", "SCENARIO", "SYNTHETIC", "OHLC", "TRADES", "VALUE", "PPA" ] }, "CurveType": { "type": "string", "description": "The storage type of a *Curve*. Since curves store different types of data, the storage type tells you which functions to use when loading it.", "enum": [ "TIMESERIES", "INSTANCE", "SCENARIO_TIMESERIES", "PERIOD", "INSTANCE_PERIOD", "OHLC", "TRADES", "PPA" ] }, "EmissionType": { "type": "string", "description": "The type of carbon emissions. The following values are available:\n\n* `LIFECYCLE` – Lifecycle emissions\n* `OPERATIONAL` – Operational emissions\n", "default": "LIFECYCLE", "enum": [ "LIFECYCLE", "OPERATIONAL" ] }, "SubscriptionAccess": { "type": "string", "enum": [ "FREEMIUM", "BLOCKED", "TRIAL", "PAYING", "REALTO", "INTERNAL", "FREE", "NONE" ], "description": "Access levels for a subscription can take on the following values:\n\n* `FREEMIUM` – Access is included in the freemium tier\n* `BLOCKED` – No access\n* `TRIAL` – Access is granted during a trial period\n* `PAYING` – Access is provided through a paid subscription\n* `REALTO` – Access is associated with a www.realto.io subscription\n* `INTERNAL` – Access is provided through partner agreements\n* `FREE` – Access is available at no cost\n* `NONE` – Missing access information\n" }, "SubscriptionType": { "type": "string", "enum": [ "collection", "free", "freemium", "package", "package_area", "private" ], "description": "Specifies the type of subscription and can be one of the following values:\n\n* `collection` – A subscription related to collections.\n* `free` – No subscription required for provided content.\n* `freemium` – Limited access due to no subscription defined for provided content.\n* `package` – A subscription associated with a package of services.\n* `package_area` – A subscription tied to a combination of a specific package and area.\n* `private` – A private subscription with restricted access.\n" }, "Subscription": { "required": [ "access" ], "type": "object", "properties": { "access": { "$ref": "#/components/schemas/SubscriptionAccess" }, "type": { "$ref": "#/components/schemas/SubscriptionType" }, "label": { "type": "string", "description": "Human-readable label for the subscription." }, "package": { "type": "string", "description": "A unique name for the package. Only available if the type equals `package` or `package_area`." }, "area": { "type": "string", "description": "A tag representing an area (country, price area or region). Only available if the type equals `package_area`. Examples: DE, DK, DK1, DK2, NP, IT, IT-NORD etc.\n" }, "collection": { "type": "string", "description": "A unique name for the collection. Only available if the type equals `collection`." }, "collection_perms": { "type": "string", "description": "Your user's permissions for this collection. `\"r\"` means read-only, `\"rw\"` means read-write. Only available if the type equals `collection`.\n", "enum": [ "r", "rw" ] } }, "description": "Your subscription describing the access to a curve" }, "Curve": { "required": [ "area", "categories", "curve_type", "data_type", "name", "resolution", "unit" ], "type": "object", "properties": { "name": { "type": "string", "description": "The identifier of a *Curve*." }, "resolution": { "$ref": "#/components/schemas/Resolution" }, "area": { "type": "string", "description": "A tag representing an area (country, price area or region). Examples: DE, DK, DK1, DK2, NP, IT, IT-NORD etc.\n" }, "area_sink": { "type": "string", "description": "Same as *area* property, but for exchange curves; the area that *imports* the power.\n" }, "categories": { "type": "array", "items": { "type": "string", "description": "Array of Category names." } }, "unit": { "type": "string", "description": "Unit of the Curve. Examples: MW, GW, °C, MWh/h etc." }, "denominator": { "type": "string", "description": "The denominator when a curve has multiple units. Example: 'EUR/MWh' => Unit=EUR, Denominator=MWh." }, "data_type": { "$ref": "#/components/schemas/DataType" }, "source": { "type": "string", "description": "Origin of the data in this *Curve*." }, "curve_type": { "$ref": "#/components/schemas/CurveType" }, "instance_issued_timezone": { "type": "string", "description": "(Only set for curves with `curve_type = INSTANCE`.) The timezone in which operations on `Instance.issued` is performed, and the timezone `Instance.issued` should be viewed in. This is relevant, for instance, when you would like to group instances on dates.", "enum": [ "UTC", "CET", "WET", "EET", "Europe/Istanbul", "Europe/Moscow", "Europe/Gas_Day" ] }, "commodity": { "$ref": "#/components/schemas/Commodity" }, "place": { "$ref": "#/components/schemas/Place" }, "subscription": { "$ref": "#/components/schemas/Subscription" }, "description": { "type": "object", "description": "A description of the source and content of this curve.", "properties": { "source": { "type": "string", "description": "Name of the source of the data in this curve" }, "notes": { "type": "string", "description": "Additional notes about the data in this curve" } } } }, "example": { "name": "DE Wind Power Production MWh/h H Forecast", "categories": [ "Wind", "Power", "Production" ], "area": "DE", "unit": "MWh/h", "resolution": { "frequency": "PT1H", "timezone": "CET" }, "data_type": "FORECAST", "curve_type": "INSTANCE", "subscription": { "access": "PAYING", "type": "area", "area": "Germany" } } }, "Instance": { "required": [ "issued", "tag" ], "type": "object", "properties": { "issued": { "type": "string", "description": "The issue date-time for the instance.", "format": "date-time" }, "tag": { "type": "string", "description": "Tag or blank string. Tags may be used to separate models, such as forecast models. Examples:\n\n * `ec` – ECMWF deterministic\n * `ec-ens` – ECMWF ensemble\n * `ec-ext` – ECMWF extended range\n * `gfs` – GFS deterministic\n * `gfs-ens` – GFS ensemble\n * `arome` – Arome (Swedish model)\n * `ukmo` – UK MetOffice\n" }, "scenarios": { "type": "integer", "description": "The number of scenarios in this instance (only present when scenarios exist for instance)\n", "format": "int32" }, "created": { "type": "string", "description": "When the instance was created\n", "format": "date-time" }, "modified": { "type": "string", "description": "When the instance was last modified (*null* when not modified since creation)\n", "format": "date-time" } } }, "Place": { "required": [ "key", "name", "type" ], "type": "object", "properties": { "type": { "type": "string", "description": "The type of the entity.", "enum": [ "city", "consumer", "producer", "river", "weatherstation", "gas-storage", "gas-lng-terminal", "gas-interconnector", "other" ] }, "key": { "type": "string", "description": "A unique identifier for the Place." }, "name": { "type": "string", "description": "The name of the city, powerplant, weatherstation etc." }, "unit": { "type": "string", "description": "Additional identification of a object (such as the unit of a powerplant)" }, "fuels": { "type": "array", "description": "Fuel types for powerplants.", "items": { "type": "string", "enum": [ "Biomass", "Fossil", "Lignite", "Derived gas", "Natural gas", "Hard coal", "Oil", "Oil shale", "Peat", "Geothermal", "Hydro", "Pumped storage", "Run-of-river", "Water reservoir", "Marine", "Nuclear", "Waste", "Renewable", "Solar", "Wind", "Offshore", "Onshore", "Other" ] } }, "children": { "type": "array", "description": "Places contained within this place, typically units for powerplants.", "items": { "$ref": "#/components/schemas/Place" } }, "curves": { "type": "array", "description": "Curves that are linked tot this place.", "items": { "$ref": "#/components/schemas/Curve" } }, "area": { "type": "string", "description": "A tag representing an area (country, price area or region). Examples: DE, DK, DK1, DK2, NP, IT, IT-NORD etc.\n" }, "location": { "maxItems": 2, "minItems": 2, "type": "array", "description": "The geolocation of this entity as a (latitude, longitude) pair.", "items": { "type": "number", "format": "double" } }, "remit_units": { "type": "array", "description": "The identifying codes for related outage units", "items": { "type": "string" } } } }, "Timeseries": { "required": [ "curve", "data", "resolution" ], "type": "object", "properties": { "curve": { "$ref": "#/components/schemas/Curve" }, "instance": { "$ref": "#/components/schemas/Instance" }, "resolution": { "$ref": "#/components/schemas/Resolution" }, "unit": { "$ref": "#/components/schemas/Unit" }, "denominator": { "$ref": "#/components/schemas/Unit" }, "contract": { "$ref": "#/components/schemas/Contract" }, "scenario_names": { "type": "array", "items": { "type": "string" } }, "data": { "type": "array", "items": { "required": [ "d" ], "type": "object", "properties": { "d": { "type": "string", "description": "The datetime instant of this value", "format": "date-time" }, "v": { "type": "number", "description": "The value (or mean value if the curve has scenarios)", "format": "double" }, "s": { "type": "array", "description": "The scenario values", "items": { "type": "number", "format": "double" } } } } } } }, "Periodseries": { "required": [ "curve", "data", "resolution" ], "type": "object", "properties": { "curve": { "$ref": "#/components/schemas/Curve" }, "instance": { "$ref": "#/components/schemas/Instance" }, "resolution": { "$ref": "#/components/schemas/Resolution" }, "unit": { "$ref": "#/components/schemas/Unit" }, "denominator": { "$ref": "#/components/schemas/Unit" }, "data": { "type": "array", "items": { "required": [ "begin", "end", "v" ], "type": "object", "properties": { "begin": { "type": "string", "description": "The beginning datetime instant of this period", "format": "date-time" }, "end": { "type": "string", "description": "The ending datetime instant of this period", "format": "date-time" }, "v": { "type": "number", "description": "The value", "format": "double" }, "capacity": { "type": "number", "description": "The installed capacity in this period period", "format": "double" } } } } } }, "Aggregation": { "type": "string", "description": "Supported aggregation methods:\n\n * `AVERAGE` – The average of all values in the aggregation interval\n * `SUM` – The sum of all values in the aggregation interval\n * `MIN` – The minimum value in the aggregation period\n * `MAX` – The maximum value in the aggregation period\n", "default": "AVERAGE", "enum": [ "AVERAGE", "SUM", "MIN", "MAX" ] }, "Filter": { "type": "string", "description": "Used for filtering hours and days in aggregations. Supported filters:\n\n * `BASE` – All hours\n * `PEAK` – Peak hours (8-20). For future contracts: Peak hours (8-20) during workdays\n * `OFFPEAK` – Offpeak (0-8 and 20-24). For future contracts: Offpeak hours (0-8 and 20-24) during workdays and all hours during the weekend\n * `WORKDAYS` – Monday, Tuesday, Wednesday, Thursday, Friday\n * `WEEKENDS` – Saturday, Sunday\n\nFor weekly, monthly, quarterly and yearly resolutions, `PEAK` is defined\nas `PEAK` hours during `WORKDAYS` (8-20 during workdays). `OFFPEAK` is,\nfor the same resolutions, defined as `OFFPEAK` hours during `WORKDAYS` and\nall hours during `WEEKENDS`.\n\nFor daily resolutions, `PEAK` and `OFFPEAK` does not make a distinction between\nworkdays and weekends.\n", "default": "BASE", "enum": [ "BASE", "PEAK", "OFFPEAK", "WORKDAYS", "WEEKENDS" ] }, "Threshold": { "minimum": 0, "default": 0, "oneOf": [ { "type": "integer", "minimum": 0 }, { "type": "string", "pattern": "^(100|[1-9]?\\d)%$" } ], "description": "By default, the aggregation returns empty values whenever one or more input\nvalues are missing. You can set a `threshold` that defines how many values are\nallowed to be missing within a frame of the converted frequency. If the number\nof missing values is less than or equal to the `threshold`, aggregation is\nperformed on the remaining non-empty values. Otherwise, an empty value is\nreturned.\n\nAlternatively, `threshold` can be specified as a percentage (e.g., `50%`),\ndefining the maximum proportion of missing values allowed within a frame of\nthe converted frequency.\n\n**Note**: By default, the threshold is set to zero. This means that an empty\ninput value will result in an empty output value.\n\nFor example, you want to convert hourly values to daily values using the mean\nvalue. Let's assume that some input values are missing. Instead of getting\nempty values, you want to get the average if a maximum of four values are\nmissing within a day. In this case, set the `threshold` to four.\n" }, "Delimiter": { "type": "string", "description": "Only CSV responses for delimiting values. Possible values are `COMMA` (\"a,b,c\") and `SEMICOLON` (\"a;b;c\").\n", "default": "COMMA", "enum": [ "COMMA", "SEMICOLON" ] }, "DecimalSeparator": { "type": "string", "description": "Used in TSV and CSV responses for decimal separators in numbers. Possible values are `PERIOD` (1.23) and `COMMA` (1,23).\n", "default": "PERIOD", "enum": [ "PERIOD", "COMMA" ] }, "Collection": { "required": [ "curves", "name", "permissions" ], "type": "object", "properties": { "name": { "type": "string", "description": "A unique name for the collection." }, "permissions": { "type": "string", "description": "Your user's permissions for this collection. `\"r\"` means read-only, `\"rw\"` means read-write.\n", "enum": [ "r", "rw" ] }, "curves": { "type": "array", "items": { "$ref": "#/components/schemas/Curve" } } } }, "Period": { "type": "string", "description": "Supported contract periods for `OHLC` objects:\n\n * `year` – Yearly contracts\n * `mdec` – The EU/ETS emissions December contract (yearly contract)\n * `season` – Season-based contracts (winter and summer)\n * `quarter` – Quarterly contracts\n * `month` – Monthly contracts\n * `week` – Weekly contracts\n * `day` – Daily contracts\n", "enum": [ "year", "mdec", "season", "quarter", "month", "week", "weekend", "day" ] }, "Product": { "required": [ "delivery", "front", "period", "traded_at" ], "type": "object", "properties": { "traded_at": { "type": "string", "description": "The trading date for an `OHLC` object.", "format": "date" }, "period": { "$ref": "#/components/schemas/Period" }, "delivery": { "type": "string", "description": "The delivery date for the traded commodity. Use in\ncombination with the `period` property to identify the contract.\n", "format": "date" }, "front": { "type": "integer", "description": "The front contract number (1 = front contract, 2 = second front)." } }, "description": "Describing the product (often also referred to as contract) for an `OHLC`\nobject. It identifies the contract by containing the trading date, the\ncontract period and delivery date, and finally the which front contract it\nis, relative to its trading date.\n" }, "OHLC": { "required": [ "product", "settlement" ], "type": "object", "properties": { "product": { "$ref": "#/components/schemas/Product" }, "open": { "type": "number" }, "high": { "type": "number" }, "low": { "type": "number" }, "close": { "type": "number" }, "settlement": { "type": "number" }, "volume": { "type": "number" }, "open_interest": { "type": "number" } } }, "TradePeriod": { "type": "string", "description": "The duration of a trade contract's delivery interval, represented as an ISO-8601 duration.", "enum": [ "PT15M", "PT30M", "PT1H" ] }, "TradeContract": { "required": [ "period", "delivery" ], "type": "object", "properties": { "period": { "$ref": "#/components/schemas/TradePeriod" }, "delivery": { "type": "string", "description": "The beginning of the contract's delivery period, in the curve's timezone.", "example": "2026-08-14 12:00+02:00" } } }, "TradeOHLC": { "required": [ "traded_at", "open", "high", "low", "close", "vwap", "volume", "count" ], "type": "object", "properties": { "traded_at": { "type": "string", "description": "The beginning of the trade-data interval, in the curve's timezone.", "example": "2026-08-14 10:00+02:00" }, "open": { "type": "number", "format": "double", "description": "The first traded price in the interval." }, "high": { "type": "number", "format": "double", "description": "The highest traded price in the interval." }, "low": { "type": "number", "format": "double", "description": "The lowest traded price in the interval." }, "close": { "type": "number", "format": "double", "description": "The last traded price in the interval." }, "vwap": { "type": "number", "format": "double", "description": "The volume-weighted average traded price in the interval." }, "volume": { "type": "number", "format": "double", "minimum": 0, "description": "The total traded volume in the interval." }, "count": { "type": "integer", "format": "int32", "minimum": 0, "description": "The number of trades in the interval." } } }, "TradeOHLCSeries": { "required": [ "trade_contract", "data" ], "type": "object", "properties": { "trade_contract": { "$ref": "#/components/schemas/TradeContract" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/TradeOHLC" } } } }, "TradeOHLCResponse": { "required": [ "curve", "data" ], "type": "object", "properties": { "curve": { "$ref": "#/components/schemas/Curve" }, "frequency": { "$ref": "#/components/schemas/Frequency" }, "unit": { "$ref": "#/components/schemas/Unit" }, "denominator": { "$ref": "#/components/schemas/Unit" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/TradeOHLCSeries" } } } }, "OHLCField": { "type": "string", "description": "Supported fields when converting `OHLC` objects time time series:\n\n * `open`\n * `high`\n * `low`\n * `close`\n * `settlement`\n * `volume`\n * `open_interest`\n", "default": "settlement", "enum": [ "open", "high", "low", "close", "settlement", "volume", "open_interest" ] }, "Contract": { "required": [ "period", "type" ], "type": "object", "properties": { "type": { "type": "string", "enum": [ "CONTINUOUS", "SPECIFIC" ] }, "field": { "type": "string", "enum": [ "open", "high", "low", "close", "settlement", "volume", "open_interest" ] }, "period": { "type": "string", "enum": [ "year", "mdec", "season", "quarter", "month", "week", "weekend", "day" ] }, "delivery": { "type": "string", "format": "date" }, "front": { "type": "number" } } }, "Fill": { "type": "string", "description": "Parameter value for how to fill missing values in time series.\n\n * `no-fill` – No fill is applied (default)\n * `zero-fill` – Fill with zeros\n * `value-fill` – Fill with the a given value\n * `mean-fill` – Fill with the mean value of the series\n * `forward-fill` – Fill missing values with the most recent preceding non-missing value\n * `fill-holes` – Fill holes with the most recent non-missing preceding value\n * `linear-interpolate-fill` – Linear interpolation fill\n", "enum": [ "no-fill", "zero-fill", "value-fill", "mean-fill", "fill-holes", "forward-fill", "linear-interpolate-fill" ] }, "Technology": { "type": "string", "description": "Supported generation technologies for `PPA` objects:\n\n * `solar` – Solar\n * `wind_onshore` – Wind onshore\n * `wind_offshore` – Wind offshore\n", "enum": [ "solar", "wind_onshore", "wind_offshore" ] }, "ContractStructure": { "type": "string", "description": "Supported contract structures for `PPA` objects:\n\n * `year` – Yearly baseload\n * `month` – Monthly baseload\n * `proxy` – Proxy\n * `pay_as_produced` – Pay as produced\n", "enum": [ "year", "month", "proxy", "pay_as_produced" ] }, "PPADuration": { "type": "integer", "description": "The duration of a PPA contract, in years.", "enum": [ 3, 5, 10, 15 ] }, "PPAProduct": { "required": [ "date", "technology", "contract_structure", "delivery_begin", "duration" ], "type": "object", "properties": { "date": { "type": "string", "description": "The quote date for a `PPA` object.", "format": "date" }, "technology": { "$ref": "#/components/schemas/Technology" }, "contract_structure": { "$ref": "#/components/schemas/ContractStructure" }, "delivery_begin": { "type": "string", "description": "The delivery start date for the contract.", "format": "date" }, "duration": { "$ref": "#/components/schemas/PPADuration" } }, "description": "Describing the product for a `PPA` object. It identifies the PPA quote by containing the\nquote date, the generation technology, the contract structure, the delivery start date and\nthe duration of the contract.\n" }, "PPA": { "required": [ "product", "price" ], "type": "object", "properties": { "product": { "$ref": "#/components/schemas/PPAProduct" }, "price": { "type": "number" } } }, "SRMCOptions": { "required": [ "carbon_emissions", "carbon_tax_area", "efficiency", "fuel_type" ], "type": "object", "properties": { "fuel_type": { "type": "string", "enum": [ "COAL", "GAS" ] }, "api2_tonne_to_mwh": { "type": "number", "format": "double" }, "gas_therm_to_mwh": { "type": "number", "format": "double" }, "efficiency": { "type": "number", "format": "double" }, "carbon_emissions": { "type": "number", "format": "double" }, "carbon_tax_area": { "type": "string" } } }, "AbsoluteItem": { "type": "object", "description": "A value and the corresponding instance.", "properties": { "instance": { "$ref": "#/components/schemas/Instance" }, "v": { "type": "number", "description": "The value", "format": "double" } } }, "AbsoluteResult": { "type": "object", "properties": { "curve": { "$ref": "#/components/schemas/Curve" }, "resolution": { "$ref": "#/components/schemas/Resolution" }, "delivery": { "type": "string", "description": "The datetime of the delivery.", "format": "date-time" }, "filter": { "$ref": "#/components/schemas/Filter" }, "aggregation": { "$ref": "#/components/schemas/Aggregation" }, "unit": { "$ref": "#/components/schemas/Unit" }, "denominator": { "$ref": "#/components/schemas/Unit" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/AbsoluteItem" } } } }, "ConsumptionProfile": { "type": "string", "description": "Used for determining consumption behaviour. Available profiles:\n\n * `H0` Household – Households with primarily private consumption \n * `G0` Business General – Represents the average of the overall group of business profiles.\n * `G1` Business Workday – Business with primarily consumption on work days from 8 AM to 6 PM and no or at most low consumption at weekends.\n * `G2` Business Evening – Businesses that are characterised by a rather subordinate daily demand on working days (especially in the dark season) and a consumption focus in the evening hours.\n * `G3` Business Continuous – Business with relatively constant consumption with a noticeable continuous base throughout the year and also over the course of the week.\n * `G4` Business Shop – Business with consumption that is almost exclusively determined by shop opening hours (weekday until the evening and also on Saturday until the afternoon).\n * `G5` Business Bakery – Businesses that traditionally have their main consumption on weekdays from around 3 AM and on Saturday nights from around midnight.\n * `G6` Business Weekend – Businesses with a clear focus on consumption at weekends.\n * `L0` Agriculture General – This profile represents the weighted average of the overall group for agricultural businesses.\n * `L1` Agriculture Milk – The consumption of dairy farms is characterised by the double milking and subsequent cooling of the milk.\n * `L2` Agriculture Others – Most farms have a combination of household and production. This average profile should be applied to such farms.\n\nThe representative load profiles are provided by BDEW German Association of Energy and Water Industries.\n", "enum": [ "H0", "G1", "G2", "G3", "G4", "G5", "G6", "L0", "L1", "L2" ] }, "User": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the user." }, "email": { "type": "string", "description": "The email address of the user.", "format": "email" }, "organization": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the organization" }, "account_manager": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the account manager." }, "email": { "type": "string", "description": "The email address of the account manager.", "format": "email" } } } } }, "subscriptions": { "type": "array", "items": { "$ref": "#/components/schemas/Subscription" } } }, "description": "User details", "example": { "name": "John Doe", "email": "john.doe@acme.com", "organization": { "name": "ACME Inc.", "account_manager": { "name": "Jane", "email": "jane@energyquantified.com" } }, "subscriptions": [ { "name": "PAYING", "begin": "2017-09-01", "end": "2100-01-01", "packages": [ "Germany", "France", "Belgium" ] } ] } }, "PFEventType": { "type": "string", "enum": [ "CURVE_UPDATE", "CURVE_DELETE", "CURVE_TRUNCATE" ], "description": "The `PFEventType` specifies the type of an event. The following values are supported:\n\n| Event Type | Description |\n| -------------- | -------------------------------------- |\n| `CURVE_UPDATE` | Indicates an update of curve data. |\n| `CURVE_DELETE` | Indicates the deletion of curve data. |\n| `CURVE_TRUNCATE` | Indicates the deletion of all data for a curve. |\n" }, "PFMessageType": { "type": "string", "enum": [ "message", "curves.event", "curves.subscribe", "curves.filters" ], "description": "The `PFMessageType` determines the type of a message. The following values are supported:\n\n| Message Type | Description |\n| ----------------- | ------------------------------------------------ |\n| `message` | An informational message from the server. |\n| `curves.event` | A server-sent curve update event. |\n| `curves.subscribe` | A message describing a subscription, usable by both client and server. |\n| `curves.filters` | A message describing filters, usable by both client and server. |\n" }, "PFBaseCurveFilter": { "type": "object", "properties": { "event_types": { "type": "array", "items": { "$ref": "#/components/schemas/PFEventType" }, "description": "Filter by the type of the event." }, "begin": { "type": "string", "format": "date-time", "example": "2017-09-01 05:17:00.000Z", "description": "Filter by the earliest date time of the changed values." }, "end": { "type": "string", "format": "date-time", "example": "2017-09-01 05:17:00.000Z", "description": "Filter by the latest date time of the changed values." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Filter to include instances with given tags. Note: Only affects events with an instance.\n" }, "exclude_tags": { "type": "array", "items": { "type": "string" }, "description": "Filter to exclude instances with given tags. Note: Only affects events with an instance.\n" } }, "description": "Base for filter specifications." }, "PFCurveNameFilter": { "allOf": [ { "$ref": "#/components/schemas/PFBaseCurveFilter" }, { "type": "object", "properties": { "curve_names": { "type": "array", "items": { "type": "string" }, "example": [ "DE Wind Power Production MWh/h 15min Forecast", "DE Solar Photovoltaic Production MWh/h 15min Forecast" ], "description": "A list of exact matching curve names." } } } ], "description": "Filter comprising a list of curve names." }, "PFCurveAttributeFilter": { "allOf": [ { "$ref": "#/components/schemas/PFBaseCurveFilter" }, { "type": "object", "properties": { "areas": { "type": "array", "items": { "type": "string" }, "example": [ "DE", "FR", "NL" ], "description": "Filter by areas (country, price area or region). Matches curves where any of the given areas is the curve's area or, for curves with two areas (e.g., exchange curves), the sink area. Examples: DE, DK, DK1, DK2, NP, IT, IT-NORD etc." }, "data_types": { "type": "array", "items": { "$ref": "#/components/schemas/DataType" }, "description": "Filter by data type." }, "commodities": { "type": "array", "items": { "$ref": "#/components/schemas/Commodity" }, "description": "Filter curves by commodities." }, "categories": { "type": "array", "items": { "type": "string" }, "example": [ "Wind", "Solar" ], "description": "Filter by specifying one or more categories. A Curve always has one or more categories (see Curve model)." }, "exact_categories": { "type": "array", "items": { "type": "string" }, "example": [ "Solar Power Production", "Wind Power Production" ], "description": "Filter by an exact combination of categories in curve names (i.e. 'Wind Power Production', 'Spot Price')." }, "frequencies": { "type": "array", "items": { "$ref": "#/components/schemas/Frequency" }, "example": [ "PT1H", "P1D" ], "description": "Filter by specifying one or more curve frequencies (e.g., PT1H, P1D)." }, "units": { "type": "array", "items": { "$ref": "#/components/schemas/Unit" }, "example": [ "MWh/h", "MW" ], "description": "Filter by specifying one or more units (e.g., MW, MWh/h, EUR). Must specify the exact, case-sensitive name." }, "curve_types": { "type": "array", "items": { "$ref": "#/components/schemas/CurveType" }, "example": [ "TIMESERIES", "INSTANCE" ], "description": "Filter by curve type (e.g., Timeseries, Instance)." }, "sources": { "type": "array", "items": { "type": "string" }, "example": [ "NordPool" ], "description": "Filter by specifying one or more sources (i.e., the origin of data - e.g., NordPool). Must specify the exact, case-sensitive name. The string \"null\" matches curves without a source." } } } ], "description": "Filter encompassing event attributes." }, "PFRequestCurvesFilters": { "type": "object", "required": [ "type" ], "properties": { "type": { "allOf": [ { "$ref": "#/components/schemas/PFMessageType" } ], "description": "Indicates the request's type. When making a curve filter request, you must choose `curves.filters`." }, "request_id": { "type": "string", "format": "uuid", "description": "The ID of the message as an UUID version 4.", "example": "123e4567-e89b-12d3-a456-426614174000" } }, "description": "Client-initiated request to receive the current active filters." }, "PFRequestCurvesSubscribe": { "type": "object", "required": [ "type", "filters" ], "properties": { "type": { "allOf": [ { "$ref": "#/components/schemas/PFMessageType" } ], "description": "Indicates the request's type. When making a curve subscribe request, you must choose `curves.subscribe`." }, "request_id": { "type": "string", "format": "uuid", "description": "The ID of the message as an UUID version 4.", "example": "123e4567-e89b-12d3-a456-426614174000" }, "last_id": { "type": "string", "example": "1504224000000-0", "description": "The last ID." }, "filters": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/PFCurveNameFilter" }, { "$ref": "#/components/schemas/PFCurveAttributeFilter" } ] } } }, "description": "Client-initiated request to subscribe to an array of provided filters." }, "PFServerMessageMessage": { "type": "object", "required": [ "type", "message" ], "properties": { "type": { "allOf": [ { "$ref": "#/components/schemas/PFMessageType" } ], "description": "Indicates the message type. A server message has `message` as type." }, "message": { "type": "string", "example": "To receive events, you must provide an initial filter. More information can be found here: https://app.eqenergy.com/api/docs/", "description": "The message containing the information." } }, "description": "A message reporting non-functional information." }, "PFServerMessageCurvesEvent": { "type": "object", "required": [ "type", "event" ], "properties": { "type": { "allOf": [ { "$ref": "#/components/schemas/PFMessageType" } ], "description": "Indicates the message type. A curve update event has `curves.event` as type." }, "event": { "type": "object", "required": [ "id", "event_type", "curve" ], "properties": { "id": { "type": "string", "example": "1504224000000-0", "description": "The event ID. Can be used for query parameter `last-id`." }, "event_type": { "$ref": "#/components/schemas/PFEventType" }, "curve": { "$ref": "#/components/schemas/Curve" }, "instance": { "$ref": "#/components/schemas/Instance" }, "begin": { "type": "string", "format": "date-time", "example": "2017-09-01 05:17:00.000Z", "description": "The begin of changed values." }, "end": { "type": "string", "format": "date-time", "example": "2017-09-01 05:17:00.000Z", "description": "The end of changed values." }, "values_changed": { "type": "number", "format": "integer", "minimum": 1, "example": 42, "description": "The amount of changed values." } } } }, "description": "A message describing a curve update event." }, "PFServerResponse": { "type": "object", "required": [ "type", "request_id", "status" ], "properties": { "type": { "allOf": [ { "$ref": "#/components/schemas/PFMessageType" } ], "description": "Denotes the response type, which corresponds to the type of the request and can be either `curves.subscribe` or `curves.filters` for a server response." }, "request_id": { "type": "string", "format": "uuid", "description": "The ID of the corresponding message as an UUID version 4.", "example": "123e4567-e89b-12d3-a456-426614174000" }, "status": { "type": "string", "enum": [ "OK", "ERROR" ], "description": "The status indicates if the response either contains `data` or `errors`." }, "data": { "oneOf": [ { "$ref": "#/components/schemas/PFCurvesFilterData" }, { "$ref": "#/components/schemas/PFCurvesSubscribeData" } ] }, "errors": { "type": "array", "items": { "type": "string", "description": "A string describing the error." } } }, "description": "A response to a client message, containing data or errors." }, "PFCurvesFilterData": { "type": "object", "properties": { "filters": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/PFCurveNameFilter" }, { "$ref": "#/components/schemas/PFCurveAttributeFilter" } ] } } }, "description": "Data payload to `curves.filters`. This contains the set of filters." }, "PFCurvesSubscribeData": { "type": "object", "properties": { "last_id": { "type": "string", "example": "1504224000000-0", "description": "The last ID." }, "filters": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/PFCurveNameFilter" }, { "$ref": "#/components/schemas/PFCurveAttributeFilter" } ] } } }, "description": "Data payload to `curves.subscribe`. This contains the set of filters and optionally the last ID." } }, "responses": { "AccessDenied": { "description": "No access to resource", "content": { "*/*": { "schema": { "required": [ "error" ], "type": "object", "properties": { "error": { "type": "string", "description": "Error type" }, "message": { "type": "string", "description": "A human-readable error message explaining which resource the user is not authorized to access." } }, "example": { "error": "FORBIDDEN", "message": "You do not have access to " } } } } }, "AuthenticationError": { "description": "Not authenticated", "content": { "*/*": { "schema": { "required": [ "error" ], "type": "object", "properties": { "error": { "type": "string", "description": "Error type" }, "message": { "type": "string", "description": "A human-readable error message explaining why authentication could not be completed." } }, "example": { "error": "UNAUTHORIZED", "message": "Account deactivated" } } } } }, "InternalServerError": { "description": "Internal server error", "content": { "*/*": { "schema": { "required": [ "error" ], "type": "object", "properties": { "error": { "type": "string", "description": "Error type" }, "message": { "type": "string", "description": "Description of the error message" } }, "example": { "error": "INTERNAL SERVER ERROR", "message": "An unexpected error occurred" } } } } }, "NotFound": { "description": "Resource not found", "content": { "*/*": { "schema": { "required": [ "error" ], "type": "object", "properties": { "error": { "type": "string", "description": "Error type" }, "message": { "type": "string", "description": "A human-readable error message explaining which resource the user is not authorized to access." } }, "example": { "error": "NOT FOUND", "message": " was not found" } } } } }, "ValidationError": { "description": "Validation error (i.e. missing/invalid parameters)", "content": { "*/*": { "schema": { "required": [ "error" ], "type": "object", "properties": { "error": { "type": "string", "description": "Error type" }, "parameter": { "type": "string", "description": "Name of the parameter that failed validation, or `null` when not related to field" }, "message": { "type": "string", "description": "A human-readable error message explaining which resource the user is not authorized to access." } }, "example": { "error": "VALIDATION ERROR", "parameter": "param1", "message": "Param1 is not valid " } } } } } }, "securitySchemes": { "APIKeyQueryParam": { "type": "apiKey", "description": "As this authentication method leaves the API key in the URL, it is well-suited for generating links which can be used as, say, data sources in Excel.", "name": "api-key", "in": "query" }, "APIKeyHeader": { "type": "apiKey", "description": "Provide the API key in a custom HTTP header.", "name": "X-API-Key", "in": "header" } }, "parameters": { "TradeCurveName": { "name": "curve-name", "in": "path", "description": "An urlencoded curve name. The curve must have `curve_type = TRADES`.", "required": true, "schema": { "type": "string" } }, "TradeBegin": { "name": "begin", "in": "query", "description": "The beginning of the delivery-start interval (inclusive). If timezone information is not present, the value is parsed in the curve's timezone.", "required": true, "schema": { "type": "string", "format": "date-time" } }, "TradeEnd": { "name": "end", "in": "query", "description": "The end of the delivery-start interval (exclusive). If timezone information is not present, the value is parsed in the curve's timezone. It must be after `begin` and no more than one week later.", "required": true, "schema": { "type": "string", "format": "date-time" } }, "TradeAfterTimeOfDay": { "name": "after-time-of-day", "in": "query", "description": "Include contracts delivered at or after this local time of day in the curve's timezone. When combined with `before-time-of-day`, this value must be earlier than it.", "schema": { "type": "string", "example": "08:00:00" } }, "TradeBeforeTimeOfDay": { "name": "before-time-of-day", "in": "query", "description": "Include contracts delivered before this local time of day in the curve's timezone. The boundary is exclusive.", "schema": { "type": "string", "example": "20:00:00" } }, "TradePeriods": { "name": "periods", "in": "query", "description": "Include only contracts with one of these delivery periods. Repeat the query parameter to select multiple periods.", "style": "form", "explode": true, "schema": { "type": "array", "uniqueItems": true, "items": { "$ref": "#/components/schemas/TradePeriod" } } }, "TradeExcludePeriods": { "name": "exclude-periods", "in": "query", "description": "Exclude contracts with any of these delivery periods. Repeat the query parameter to exclude multiple periods.", "style": "form", "explode": true, "schema": { "type": "array", "uniqueItems": true, "items": { "$ref": "#/components/schemas/TradePeriod" } } }, "TradeMinLeadTime": { "name": "min-lead-time", "in": "query", "description": "The exclusive minimum lead time between a value's `traded_at` timestamp and the beginning of delivery, as an ISO-8601 duration. It must be shorter than `max-lead-time` and between `PT0S` and `PT36H`.", "schema": { "type": "string", "default": "PT0S", "example": "PT1H" } }, "TradeMaxLeadTime": { "name": "max-lead-time", "in": "query", "description": "The inclusive maximum lead time between a value's `traded_at` timestamp and the beginning of delivery, as an ISO-8601 duration. It must be longer than `min-lead-time` and between `PT0S` and `PT36H`.", "schema": { "type": "string", "default": "PT36H", "example": "PT6H" } }, "Threshold": { "name": "threshold", "in": "query", "description": "Number of values allowed to be missing within a single *frequency* frame. Can be an integer, or a percentage string ending with %. Has no effect unless *frequency* is provided.", "required": false, "schema": { "$ref": "#/components/schemas/Threshold" } } } } }