{ "openapi": "3.1.0", "info": { "title": "GridCapacity API", "version": "1.0.0", "summary": "Normalised, source-backed European grid hosting-capacity data.", "description": "A read-only REST API over grid hosting-capacity data published by European transmission and distribution system operators, normalised into one schema.\n\n**The semantics are the product.** No capacity number is served without its direction, technology, availability type, firmness, horizon, unit, methodology, freshness, provenance and decision context.\n\n**Rights fail closed.** A value whose source does not permit redistribution is withheld: the record is listed with `capacity.value = null` and `access.status = \"withheld\"`, and it never satisfies a numeric filter.\n\n**Units are never converted.** `value_mw` exists only when the source published active power; an MVA figure never satisfies `min_capacity_mw`.\n\n**Every field is always present.** A value that does not apply is `null`; it is never omitted, so a row has the same shape on page one and page four hundred.\n\n**Indicative, not binding.** Capacity figures are what operators publish. Only the operator can confirm capacity for a connection request.\n\nIndependent service. Not affiliated with, endorsed by, or operated by any transmission or distribution system operator.", "contact": { "name": "GridCapacity API", "url": "https://gridcapacityapi.com", "email": "hello@gridcapacityapi.com" }, "termsOfService": "https://gridcapacityapi.com/terms" }, "servers": [ { "url": "https://api.gridcapacityapi.com", "description": "Production" } ], "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "tags": [ { "name": "Meta", "description": "Status, plans and the calling key." }, { "name": "Coverage", "description": "Public coverage and map feeds. No key, rate limited." }, { "name": "Catalogue", "description": "Countries, operators, sources and methodologies." }, { "name": "Assets", "description": "Substations and other grid assets." }, { "name": "Capacity", "description": "Capacity records: search, nearby, per asset, history." }, { "name": "Changes", "description": "The change feed." }, { "name": "Exports", "description": "Asynchronous bulk exports (Business+)." }, { "name": "Webhooks", "description": "Change-feed webhooks (Business+)." } ], "paths": { "/v1/health": { "get": { "tags": [ "Meta" ], "summary": "Service status", "description": "Answers without a key. Reports whether the database is reachable, the build version, and which sign-in methods this deployment offers.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } } }, "security": [] } }, "/v1/plans": { "get": { "tags": [ "Meta" ], "summary": "Plans, prices and entitlements", "description": "Every plan with its price in euros, quotas, limits and capabilities: the same table the API enforces. Enterprise is listed with its \"from\" price and `self_serve: false`.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanList" } } } } }, "security": [] } }, "/v1/key": { "get": { "tags": [ "Meta" ], "summary": "The key making this request", "description": "Its plan, everything that plan allows, and how much of this month's quota it has used. Metered like any data route, so it is also a smoke test of the whole authentication path.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeyInfo" } } } }, "400": { "description": "Invalid parameter or cursor (`invalid_parameter`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_parameter": { "value": { "error": { "code": "invalid_parameter", "message": "Invalid value for min_capacity_mw (expected a number, got \"fifty\").", "request_id": "req_0199…", "details": {} } } } } } } }, "401": { "description": "Missing, malformed or revoked API key (`unauthorized`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "value": { "error": { "code": "unauthorized", "message": "The API key (or session) is missing, malformed or has been revoked.", "request_id": "req_0199…", "details": {} } } } } } } }, "429": { "description": "Rate limit or monthly quota exceeded (`rate_limit_exceeded`, `quota_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limit_exceeded": { "value": { "error": { "code": "rate_limit_exceeded", "message": "Too many requests.", "request_id": "req_0199…", "details": {} } } }, "quota_exceeded": { "value": { "error": { "code": "quota_exceeded", "message": "This month's request quota has been used.", "request_id": "req_0199…", "details": {} } } } } } } } } } }, "/v1/coverage": { "get": { "tags": [ "Coverage" ], "summary": "Coverage per country", "description": "Public and rate limited, no key. Per country: coverage status (computed from the sources, never declared), operators, sources granted and withheld, assets, series and the newest source date; plus dataset totals. Cached for a minute.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Coverage" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "description": "Invalid parameter or cursor (`invalid_parameter`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_parameter": { "value": { "error": { "code": "invalid_parameter", "message": "Invalid value for min_capacity_mw (expected a number, got \"fifty\").", "request_id": "req_0199…", "details": {} } } } } } } }, "429": { "description": "Rate limit or monthly quota exceeded (`rate_limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limit_exceeded": { "value": { "error": { "code": "rate_limit_exceeded", "message": "Too many requests.", "request_id": "req_0199…", "details": {} } } } } } } } }, "security": [] } }, "/v1/assets.geojson": { "get": { "tags": [ "Coverage" ], "summary": "Asset points as GeoJSON", "description": "Public and rate limited, no key. Asset points only — never capacity values — at most 5,000 features; `truncated` says when more matched.", "responses": { "200": { "description": "Success", "content": { "application/geo+json": { "schema": { "$ref": "#/components/schemas/GeoJsonAssets" } } } }, "400": { "description": "Invalid parameter or cursor (`invalid_parameter`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_parameter": { "value": { "error": { "code": "invalid_parameter", "message": "Invalid value for min_capacity_mw (expected a number, got \"fifty\").", "request_id": "req_0199…", "details": {} } } } } } } }, "404": { "description": "Not found (`operator_not_found`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "operator_not_found": { "value": { "error": { "code": "operator_not_found", "message": "No operator is known by \"acme\".", "request_id": "req_0199…", "details": {} } } } } } } }, "429": { "description": "Rate limit or monthly quota exceeded (`rate_limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limit_exceeded": { "value": { "error": { "code": "rate_limit_exceeded", "message": "Too many requests.", "request_id": "req_0199…", "details": {} } } } } } } } }, "parameters": [ { "name": "bbox", "description": "`min_lon,min_lat,max_lon,max_lat`, WGS84 degrees.", "schema": { "type": "string" }, "in": "query", "required": false }, { "name": "country", "description": "ISO 3166-1 alpha-2, comma list. A country with nothing published is `country_not_supported`.", "schema": { "type": "string" }, "in": "query", "required": false }, { "name": "operator", "description": "Operator slug or `op_` id, comma list.", "schema": { "type": "string" }, "in": "query", "required": false }, { "name": "asset_type", "description": "Asset type, comma list.", "schema": { "type": "string", "description": "comma list of: substation, node, busbar, feeder, transformer, congestion_zone, connection_point, grid_cell, area" }, "in": "query", "required": false } ], "security": [] } }, "/v1/tiles/assets/{z}/{x}/{y}.mvt": { "get": { "tags": [ "Coverage" ], "summary": "Asset points as vector tiles", "description": "Public and rate limited, no key. A Mapbox vector tile (layer `assets`) of asset points with id, type, name, slug, country, operator, voltage_kv and precision; no values. At most 20,000 points per tile; `X-Feature-Limit-Reached: true` when capped.", "responses": { "200": { "description": "Success", "content": { "application/vnd.mapbox-vector-tile": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid parameter or cursor (`invalid_parameter`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_parameter": { "value": { "error": { "code": "invalid_parameter", "message": "Invalid value for min_capacity_mw (expected a number, got \"fifty\").", "request_id": "req_0199…", "details": {} } } } } } } }, "429": { "description": "Rate limit or monthly quota exceeded (`rate_limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limit_exceeded": { "value": { "error": { "code": "rate_limit_exceeded", "message": "Too many requests.", "request_id": "req_0199…", "details": {} } } } } } } } }, "parameters": [ { "name": "z", "description": "Zoom.", "schema": { "type": "integer", "minimum": 0, "maximum": 22 }, "in": "path", "required": true }, { "name": "x", "description": "Tile column.", "schema": { "type": "integer", "minimum": 0 }, "in": "path", "required": true }, { "name": "y", "description": "Tile row (the URL ends in `.mvt`).", "schema": { "type": "integer", "minimum": 0 }, "in": "path", "required": true } ], "security": [] } }, "/v1/countries": { "get": { "tags": [ "Catalogue" ], "summary": "Countries", "description": "Every country in the reference list with its computed coverage status.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Country" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "description": "Invalid parameter or cursor (`invalid_parameter`, `invalid_cursor`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_parameter": { "value": { "error": { "code": "invalid_parameter", "message": "Invalid value for min_capacity_mw (expected a number, got \"fifty\").", "request_id": "req_0199…", "details": {} } } }, "invalid_cursor": { "value": { "error": { "code": "invalid_cursor", "message": "The cursor is not valid for this request.", "request_id": "req_0199…", "details": {} } } } } } } }, "401": { "description": "Missing, malformed or revoked API key (`unauthorized`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "value": { "error": { "code": "unauthorized", "message": "The API key (or session) is missing, malformed or has been revoked.", "request_id": "req_0199…", "details": {} } } } } } } }, "429": { "description": "Rate limit or monthly quota exceeded (`rate_limit_exceeded`, `quota_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limit_exceeded": { "value": { "error": { "code": "rate_limit_exceeded", "message": "Too many requests.", "request_id": "req_0199…", "details": {} } } }, "quota_exceeded": { "value": { "error": { "code": "quota_exceeded", "message": "This month's request quota has been used.", "request_id": "req_0199…", "details": {} } } } } } } } }, "parameters": [ { "name": "status", "description": "Coverage status.", "schema": { "type": "string", "enum": [ "live", "partial", "planned", "none" ] }, "in": "query", "required": false }, { "name": "limit", "description": "Rows per page. The maximum is set by your plan (20 / 100 / 200); asking for more is an error rather than a silent truncation.", "schema": { "type": "integer", "minimum": 1, "default": 50 }, "in": "query", "required": false }, { "name": "cursor", "description": "Opaque cursor from `pagination.next_cursor`. Omit for the first page. Bound to the sort it was minted under.", "schema": { "type": "string" }, "in": "query", "required": false } ] } }, "/v1/operators": { "get": { "tags": [ "Catalogue" ], "summary": "Operators", "description": "TSOs and DSOs, with their sources and asset counts. `covered` means at least one of their sources has published values we may serve.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Operator" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "description": "Invalid parameter or cursor (`invalid_parameter`, `invalid_cursor`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_parameter": { "value": { "error": { "code": "invalid_parameter", "message": "Invalid value for min_capacity_mw (expected a number, got \"fifty\").", "request_id": "req_0199…", "details": {} } } }, "invalid_cursor": { "value": { "error": { "code": "invalid_cursor", "message": "The cursor is not valid for this request.", "request_id": "req_0199…", "details": {} } } } } } } }, "401": { "description": "Missing, malformed or revoked API key (`unauthorized`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "value": { "error": { "code": "unauthorized", "message": "The API key (or session) is missing, malformed or has been revoked.", "request_id": "req_0199…", "details": {} } } } } } } }, "404": { "description": "Not found (`country_not_supported`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "country_not_supported": { "value": { "error": { "code": "country_not_supported", "message": "No capacity data is published for country \"DE\" yet.", "request_id": "req_0199…", "details": { "country": "DE" } } } } } } } }, "429": { "description": "Rate limit or monthly quota exceeded (`rate_limit_exceeded`, `quota_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limit_exceeded": { "value": { "error": { "code": "rate_limit_exceeded", "message": "Too many requests.", "request_id": "req_0199…", "details": {} } } }, "quota_exceeded": { "value": { "error": { "code": "quota_exceeded", "message": "This month's request quota has been used.", "request_id": "req_0199…", "details": {} } } } } } } } }, "parameters": [ { "name": "country", "description": "ISO 3166-1 alpha-2.", "schema": { "type": "string" }, "in": "query", "required": false }, { "name": "type", "description": "Operator type.", "schema": { "type": "string", "enum": [ "TSO", "DSO", "TSO_DSO", "joint", "other" ] }, "in": "query", "required": false }, { "name": "covered", "description": "Only covered (or only uncovered) operators.", "schema": { "type": "boolean" }, "in": "query", "required": false }, { "name": "limit", "description": "Rows per page. The maximum is set by your plan (20 / 100 / 200); asking for more is an error rather than a silent truncation.", "schema": { "type": "integer", "minimum": 1, "default": 50 }, "in": "query", "required": false }, { "name": "cursor", "description": "Opaque cursor from `pagination.next_cursor`. Omit for the first page. Bound to the sort it was minted under.", "schema": { "type": "string" }, "in": "query", "required": false } ] } }, "/v1/operators/{id}": { "get": { "tags": [ "Catalogue" ], "summary": "One operator", "description": "By `op_` id or slug, with its sources.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Operator" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "description": "Invalid parameter or cursor (`invalid_parameter`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_parameter": { "value": { "error": { "code": "invalid_parameter", "message": "Invalid value for min_capacity_mw (expected a number, got \"fifty\").", "request_id": "req_0199…", "details": {} } } } } } } }, "401": { "description": "Missing, malformed or revoked API key (`unauthorized`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "value": { "error": { "code": "unauthorized", "message": "The API key (or session) is missing, malformed or has been revoked.", "request_id": "req_0199…", "details": {} } } } } } } }, "404": { "description": "Not found (`operator_not_found`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "operator_not_found": { "value": { "error": { "code": "operator_not_found", "message": "No operator is known by \"acme\".", "request_id": "req_0199…", "details": {} } } } } } } }, "429": { "description": "Rate limit or monthly quota exceeded (`rate_limit_exceeded`, `quota_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limit_exceeded": { "value": { "error": { "code": "rate_limit_exceeded", "message": "Too many requests.", "request_id": "req_0199…", "details": {} } } }, "quota_exceeded": { "value": { "error": { "code": "quota_exceeded", "message": "This month's request quota has been used.", "request_id": "req_0199…", "details": {} } } } } } } } }, "parameters": [ { "name": "id", "description": "`op_` id or slug.", "schema": { "type": "string" }, "in": "path", "required": true } ] } }, "/v1/sources": { "get": { "tags": [ "Catalogue" ], "summary": "Sources", "description": "Every operator publication, registry-only ones included (health `disabled`). `rights_mode` is the effective mode, override included.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SourceSummary" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "description": "Invalid parameter or cursor (`invalid_parameter`, `invalid_cursor`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_parameter": { "value": { "error": { "code": "invalid_parameter", "message": "Invalid value for min_capacity_mw (expected a number, got \"fifty\").", "request_id": "req_0199…", "details": {} } } }, "invalid_cursor": { "value": { "error": { "code": "invalid_cursor", "message": "The cursor is not valid for this request.", "request_id": "req_0199…", "details": {} } } } } } } }, "401": { "description": "Missing, malformed or revoked API key (`unauthorized`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "value": { "error": { "code": "unauthorized", "message": "The API key (or session) is missing, malformed or has been revoked.", "request_id": "req_0199…", "details": {} } } } } } } }, "404": { "description": "Not found (`country_not_supported`, `operator_not_found`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "country_not_supported": { "value": { "error": { "code": "country_not_supported", "message": "No capacity data is published for country \"DE\" yet.", "request_id": "req_0199…", "details": { "country": "DE" } } } }, "operator_not_found": { "value": { "error": { "code": "operator_not_found", "message": "No operator is known by \"acme\".", "request_id": "req_0199…", "details": {} } } } } } } }, "429": { "description": "Rate limit or monthly quota exceeded (`rate_limit_exceeded`, `quota_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limit_exceeded": { "value": { "error": { "code": "rate_limit_exceeded", "message": "Too many requests.", "request_id": "req_0199…", "details": {} } } }, "quota_exceeded": { "value": { "error": { "code": "quota_exceeded", "message": "This month's request quota has been used.", "request_id": "req_0199…", "details": {} } } } } } } } }, "parameters": [ { "name": "country", "description": "ISO 3166-1 alpha-2.", "schema": { "type": "string" }, "in": "query", "required": false }, { "name": "operator", "description": "Operator slug or `op_` id.", "schema": { "type": "string" }, "in": "query", "required": false }, { "name": "rights_mode", "description": "Effective rights mode.", "schema": { "type": "string", "enum": [ "redistribution_allowed", "commercial_use_with_attribution", "derived_only", "internal_cache_only", "link_only", "pending_review", "blocked" ] }, "in": "query", "required": false }, { "name": "health", "description": "Health.", "schema": { "type": "string", "enum": [ "healthy", "stale", "degraded", "failing", "disabled", "unknown" ] }, "in": "query", "required": false }, { "name": "limit", "description": "Rows per page. The maximum is set by your plan (20 / 100 / 200); asking for more is an error rather than a silent truncation.", "schema": { "type": "integer", "minimum": 1, "default": 50 }, "in": "query", "required": false }, { "name": "cursor", "description": "Opaque cursor from `pagination.next_cursor`. Omit for the first page. Bound to the sort it was minted under.", "schema": { "type": "string" }, "in": "query", "required": false } ] } }, "/v1/sources/{id}": { "get": { "tags": [ "Catalogue" ], "summary": "One source", "description": "The full manifest facts: methodologies, licence, rights evidence (URL, verbatim quote, date) and semantics.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Source" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "description": "Invalid parameter or cursor (`invalid_parameter`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_parameter": { "value": { "error": { "code": "invalid_parameter", "message": "Invalid value for min_capacity_mw (expected a number, got \"fifty\").", "request_id": "req_0199…", "details": {} } } } } } } }, "401": { "description": "Missing, malformed or revoked API key (`unauthorized`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "value": { "error": { "code": "unauthorized", "message": "The API key (or session) is missing, malformed or has been revoked.", "request_id": "req_0199…", "details": {} } } } } } } }, "404": { "description": "Not found (`source_not_found`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "source_not_found": { "value": { "error": { "code": "source_not_found", "message": "No source has the id \"be_x\".", "request_id": "req_0199…", "details": {} } } } } } } }, "429": { "description": "Rate limit or monthly quota exceeded (`rate_limit_exceeded`, `quota_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limit_exceeded": { "value": { "error": { "code": "rate_limit_exceeded", "message": "Too many requests.", "request_id": "req_0199…", "details": {} } } }, "quota_exceeded": { "value": { "error": { "code": "quota_exceeded", "message": "This month's request quota has been used.", "request_id": "req_0199…", "details": {} } } } } } } } }, "parameters": [ { "name": "id", "description": "The public id.", "schema": { "type": "string" }, "in": "path", "required": true } ] } }, "/v1/sources/{id}/status": { "get": { "tags": [ "Catalogue" ], "summary": "Source health and freshness", "description": "Health, the last import run and the checks that held it (by name, with how many items each found at fault), and `freshness_seconds`: the age of the data, not of our last fetch.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/SourceStatus" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "description": "Invalid parameter or cursor (`invalid_parameter`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_parameter": { "value": { "error": { "code": "invalid_parameter", "message": "Invalid value for min_capacity_mw (expected a number, got \"fifty\").", "request_id": "req_0199…", "details": {} } } } } } } }, "401": { "description": "Missing, malformed or revoked API key (`unauthorized`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "value": { "error": { "code": "unauthorized", "message": "The API key (or session) is missing, malformed or has been revoked.", "request_id": "req_0199…", "details": {} } } } } } } }, "404": { "description": "Not found (`source_not_found`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "source_not_found": { "value": { "error": { "code": "source_not_found", "message": "No source has the id \"be_x\".", "request_id": "req_0199…", "details": {} } } } } } } }, "429": { "description": "Rate limit or monthly quota exceeded (`rate_limit_exceeded`, `quota_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limit_exceeded": { "value": { "error": { "code": "rate_limit_exceeded", "message": "Too many requests.", "request_id": "req_0199…", "details": {} } } }, "quota_exceeded": { "value": { "error": { "code": "quota_exceeded", "message": "This month's request quota has been used.", "request_id": "req_0199…", "details": {} } } } } } } } }, "parameters": [ { "name": "id", "description": "The public id.", "schema": { "type": "string" }, "in": "path", "required": true } ] } }, "/v1/methodologies/{id}": { "get": { "tags": [ "Catalogue" ], "summary": "One methodology", "description": "How one source computes its numbers: basis, network state, what is included, comparability class, disclaimers.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/MethodologyDetail" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "description": "Invalid parameter or cursor (`invalid_parameter`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_parameter": { "value": { "error": { "code": "invalid_parameter", "message": "Invalid value for min_capacity_mw (expected a number, got \"fifty\").", "request_id": "req_0199…", "details": {} } } } } } } }, "401": { "description": "Missing, malformed or revoked API key (`unauthorized`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "value": { "error": { "code": "unauthorized", "message": "The API key (or session) is missing, malformed or has been revoked.", "request_id": "req_0199…", "details": {} } } } } } } }, "404": { "description": "Not found (`methodology_not_found`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "methodology_not_found": { "value": { "error": { "code": "methodology_not_found", "message": "No methodology has the id \"x\".", "request_id": "req_0199…", "details": {} } } } } } } }, "429": { "description": "Rate limit or monthly quota exceeded (`rate_limit_exceeded`, `quota_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limit_exceeded": { "value": { "error": { "code": "rate_limit_exceeded", "message": "Too many requests.", "request_id": "req_0199…", "details": {} } } }, "quota_exceeded": { "value": { "error": { "code": "quota_exceeded", "message": "This month's request quota has been used.", "request_id": "req_0199…", "details": {} } } } } } } } }, "parameters": [ { "name": "id", "description": "The public id.", "schema": { "type": "string" }, "in": "path", "required": true } ] } }, "/v1/substations": { "get": { "tags": [ "Assets" ], "summary": "Grid assets", "description": "Substations and other grid assets, whatever the rights of their sources (names and locations are listed; values are not here). Every asset type unless `asset_type` is given.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Substation" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "description": "Invalid parameter or cursor (`invalid_parameter`, `invalid_cursor`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_parameter": { "value": { "error": { "code": "invalid_parameter", "message": "Invalid value for min_capacity_mw (expected a number, got \"fifty\").", "request_id": "req_0199…", "details": {} } } }, "invalid_cursor": { "value": { "error": { "code": "invalid_cursor", "message": "The cursor is not valid for this request.", "request_id": "req_0199…", "details": {} } } } } } } }, "401": { "description": "Missing, malformed or revoked API key (`unauthorized`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "value": { "error": { "code": "unauthorized", "message": "The API key (or session) is missing, malformed or has been revoked.", "request_id": "req_0199…", "details": {} } } } } } } }, "403": { "description": "The plan does not include this capability or limit (`plan_required`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "plan_required": { "value": { "error": { "code": "plan_required", "message": "'history' requires the pro plan or above.", "request_id": "req_0199…", "details": { "capability": "history", "required_plan": "pro" }, "required_plan": "pro" } } } } } } }, "404": { "description": "Not found (`country_not_supported`, `operator_not_found`, `operator_not_supported`, `source_not_found`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "country_not_supported": { "value": { "error": { "code": "country_not_supported", "message": "No capacity data is published for country \"DE\" yet.", "request_id": "req_0199…", "details": { "country": "DE" } } } }, "operator_not_found": { "value": { "error": { "code": "operator_not_found", "message": "No operator is known by \"acme\".", "request_id": "req_0199…", "details": {} } } }, "operator_not_supported": { "value": { "error": { "code": "operator_not_supported", "message": "Operator \"stedin\" is known, but no data of theirs has been published here yet.", "request_id": "req_0199…", "details": {} } } }, "source_not_found": { "value": { "error": { "code": "source_not_found", "message": "No source has the id \"be_x\".", "request_id": "req_0199…", "details": {} } } } } } } }, "429": { "description": "Rate limit or monthly quota exceeded (`rate_limit_exceeded`, `quota_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limit_exceeded": { "value": { "error": { "code": "rate_limit_exceeded", "message": "Too many requests.", "request_id": "req_0199…", "details": {} } } }, "quota_exceeded": { "value": { "error": { "code": "quota_exceeded", "message": "This month's request quota has been used.", "request_id": "req_0199…", "details": {} } } } } } } } }, "parameters": [ { "name": "country", "description": "ISO 3166-1 alpha-2, comma list. A country with nothing published is `country_not_supported`.", "schema": { "type": "string" }, "in": "query", "required": false }, { "name": "operator", "description": "Operator slug or `op_` id, comma list.", "schema": { "type": "string" }, "in": "query", "required": false }, { "name": "source", "description": "Assets with an identity in these sources.", "schema": { "type": "string" }, "in": "query", "required": false }, { "name": "asset_type", "description": "Asset type, comma list.", "schema": { "type": "string", "description": "comma list of: substation, node, busbar, feeder, transformer, congestion_zone, connection_point, grid_cell, area" }, "in": "query", "required": false }, { "name": "q", "description": "Name search (substring or trigram similarity).", "schema": { "type": "string" }, "in": "query", "required": false }, { "name": "slug", "description": "Exact slug, with `country` for the site's asset pages.", "schema": { "type": "string" }, "in": "query", "required": false }, { "name": "bbox", "description": "`min_lon,min_lat,max_lon,max_lat`, WGS84 degrees.", "schema": { "type": "string" }, "in": "query", "required": false }, { "name": "lat", "description": "Latitude, WGS84. With `lng`.", "schema": { "type": "number" }, "in": "query", "required": false }, { "name": "lng", "description": "Longitude, WGS84. With `lat`.", "schema": { "type": "number" }, "in": "query", "required": false }, { "name": "radius_km", "description": "Radius around lat/lng on the asset centroid. Default 10 whenever lat/lng are given. Capped per plan (25 / 50 / 250 / 500 / 1000 km): above the cap is `plan_required`.", "schema": { "type": "number" }, "in": "query", "required": false }, { "name": "voltage_min_kv", "description": "Lowest nominal voltage, kV.", "schema": { "type": "number" }, "in": "query", "required": false }, { "name": "voltage_max_kv", "description": "Highest nominal voltage, kV.", "schema": { "type": "number" }, "in": "query", "required": false }, { "name": "has_capacity", "description": "Only assets with (or without) active capacity series.", "schema": { "type": "boolean" }, "in": "query", "required": false }, { "name": "sort", "description": "Sort order. Nulls (withheld values, unstated voltages) sort last either way.", "schema": { "type": "string", "enum": [ "name", "voltage", "-voltage", "distance" ], "default": "name (distance with lat/lng)" }, "in": "query", "required": false }, { "name": "limit", "description": "Rows per page. The maximum is set by your plan (20 / 100 / 200); asking for more is an error rather than a silent truncation.", "schema": { "type": "integer", "minimum": 1, "default": 50 }, "in": "query", "required": false }, { "name": "cursor", "description": "Opaque cursor from `pagination.next_cursor`. Omit for the first page. Bound to the sort it was minted under.", "schema": { "type": "string" }, "in": "query", "required": false } ] } }, "/v1/substations/{id}": { "get": { "tags": [ "Assets" ], "summary": "One substation", "description": "The asset, its source identities, related assets and a capacity summary. A merged asset's id resolves to the asset it was merged into.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Substation" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "description": "Invalid parameter or cursor (`invalid_parameter`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_parameter": { "value": { "error": { "code": "invalid_parameter", "message": "Invalid value for min_capacity_mw (expected a number, got \"fifty\").", "request_id": "req_0199…", "details": {} } } } } } } }, "401": { "description": "Missing, malformed or revoked API key (`unauthorized`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "value": { "error": { "code": "unauthorized", "message": "The API key (or session) is missing, malformed or has been revoked.", "request_id": "req_0199…", "details": {} } } } } } } }, "404": { "description": "Not found (`asset_not_found`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "asset_not_found": { "value": { "error": { "code": "asset_not_found", "message": "No grid asset has the id \"sub_…\".", "request_id": "req_0199…", "details": {} } } } } } } }, "429": { "description": "Rate limit or monthly quota exceeded (`rate_limit_exceeded`, `quota_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limit_exceeded": { "value": { "error": { "code": "rate_limit_exceeded", "message": "Too many requests.", "request_id": "req_0199…", "details": {} } } }, "quota_exceeded": { "value": { "error": { "code": "quota_exceeded", "message": "This month's request quota has been used.", "request_id": "req_0199…", "details": {} } } } } } } } }, "parameters": [ { "name": "id", "description": "A `sub_` id.", "schema": { "type": "string" }, "in": "path", "required": true } ] } }, "/v1/substations/{id}/capacity": { "get": { "tags": [ "Capacity" ], "summary": "Current capacity of a substation", "description": "Every current capacity record of the asset (all availability types unless filtered). `as_of` is Pro+.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CapacityRecord" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": [ { "id": "cap_0698x2v5xyz9kq4m1n7r3b5c8d", "series_id": "cs_0698x2v4abcdkq4m1n7r3b5c8d", "asset": { "id": "sub_0698x2v1abcdkq4m1n7r3b5c8d", "type": "substation", "name": "Mercator", "slug": "mercator-150kv", "country": "BE", "operator": { "id": "op_0698x2v0abcdkq4m1n7r3b5c8d", "slug": "elia", "name": "Elia", "type": "TSO" }, "network_level": "transmission", "voltage_kv": 150, "location": { "type": "Point", "coordinates": [ 4.3517, 50.8503 ], "precision": "exact" }, "distance_km": 8.2 }, "direction": "offtake", "technology": "battery", "capacity": { "type": "available", "value": 42.5, "unit": "MW", "value_mw": 42.5, "qualifier": null, "status": null, "status_label": null }, "firmness": "flexible", "curtailment": { "max_annual_percent": 5 }, "horizon": { "type": "target_year", "year": 2028, "label": "Y+2" }, "scenario": null, "season": null, "variant": null, "details": {}, "methodology": { "id": "elia_ghc_2026", "title": "Elia grid hosting capacity", "capacity_basis": "operator_calculated", "network_state": "n_minus_1", "binding": false, "non_additive": true, "includes_reserved": true, "includes_allocated": null, "includes_pre_reserved": true, "includes_pending_requests": null, "comparability_class": "be_elia_ghc" }, "freshness": { "source_effective_at": "2026-09-01T00:00:00Z", "retrieved_at": "2026-09-25T04:12:51Z", "last_confirmed_at": "2026-09-25T04:12:51Z", "source_health": "healthy" }, "provenance": { "source_id": "be_elia_hosting_capacity", "source_record_id": "12345", "source_url": "https://www.elia.be/", "payload_sha256": "e3b0c442…", "license": "Elia open data licence", "rights_mode": "commercial_use_with_attribution" }, "access": { "status": "granted", "attribution": "Source: Elia" }, "decision_context": { "binding": false, "formal_connection_study_required": true, "source_indicative": true, "statement": "The operator's latest published dataset reports 42.5 MW under methodology elia_ghc_2026." } }, { "id": "cap_0698x2v5xyz9kq4m1n7r3b5c8d", "series_id": "cs_0698x2v4abcdkq4m1n7r3b5c8d", "asset": { "id": "sub_0698x2v1abcdkq4m1n7r3b5c8d", "type": "substation", "name": "Mercator", "slug": "mercator-150kv", "country": "BE", "operator": { "id": "op_0698x2v0abcdkq4m1n7r3b5c8d", "slug": "elia", "name": "Elia", "type": "TSO" }, "network_level": "transmission", "voltage_kv": 150, "location": { "type": "Point", "coordinates": [ 4.3517, 50.8503 ], "precision": "exact" }, "distance_km": 8.2 }, "direction": "offtake", "technology": "battery", "capacity": { "type": "available", "value": null, "unit": "MW", "value_mw": null, "qualifier": null, "status": null, "status_label": null }, "firmness": "flexible", "curtailment": { "max_annual_percent": 5 }, "horizon": { "type": "target_year", "year": 2028, "label": "Y+2" }, "scenario": null, "season": null, "variant": null, "details": {}, "methodology": { "id": "elia_ghc_2026", "title": "Elia grid hosting capacity", "capacity_basis": "operator_calculated", "network_state": "n_minus_1", "binding": false, "non_additive": true, "includes_reserved": true, "includes_allocated": null, "includes_pre_reserved": true, "includes_pending_requests": null, "comparability_class": "be_elia_ghc" }, "freshness": { "source_effective_at": "2026-09-01T00:00:00Z", "retrieved_at": "2026-09-25T04:12:51Z", "last_confirmed_at": "2026-09-25T04:12:51Z", "source_health": "healthy" }, "provenance": { "source_id": "be_elia_hosting_capacity", "source_record_id": "12345", "source_url": "https://www.elia.be/", "payload_sha256": null, "license": "Elia open data licence", "rights_mode": "pending_review" }, "access": { "status": "withheld", "reason": "pending_review", "source_url": "https://www.elia.be/" }, "decision_context": { "binding": false, "formal_connection_study_required": true, "source_indicative": true, "statement": "The operator publishes a value for this record under methodology elia_ghc_2026. It is withheld here because the source's rights mode is pending_review; read it in the operator's own publication." } } ], "pagination": { "has_more": true, "next_cursor": "eyJzIjoiLWNhcGFjaXR5Ii…", "limit": 50 }, "meta": { "request_id": "req_0199…", "warnings": [ "withheld_values: 1 record(s) on this page are listed without their value because the source's licence does not permit redistribution (see access.reason); include_withheld=false drops them" ], "comparability": "best_effort" } } } } }, "400": { "description": "Invalid parameter or cursor (`invalid_parameter`, `invalid_cursor`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_parameter": { "value": { "error": { "code": "invalid_parameter", "message": "Invalid value for min_capacity_mw (expected a number, got \"fifty\").", "request_id": "req_0199…", "details": {} } } }, "invalid_cursor": { "value": { "error": { "code": "invalid_cursor", "message": "The cursor is not valid for this request.", "request_id": "req_0199…", "details": {} } } } } } } }, "401": { "description": "Missing, malformed or revoked API key (`unauthorized`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "value": { "error": { "code": "unauthorized", "message": "The API key (or session) is missing, malformed or has been revoked.", "request_id": "req_0199…", "details": {} } } } } } } }, "403": { "description": "The plan does not include this capability or limit (`plan_required`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "plan_required": { "value": { "error": { "code": "plan_required", "message": "'history' requires the pro plan or above.", "request_id": "req_0199…", "details": { "capability": "history", "required_plan": "pro" }, "required_plan": "pro" } } } } } } }, "404": { "description": "Not found (`asset_not_found`, `capacity_not_available`, `source_not_found`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "asset_not_found": { "value": { "error": { "code": "asset_not_found", "message": "No grid asset has the id \"sub_…\".", "request_id": "req_0199…", "details": {} } } }, "capacity_not_available": { "value": { "error": { "code": "capacity_not_available", "message": "The operator publishes no capacity figures for sub_….", "request_id": "req_0199…", "details": {} } } }, "source_not_found": { "value": { "error": { "code": "source_not_found", "message": "No source has the id \"be_x\".", "request_id": "req_0199…", "details": {} } } } } } } }, "409": { "description": "Conflict with the state of the data (`source_not_available`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "source_not_available": { "value": { "error": { "code": "source_not_available", "message": "Source \"be_x\" is disabled, listed without being fetched, or has never published.", "request_id": "req_0199…", "details": {} } } } } } } }, "429": { "description": "Rate limit or monthly quota exceeded (`rate_limit_exceeded`, `quota_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limit_exceeded": { "value": { "error": { "code": "rate_limit_exceeded", "message": "Too many requests.", "request_id": "req_0199…", "details": {} } } }, "quota_exceeded": { "value": { "error": { "code": "quota_exceeded", "message": "This month's request quota has been used.", "request_id": "req_0199…", "details": {} } } } } } } }, "451": { "description": "Unavailable for legal reasons (rights) (`source_rights_restricted`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "source_rights_restricted": { "value": { "error": { "code": "source_rights_restricted", "message": "Every source named in this request withholds its values.", "request_id": "req_0199…", "details": { "sources": [ { "source_id": "be_elia_hosting_capacity", "rights_mode": "pending_review", "source_url": "https://www.elia.be/" } ] } } } } } } } } }, "parameters": [ { "name": "id", "description": "A `sub_` id.", "schema": { "type": "string" }, "in": "path", "required": true }, { "name": "direction", "description": "Direction, comma list.", "schema": { "type": "string", "description": "comma list of: injection, offtake, bidirectional, unknown" }, "in": "query", "required": false }, { "name": "technology", "description": "Technology, comma list.", "schema": { "type": "string", "description": "comma list of: generic_generation, generic_load, solar_pv, wind_onshore, wind_offshore, battery, storage_other, hydrogen, electrolyser, ev_charging, data_center, other, unknown" }, "in": "query", "required": false }, { "name": "availability_type", "description": "What the number counts, comma list. Search and nearby default to `available`.", "schema": { "type": "string", "description": "comma list of: available, requested, reserved, allocated, pre_reserved, connected, waitlisted, contracted, installed, total, unknown" }, "in": "query", "required": false }, { "name": "firmness", "description": "Firmness, comma list.", "schema": { "type": "string", "description": "comma list of: firm, flexible, conditional, unknown" }, "in": "query", "required": false }, { "name": "horizon", "description": "`snapshot`, a target year (`2028`) or the operator's label (`Y+2`).", "schema": { "type": "string" }, "in": "query", "required": false }, { "name": "curtailment_max_pct", "description": "Largest acceptable curtailment band. Firm series satisfy any value; series of unknown firmness never do.", "schema": { "type": "number" }, "in": "query", "required": false }, { "name": "min_capacity_mw", "description": "On `value_mw` only: an MVA figure never satisfies it. Withheld values never satisfy any numeric filter.", "schema": { "type": "number" }, "in": "query", "required": false }, { "name": "max_capacity_mw", "description": "On `value_mw` only.", "schema": { "type": "number" }, "in": "query", "required": false }, { "name": "unit", "description": "Unit as published, comma list. Nothing is converted.", "schema": { "type": "string", "description": "comma list of: MW, kW, MVA, kVA, A, GWh, count, percent, status" }, "in": "query", "required": false }, { "name": "min_capacity", "description": "On `value` in the one unit named by `unit` (required, exactly one): `unit=MVA&min_capacity=50`.", "schema": { "type": "number" }, "in": "query", "required": false }, { "name": "max_capacity", "description": "On `value` in the one unit named by `unit`.", "schema": { "type": "number" }, "in": "query", "required": false }, { "name": "status", "description": "Categorical status, comma list (unit=status sources).", "schema": { "type": "string", "description": "comma list of: available, limited, unavailable, waitlist, under_study, unknown" }, "in": "query", "required": false }, { "name": "source", "description": "Source id, comma list. Naming only sources that withhold their values is `source_rights_restricted` (451).", "schema": { "type": "string" }, "in": "query", "required": false }, { "name": "as_of", "description": "Pro+. RFC 3339 timestamp or date (end of that day, UTC): what the latest published data said then, on our observation clock.", "schema": { "type": "string" }, "in": "query", "required": false }, { "name": "include_withheld", "description": "Default true: withheld records are listed without their value. false drops them.", "schema": { "type": "boolean" }, "in": "query", "required": false }, { "name": "sort", "description": "Sort order. Nulls (withheld values, unstated voltages) sort last either way.", "schema": { "type": "string", "enum": [ "capacity", "-capacity", "distance", "voltage", "-voltage", "name", "source_updated_at", "-source_updated_at", "observed_at", "-observed_at" ], "default": "-capacity" }, "in": "query", "required": false }, { "name": "limit", "description": "Rows per page. The maximum is set by your plan (20 / 100 / 200); asking for more is an error rather than a silent truncation.", "schema": { "type": "integer", "minimum": 1, "default": 50 }, "in": "query", "required": false }, { "name": "cursor", "description": "Opaque cursor from `pagination.next_cursor`. Omit for the first page. Bound to the sort it was minted under.", "schema": { "type": "string" }, "in": "query", "required": false } ] } }, "/v1/substations/{id}/capacity/history": { "get": { "tags": [ "Capacity" ], "summary": "History of a substation's capacity", "description": "Pro+. Each series with its observations as intervals `[observed_from, observed_to)` of our observation clock, overlapping `from`..`to`.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SeriesHistory" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "description": "Invalid parameter or cursor (`invalid_parameter`, `invalid_cursor`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_parameter": { "value": { "error": { "code": "invalid_parameter", "message": "Invalid value for min_capacity_mw (expected a number, got \"fifty\").", "request_id": "req_0199…", "details": {} } } }, "invalid_cursor": { "value": { "error": { "code": "invalid_cursor", "message": "The cursor is not valid for this request.", "request_id": "req_0199…", "details": {} } } } } } } }, "401": { "description": "Missing, malformed or revoked API key (`unauthorized`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "value": { "error": { "code": "unauthorized", "message": "The API key (or session) is missing, malformed or has been revoked.", "request_id": "req_0199…", "details": {} } } } } } } }, "403": { "description": "The plan does not include this capability or limit (`plan_required`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "plan_required": { "value": { "error": { "code": "plan_required", "message": "'history' requires the pro plan or above.", "request_id": "req_0199…", "details": { "capability": "history", "required_plan": "pro" }, "required_plan": "pro" } } } } } } }, "404": { "description": "Not found (`asset_not_found`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "asset_not_found": { "value": { "error": { "code": "asset_not_found", "message": "No grid asset has the id \"sub_…\".", "request_id": "req_0199…", "details": {} } } } } } } }, "429": { "description": "Rate limit or monthly quota exceeded (`rate_limit_exceeded`, `quota_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limit_exceeded": { "value": { "error": { "code": "rate_limit_exceeded", "message": "Too many requests.", "request_id": "req_0199…", "details": {} } } }, "quota_exceeded": { "value": { "error": { "code": "quota_exceeded", "message": "This month's request quota has been used.", "request_id": "req_0199…", "details": {} } } } } } } } }, "parameters": [ { "name": "id", "description": "A `sub_` id.", "schema": { "type": "string" }, "in": "path", "required": true }, { "name": "from", "description": "RFC 3339 or date (start of day).", "schema": { "type": "string" }, "in": "query", "required": false }, { "name": "to", "description": "RFC 3339 or date (end of day, exclusive).", "schema": { "type": "string" }, "in": "query", "required": false }, { "name": "direction", "description": "Direction, comma list.", "schema": { "type": "string", "description": "comma list of: injection, offtake, bidirectional, unknown" }, "in": "query", "required": false }, { "name": "technology", "description": "Technology, comma list.", "schema": { "type": "string", "description": "comma list of: generic_generation, generic_load, solar_pv, wind_onshore, wind_offshore, battery, storage_other, hydrogen, electrolyser, ev_charging, data_center, other, unknown" }, "in": "query", "required": false }, { "name": "availability_type", "description": "What the number counts, comma list. Search and nearby default to `available`.", "schema": { "type": "string", "description": "comma list of: available, requested, reserved, allocated, pre_reserved, connected, waitlisted, contracted, installed, total, unknown" }, "in": "query", "required": false }, { "name": "firmness", "description": "Firmness, comma list.", "schema": { "type": "string", "description": "comma list of: firm, flexible, conditional, unknown" }, "in": "query", "required": false }, { "name": "horizon", "description": "`snapshot`, a target year (`2028`) or the operator's label (`Y+2`).", "schema": { "type": "string" }, "in": "query", "required": false }, { "name": "limit", "description": "Rows per page. The maximum is set by your plan (20 / 100 / 200); asking for more is an error rather than a silent truncation.", "schema": { "type": "integer", "minimum": 1, "default": 50 }, "in": "query", "required": false }, { "name": "cursor", "description": "Opaque cursor from `pagination.next_cursor`. Omit for the first page. Bound to the sort it was minted under.", "schema": { "type": "string" }, "in": "query", "required": false } ] } }, "/v1/grid-assets/{id}": { "get": { "tags": [ "Assets" ], "summary": "One grid asset of any type", "description": "As `/v1/substations/{id}`, for any asset id prefix (`sub_`, `zone_`, `node_`, …).", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Substation" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "description": "Invalid parameter or cursor (`invalid_parameter`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_parameter": { "value": { "error": { "code": "invalid_parameter", "message": "Invalid value for min_capacity_mw (expected a number, got \"fifty\").", "request_id": "req_0199…", "details": {} } } } } } } }, "401": { "description": "Missing, malformed or revoked API key (`unauthorized`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "value": { "error": { "code": "unauthorized", "message": "The API key (or session) is missing, malformed or has been revoked.", "request_id": "req_0199…", "details": {} } } } } } } }, "404": { "description": "Not found (`asset_not_found`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "asset_not_found": { "value": { "error": { "code": "asset_not_found", "message": "No grid asset has the id \"sub_…\".", "request_id": "req_0199…", "details": {} } } } } } } }, "429": { "description": "Rate limit or monthly quota exceeded (`rate_limit_exceeded`, `quota_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limit_exceeded": { "value": { "error": { "code": "rate_limit_exceeded", "message": "Too many requests.", "request_id": "req_0199…", "details": {} } } }, "quota_exceeded": { "value": { "error": { "code": "quota_exceeded", "message": "This month's request quota has been used.", "request_id": "req_0199…", "details": {} } } } } } } } }, "parameters": [ { "name": "id", "description": "Any grid-asset id.", "schema": { "type": "string" }, "in": "path", "required": true } ] } }, "/v1/grid-assets/{id}/capacity": { "get": { "tags": [ "Capacity" ], "summary": "Current capacity of any grid asset", "description": "As `/v1/substations/{id}/capacity`, for any asset type — a Dutch supply area (`zone_`), a Belgian municipality (`area_`), a node. `as_of` is Pro+.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CapacityRecord" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": [ { "id": "cap_0698x2v5xyz9kq4m1n7r3b5c8d", "series_id": "cs_0698x2v4abcdkq4m1n7r3b5c8d", "asset": { "id": "sub_0698x2v1abcdkq4m1n7r3b5c8d", "type": "substation", "name": "Mercator", "slug": "mercator-150kv", "country": "BE", "operator": { "id": "op_0698x2v0abcdkq4m1n7r3b5c8d", "slug": "elia", "name": "Elia", "type": "TSO" }, "network_level": "transmission", "voltage_kv": 150, "location": { "type": "Point", "coordinates": [ 4.3517, 50.8503 ], "precision": "exact" }, "distance_km": 8.2 }, "direction": "offtake", "technology": "battery", "capacity": { "type": "available", "value": 42.5, "unit": "MW", "value_mw": 42.5, "qualifier": null, "status": null, "status_label": null }, "firmness": "flexible", "curtailment": { "max_annual_percent": 5 }, "horizon": { "type": "target_year", "year": 2028, "label": "Y+2" }, "scenario": null, "season": null, "variant": null, "details": {}, "methodology": { "id": "elia_ghc_2026", "title": "Elia grid hosting capacity", "capacity_basis": "operator_calculated", "network_state": "n_minus_1", "binding": false, "non_additive": true, "includes_reserved": true, "includes_allocated": null, "includes_pre_reserved": true, "includes_pending_requests": null, "comparability_class": "be_elia_ghc" }, "freshness": { "source_effective_at": "2026-09-01T00:00:00Z", "retrieved_at": "2026-09-25T04:12:51Z", "last_confirmed_at": "2026-09-25T04:12:51Z", "source_health": "healthy" }, "provenance": { "source_id": "be_elia_hosting_capacity", "source_record_id": "12345", "source_url": "https://www.elia.be/", "payload_sha256": "e3b0c442…", "license": "Elia open data licence", "rights_mode": "commercial_use_with_attribution" }, "access": { "status": "granted", "attribution": "Source: Elia" }, "decision_context": { "binding": false, "formal_connection_study_required": true, "source_indicative": true, "statement": "The operator's latest published dataset reports 42.5 MW under methodology elia_ghc_2026." } }, { "id": "cap_0698x2v5xyz9kq4m1n7r3b5c8d", "series_id": "cs_0698x2v4abcdkq4m1n7r3b5c8d", "asset": { "id": "sub_0698x2v1abcdkq4m1n7r3b5c8d", "type": "substation", "name": "Mercator", "slug": "mercator-150kv", "country": "BE", "operator": { "id": "op_0698x2v0abcdkq4m1n7r3b5c8d", "slug": "elia", "name": "Elia", "type": "TSO" }, "network_level": "transmission", "voltage_kv": 150, "location": { "type": "Point", "coordinates": [ 4.3517, 50.8503 ], "precision": "exact" }, "distance_km": 8.2 }, "direction": "offtake", "technology": "battery", "capacity": { "type": "available", "value": null, "unit": "MW", "value_mw": null, "qualifier": null, "status": null, "status_label": null }, "firmness": "flexible", "curtailment": { "max_annual_percent": 5 }, "horizon": { "type": "target_year", "year": 2028, "label": "Y+2" }, "scenario": null, "season": null, "variant": null, "details": {}, "methodology": { "id": "elia_ghc_2026", "title": "Elia grid hosting capacity", "capacity_basis": "operator_calculated", "network_state": "n_minus_1", "binding": false, "non_additive": true, "includes_reserved": true, "includes_allocated": null, "includes_pre_reserved": true, "includes_pending_requests": null, "comparability_class": "be_elia_ghc" }, "freshness": { "source_effective_at": "2026-09-01T00:00:00Z", "retrieved_at": "2026-09-25T04:12:51Z", "last_confirmed_at": "2026-09-25T04:12:51Z", "source_health": "healthy" }, "provenance": { "source_id": "be_elia_hosting_capacity", "source_record_id": "12345", "source_url": "https://www.elia.be/", "payload_sha256": null, "license": "Elia open data licence", "rights_mode": "pending_review" }, "access": { "status": "withheld", "reason": "pending_review", "source_url": "https://www.elia.be/" }, "decision_context": { "binding": false, "formal_connection_study_required": true, "source_indicative": true, "statement": "The operator publishes a value for this record under methodology elia_ghc_2026. It is withheld here because the source's rights mode is pending_review; read it in the operator's own publication." } } ], "pagination": { "has_more": true, "next_cursor": "eyJzIjoiLWNhcGFjaXR5Ii…", "limit": 50 }, "meta": { "request_id": "req_0199…", "warnings": [ "withheld_values: 1 record(s) on this page are listed without their value because the source's licence does not permit redistribution (see access.reason); include_withheld=false drops them" ], "comparability": "best_effort" } } } } }, "400": { "description": "Invalid parameter or cursor (`invalid_parameter`, `invalid_cursor`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_parameter": { "value": { "error": { "code": "invalid_parameter", "message": "Invalid value for min_capacity_mw (expected a number, got \"fifty\").", "request_id": "req_0199…", "details": {} } } }, "invalid_cursor": { "value": { "error": { "code": "invalid_cursor", "message": "The cursor is not valid for this request.", "request_id": "req_0199…", "details": {} } } } } } } }, "401": { "description": "Missing, malformed or revoked API key (`unauthorized`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "value": { "error": { "code": "unauthorized", "message": "The API key (or session) is missing, malformed or has been revoked.", "request_id": "req_0199…", "details": {} } } } } } } }, "403": { "description": "The plan does not include this capability or limit (`plan_required`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "plan_required": { "value": { "error": { "code": "plan_required", "message": "'history' requires the pro plan or above.", "request_id": "req_0199…", "details": { "capability": "history", "required_plan": "pro" }, "required_plan": "pro" } } } } } } }, "404": { "description": "Not found (`asset_not_found`, `capacity_not_available`, `source_not_found`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "asset_not_found": { "value": { "error": { "code": "asset_not_found", "message": "No grid asset has the id \"sub_…\".", "request_id": "req_0199…", "details": {} } } }, "capacity_not_available": { "value": { "error": { "code": "capacity_not_available", "message": "The operator publishes no capacity figures for sub_….", "request_id": "req_0199…", "details": {} } } }, "source_not_found": { "value": { "error": { "code": "source_not_found", "message": "No source has the id \"be_x\".", "request_id": "req_0199…", "details": {} } } } } } } }, "409": { "description": "Conflict with the state of the data (`source_not_available`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "source_not_available": { "value": { "error": { "code": "source_not_available", "message": "Source \"be_x\" is disabled, listed without being fetched, or has never published.", "request_id": "req_0199…", "details": {} } } } } } } }, "429": { "description": "Rate limit or monthly quota exceeded (`rate_limit_exceeded`, `quota_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limit_exceeded": { "value": { "error": { "code": "rate_limit_exceeded", "message": "Too many requests.", "request_id": "req_0199…", "details": {} } } }, "quota_exceeded": { "value": { "error": { "code": "quota_exceeded", "message": "This month's request quota has been used.", "request_id": "req_0199…", "details": {} } } } } } } }, "451": { "description": "Unavailable for legal reasons (rights) (`source_rights_restricted`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "source_rights_restricted": { "value": { "error": { "code": "source_rights_restricted", "message": "Every source named in this request withholds its values.", "request_id": "req_0199…", "details": { "sources": [ { "source_id": "be_elia_hosting_capacity", "rights_mode": "pending_review", "source_url": "https://www.elia.be/" } ] } } } } } } } } }, "parameters": [ { "name": "id", "description": "Any grid-asset id.", "schema": { "type": "string" }, "in": "path", "required": true }, { "name": "direction", "description": "Direction, comma list.", "schema": { "type": "string", "description": "comma list of: injection, offtake, bidirectional, unknown" }, "in": "query", "required": false }, { "name": "technology", "description": "Technology, comma list.", "schema": { "type": "string", "description": "comma list of: generic_generation, generic_load, solar_pv, wind_onshore, wind_offshore, battery, storage_other, hydrogen, electrolyser, ev_charging, data_center, other, unknown" }, "in": "query", "required": false }, { "name": "availability_type", "description": "What the number counts, comma list. Search and nearby default to `available`.", "schema": { "type": "string", "description": "comma list of: available, requested, reserved, allocated, pre_reserved, connected, waitlisted, contracted, installed, total, unknown" }, "in": "query", "required": false }, { "name": "firmness", "description": "Firmness, comma list.", "schema": { "type": "string", "description": "comma list of: firm, flexible, conditional, unknown" }, "in": "query", "required": false }, { "name": "horizon", "description": "`snapshot`, a target year (`2028`) or the operator's label (`Y+2`).", "schema": { "type": "string" }, "in": "query", "required": false }, { "name": "curtailment_max_pct", "description": "Largest acceptable curtailment band. Firm series satisfy any value; series of unknown firmness never do.", "schema": { "type": "number" }, "in": "query", "required": false }, { "name": "min_capacity_mw", "description": "On `value_mw` only: an MVA figure never satisfies it. Withheld values never satisfy any numeric filter.", "schema": { "type": "number" }, "in": "query", "required": false }, { "name": "max_capacity_mw", "description": "On `value_mw` only.", "schema": { "type": "number" }, "in": "query", "required": false }, { "name": "unit", "description": "Unit as published, comma list. Nothing is converted.", "schema": { "type": "string", "description": "comma list of: MW, kW, MVA, kVA, A, GWh, count, percent, status" }, "in": "query", "required": false }, { "name": "min_capacity", "description": "On `value` in the one unit named by `unit` (required, exactly one): `unit=MVA&min_capacity=50`.", "schema": { "type": "number" }, "in": "query", "required": false }, { "name": "max_capacity", "description": "On `value` in the one unit named by `unit`.", "schema": { "type": "number" }, "in": "query", "required": false }, { "name": "status", "description": "Categorical status, comma list (unit=status sources).", "schema": { "type": "string", "description": "comma list of: available, limited, unavailable, waitlist, under_study, unknown" }, "in": "query", "required": false }, { "name": "source", "description": "Source id, comma list. Naming only sources that withhold their values is `source_rights_restricted` (451).", "schema": { "type": "string" }, "in": "query", "required": false }, { "name": "as_of", "description": "Pro+. RFC 3339 timestamp or date (end of that day, UTC): what the latest published data said then, on our observation clock.", "schema": { "type": "string" }, "in": "query", "required": false }, { "name": "include_withheld", "description": "Default true: withheld records are listed without their value. false drops them.", "schema": { "type": "boolean" }, "in": "query", "required": false }, { "name": "sort", "description": "Sort order. Nulls (withheld values, unstated voltages) sort last either way.", "schema": { "type": "string", "enum": [ "capacity", "-capacity", "distance", "voltage", "-voltage", "name", "source_updated_at", "-source_updated_at", "observed_at", "-observed_at" ], "default": "-capacity" }, "in": "query", "required": false }, { "name": "limit", "description": "Rows per page. The maximum is set by your plan (20 / 100 / 200); asking for more is an error rather than a silent truncation.", "schema": { "type": "integer", "minimum": 1, "default": 50 }, "in": "query", "required": false }, { "name": "cursor", "description": "Opaque cursor from `pagination.next_cursor`. Omit for the first page. Bound to the sort it was minted under.", "schema": { "type": "string" }, "in": "query", "required": false } ] } }, "/v1/grid-assets/{id}/capacity/history": { "get": { "tags": [ "Capacity" ], "summary": "History of any grid asset's capacity", "description": "As `/v1/substations/{id}/capacity/history`, for any asset type. Pro+.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SeriesHistory" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "description": "Invalid parameter or cursor (`invalid_parameter`, `invalid_cursor`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_parameter": { "value": { "error": { "code": "invalid_parameter", "message": "Invalid value for min_capacity_mw (expected a number, got \"fifty\").", "request_id": "req_0199…", "details": {} } } }, "invalid_cursor": { "value": { "error": { "code": "invalid_cursor", "message": "The cursor is not valid for this request.", "request_id": "req_0199…", "details": {} } } } } } } }, "401": { "description": "Missing, malformed or revoked API key (`unauthorized`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "value": { "error": { "code": "unauthorized", "message": "The API key (or session) is missing, malformed or has been revoked.", "request_id": "req_0199…", "details": {} } } } } } } }, "403": { "description": "The plan does not include this capability or limit (`plan_required`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "plan_required": { "value": { "error": { "code": "plan_required", "message": "'history' requires the pro plan or above.", "request_id": "req_0199…", "details": { "capability": "history", "required_plan": "pro" }, "required_plan": "pro" } } } } } } }, "404": { "description": "Not found (`asset_not_found`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "asset_not_found": { "value": { "error": { "code": "asset_not_found", "message": "No grid asset has the id \"sub_…\".", "request_id": "req_0199…", "details": {} } } } } } } }, "429": { "description": "Rate limit or monthly quota exceeded (`rate_limit_exceeded`, `quota_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limit_exceeded": { "value": { "error": { "code": "rate_limit_exceeded", "message": "Too many requests.", "request_id": "req_0199…", "details": {} } } }, "quota_exceeded": { "value": { "error": { "code": "quota_exceeded", "message": "This month's request quota has been used.", "request_id": "req_0199…", "details": {} } } } } } } } }, "parameters": [ { "name": "id", "description": "Any grid-asset id.", "schema": { "type": "string" }, "in": "path", "required": true }, { "name": "from", "description": "RFC 3339 or date (start of day).", "schema": { "type": "string" }, "in": "query", "required": false }, { "name": "to", "description": "RFC 3339 or date (end of day, exclusive).", "schema": { "type": "string" }, "in": "query", "required": false }, { "name": "direction", "description": "Direction, comma list.", "schema": { "type": "string", "description": "comma list of: injection, offtake, bidirectional, unknown" }, "in": "query", "required": false }, { "name": "technology", "description": "Technology, comma list.", "schema": { "type": "string", "description": "comma list of: generic_generation, generic_load, solar_pv, wind_onshore, wind_offshore, battery, storage_other, hydrogen, electrolyser, ev_charging, data_center, other, unknown" }, "in": "query", "required": false }, { "name": "availability_type", "description": "What the number counts, comma list. Search and nearby default to `available`.", "schema": { "type": "string", "description": "comma list of: available, requested, reserved, allocated, pre_reserved, connected, waitlisted, contracted, installed, total, unknown" }, "in": "query", "required": false }, { "name": "firmness", "description": "Firmness, comma list.", "schema": { "type": "string", "description": "comma list of: firm, flexible, conditional, unknown" }, "in": "query", "required": false }, { "name": "horizon", "description": "`snapshot`, a target year (`2028`) or the operator's label (`Y+2`).", "schema": { "type": "string" }, "in": "query", "required": false }, { "name": "limit", "description": "Rows per page. The maximum is set by your plan (20 / 100 / 200); asking for more is an error rather than a silent truncation.", "schema": { "type": "integer", "minimum": 1, "default": 50 }, "in": "query", "required": false }, { "name": "cursor", "description": "Opaque cursor from `pagination.next_cursor`. Omit for the first page. Bound to the sort it was minted under.", "schema": { "type": "string" }, "in": "query", "required": false } ] } }, "/v1/capacity/search": { "get": { "tags": [ "Capacity" ], "summary": "Search capacity records", "description": "The central query. Every record carries its dimensions, methodology, freshness, provenance, access and decision context. Withheld values are listed without their number and never satisfy a numeric filter.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CapacityRecord" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": [ { "id": "cap_0698x2v5xyz9kq4m1n7r3b5c8d", "series_id": "cs_0698x2v4abcdkq4m1n7r3b5c8d", "asset": { "id": "sub_0698x2v1abcdkq4m1n7r3b5c8d", "type": "substation", "name": "Mercator", "slug": "mercator-150kv", "country": "BE", "operator": { "id": "op_0698x2v0abcdkq4m1n7r3b5c8d", "slug": "elia", "name": "Elia", "type": "TSO" }, "network_level": "transmission", "voltage_kv": 150, "location": { "type": "Point", "coordinates": [ 4.3517, 50.8503 ], "precision": "exact" }, "distance_km": 8.2 }, "direction": "offtake", "technology": "battery", "capacity": { "type": "available", "value": 42.5, "unit": "MW", "value_mw": 42.5, "qualifier": null, "status": null, "status_label": null }, "firmness": "flexible", "curtailment": { "max_annual_percent": 5 }, "horizon": { "type": "target_year", "year": 2028, "label": "Y+2" }, "scenario": null, "season": null, "variant": null, "details": {}, "methodology": { "id": "elia_ghc_2026", "title": "Elia grid hosting capacity", "capacity_basis": "operator_calculated", "network_state": "n_minus_1", "binding": false, "non_additive": true, "includes_reserved": true, "includes_allocated": null, "includes_pre_reserved": true, "includes_pending_requests": null, "comparability_class": "be_elia_ghc" }, "freshness": { "source_effective_at": "2026-09-01T00:00:00Z", "retrieved_at": "2026-09-25T04:12:51Z", "last_confirmed_at": "2026-09-25T04:12:51Z", "source_health": "healthy" }, "provenance": { "source_id": "be_elia_hosting_capacity", "source_record_id": "12345", "source_url": "https://www.elia.be/", "payload_sha256": "e3b0c442…", "license": "Elia open data licence", "rights_mode": "commercial_use_with_attribution" }, "access": { "status": "granted", "attribution": "Source: Elia" }, "decision_context": { "binding": false, "formal_connection_study_required": true, "source_indicative": true, "statement": "The operator's latest published dataset reports 42.5 MW under methodology elia_ghc_2026." } }, { "id": "cap_0698x2v5xyz9kq4m1n7r3b5c8d", "series_id": "cs_0698x2v4abcdkq4m1n7r3b5c8d", "asset": { "id": "sub_0698x2v1abcdkq4m1n7r3b5c8d", "type": "substation", "name": "Mercator", "slug": "mercator-150kv", "country": "BE", "operator": { "id": "op_0698x2v0abcdkq4m1n7r3b5c8d", "slug": "elia", "name": "Elia", "type": "TSO" }, "network_level": "transmission", "voltage_kv": 150, "location": { "type": "Point", "coordinates": [ 4.3517, 50.8503 ], "precision": "exact" }, "distance_km": 8.2 }, "direction": "offtake", "technology": "battery", "capacity": { "type": "available", "value": null, "unit": "MW", "value_mw": null, "qualifier": null, "status": null, "status_label": null }, "firmness": "flexible", "curtailment": { "max_annual_percent": 5 }, "horizon": { "type": "target_year", "year": 2028, "label": "Y+2" }, "scenario": null, "season": null, "variant": null, "details": {}, "methodology": { "id": "elia_ghc_2026", "title": "Elia grid hosting capacity", "capacity_basis": "operator_calculated", "network_state": "n_minus_1", "binding": false, "non_additive": true, "includes_reserved": true, "includes_allocated": null, "includes_pre_reserved": true, "includes_pending_requests": null, "comparability_class": "be_elia_ghc" }, "freshness": { "source_effective_at": "2026-09-01T00:00:00Z", "retrieved_at": "2026-09-25T04:12:51Z", "last_confirmed_at": "2026-09-25T04:12:51Z", "source_health": "healthy" }, "provenance": { "source_id": "be_elia_hosting_capacity", "source_record_id": "12345", "source_url": "https://www.elia.be/", "payload_sha256": null, "license": "Elia open data licence", "rights_mode": "pending_review" }, "access": { "status": "withheld", "reason": "pending_review", "source_url": "https://www.elia.be/" }, "decision_context": { "binding": false, "formal_connection_study_required": true, "source_indicative": true, "statement": "The operator publishes a value for this record under methodology elia_ghc_2026. It is withheld here because the source's rights mode is pending_review; read it in the operator's own publication." } } ], "pagination": { "has_more": true, "next_cursor": "eyJzIjoiLWNhcGFjaXR5Ii…", "limit": 50 }, "meta": { "request_id": "req_0199…", "warnings": [ "withheld_values: 1 record(s) on this page are listed without their value because the source's licence does not permit redistribution (see access.reason); include_withheld=false drops them" ], "comparability": "best_effort" } } } } }, "400": { "description": "Invalid parameter or cursor (`invalid_parameter`, `invalid_cursor`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_parameter": { "value": { "error": { "code": "invalid_parameter", "message": "Invalid value for min_capacity_mw (expected a number, got \"fifty\").", "request_id": "req_0199…", "details": {} } } }, "invalid_cursor": { "value": { "error": { "code": "invalid_cursor", "message": "The cursor is not valid for this request.", "request_id": "req_0199…", "details": {} } } } } } } }, "401": { "description": "Missing, malformed or revoked API key (`unauthorized`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "value": { "error": { "code": "unauthorized", "message": "The API key (or session) is missing, malformed or has been revoked.", "request_id": "req_0199…", "details": {} } } } } } } }, "403": { "description": "The plan does not include this capability or limit (`plan_required`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "plan_required": { "value": { "error": { "code": "plan_required", "message": "'history' requires the pro plan or above.", "request_id": "req_0199…", "details": { "capability": "history", "required_plan": "pro" }, "required_plan": "pro" } } } } } } }, "404": { "description": "Not found (`country_not_supported`, `operator_not_found`, `operator_not_supported`, `source_not_found`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "country_not_supported": { "value": { "error": { "code": "country_not_supported", "message": "No capacity data is published for country \"DE\" yet.", "request_id": "req_0199…", "details": { "country": "DE" } } } }, "operator_not_found": { "value": { "error": { "code": "operator_not_found", "message": "No operator is known by \"acme\".", "request_id": "req_0199…", "details": {} } } }, "operator_not_supported": { "value": { "error": { "code": "operator_not_supported", "message": "Operator \"stedin\" is known, but no data of theirs has been published here yet.", "request_id": "req_0199…", "details": {} } } }, "source_not_found": { "value": { "error": { "code": "source_not_found", "message": "No source has the id \"be_x\".", "request_id": "req_0199…", "details": {} } } } } } } }, "409": { "description": "Conflict with the state of the data (`source_not_available`, `source_data_stale`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "source_not_available": { "value": { "error": { "code": "source_not_available", "message": "Source \"be_x\" is disabled, listed without being fetched, or has never published.", "request_id": "req_0199…", "details": {} } } }, "source_data_stale": { "value": { "error": { "code": "source_data_stale", "message": "Records match, but none is as fresh as fresh_after asks.", "request_id": "req_0199…", "details": { "newest": "2026-06-30T00:00:00Z" } } } } } } } }, "422": { "description": "Not comparable (`capacity_semantics_not_comparable`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "capacity_semantics_not_comparable": { "value": { "error": { "code": "capacity_semantics_not_comparable", "message": "The requested sources cannot be compared under strict comparability mode.", "request_id": "req_0199…", "details": { "classes": [ "be_elia_ghc", "gb_ltds_headroom" ] } } } } } } } }, "429": { "description": "Rate limit or monthly quota exceeded (`rate_limit_exceeded`, `quota_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limit_exceeded": { "value": { "error": { "code": "rate_limit_exceeded", "message": "Too many requests.", "request_id": "req_0199…", "details": {} } } }, "quota_exceeded": { "value": { "error": { "code": "quota_exceeded", "message": "This month's request quota has been used.", "request_id": "req_0199…", "details": {} } } } } } } }, "451": { "description": "Unavailable for legal reasons (rights) (`source_rights_restricted`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "source_rights_restricted": { "value": { "error": { "code": "source_rights_restricted", "message": "Every source named in this request withholds its values.", "request_id": "req_0199…", "details": { "sources": [ { "source_id": "be_elia_hosting_capacity", "rights_mode": "pending_review", "source_url": "https://www.elia.be/" } ] } } } } } } } } }, "parameters": [ { "name": "country", "description": "ISO 3166-1 alpha-2, comma list. A country with nothing published is `country_not_supported`.", "schema": { "type": "string" }, "in": "query", "required": false }, { "name": "operator", "description": "Operator slug or `op_` id, comma list.", "schema": { "type": "string" }, "in": "query", "required": false }, { "name": "source", "description": "Source id, comma list. Naming only sources that withhold their values is `source_rights_restricted` (451).", "schema": { "type": "string" }, "in": "query", "required": false }, { "name": "asset_type", "description": "Asset type, comma list.", "schema": { "type": "string", "description": "comma list of: substation, node, busbar, feeder, transformer, congestion_zone, connection_point, grid_cell, area" }, "in": "query", "required": false }, { "name": "voltage_min_kv", "description": "Lowest nominal voltage, kV.", "schema": { "type": "number" }, "in": "query", "required": false }, { "name": "voltage_max_kv", "description": "Highest nominal voltage, kV.", "schema": { "type": "number" }, "in": "query", "required": false }, { "name": "direction", "description": "Direction, comma list.", "schema": { "type": "string", "description": "comma list of: injection, offtake, bidirectional, unknown" }, "in": "query", "required": false }, { "name": "technology", "description": "Technology, comma list.", "schema": { "type": "string", "description": "comma list of: generic_generation, generic_load, solar_pv, wind_onshore, wind_offshore, battery, storage_other, hydrogen, electrolyser, ev_charging, data_center, other, unknown" }, "in": "query", "required": false }, { "name": "availability_type", "description": "What the number counts, comma list. Search and nearby default to `available`.", "schema": { "type": "string", "description": "comma list of: available, requested, reserved, allocated, pre_reserved, connected, waitlisted, contracted, installed, total, unknown" }, "in": "query", "required": false }, { "name": "firmness", "description": "Firmness, comma list.", "schema": { "type": "string", "description": "comma list of: firm, flexible, conditional, unknown" }, "in": "query", "required": false }, { "name": "horizon", "description": "`snapshot`, a target year (`2028`) or the operator's label (`Y+2`).", "schema": { "type": "string" }, "in": "query", "required": false }, { "name": "curtailment_max_pct", "description": "Largest acceptable curtailment band. Firm series satisfy any value; series of unknown firmness never do.", "schema": { "type": "number" }, "in": "query", "required": false }, { "name": "min_capacity_mw", "description": "On `value_mw` only: an MVA figure never satisfies it. Withheld values never satisfy any numeric filter.", "schema": { "type": "number" }, "in": "query", "required": false }, { "name": "max_capacity_mw", "description": "On `value_mw` only.", "schema": { "type": "number" }, "in": "query", "required": false }, { "name": "unit", "description": "Unit as published, comma list. Nothing is converted.", "schema": { "type": "string", "description": "comma list of: MW, kW, MVA, kVA, A, GWh, count, percent, status" }, "in": "query", "required": false }, { "name": "min_capacity", "description": "On `value` in the one unit named by `unit` (required, exactly one): `unit=MVA&min_capacity=50`.", "schema": { "type": "number" }, "in": "query", "required": false }, { "name": "max_capacity", "description": "On `value` in the one unit named by `unit`.", "schema": { "type": "number" }, "in": "query", "required": false }, { "name": "status", "description": "Categorical status, comma list (unit=status sources).", "schema": { "type": "string", "description": "comma list of: available, limited, unavailable, waitlist, under_study, unknown" }, "in": "query", "required": false }, { "name": "as_of", "description": "Pro+. RFC 3339 timestamp or date (end of that day, UTC): what the latest published data said then, on our observation clock.", "schema": { "type": "string" }, "in": "query", "required": false }, { "name": "lat", "description": "Latitude, WGS84. With `lng`.", "schema": { "type": "number" }, "in": "query", "required": false }, { "name": "lng", "description": "Longitude, WGS84. With `lat`.", "schema": { "type": "number" }, "in": "query", "required": false }, { "name": "radius_km", "description": "Radius around lat/lng on the asset centroid. Default 10 whenever lat/lng are given. Capped per plan (25 / 50 / 250 / 500 / 1000 km): above the cap is `plan_required`.", "schema": { "type": "number" }, "in": "query", "required": false }, { "name": "bbox", "description": "`min_lon,min_lat,max_lon,max_lat`, WGS84 degrees.", "schema": { "type": "string" }, "in": "query", "required": false }, { "name": "fresh_after", "description": "Only records whose data is at least this recent (source_effective_at, else the source's last change). When records match but none is fresh enough: 409 `source_data_stale` with `details.newest`.", "schema": { "type": "string" }, "in": "query", "required": false }, { "name": "comparability", "description": "`best_effort` (default) returns mixed methodology classes with a warning; `strict` answers 422 unless every record shares one class; `raw` also returns records with unknown dimensions.", "schema": { "type": "string", "enum": [ "strict", "best_effort", "raw" ] }, "in": "query", "required": false }, { "name": "include_withheld", "description": "Default true: withheld records are listed without their value. false drops them.", "schema": { "type": "boolean" }, "in": "query", "required": false }, { "name": "sort", "description": "Sort order. Nulls (withheld values, unstated voltages) sort last either way.", "schema": { "type": "string", "enum": [ "capacity", "-capacity", "distance", "voltage", "-voltage", "name", "source_updated_at", "-source_updated_at", "observed_at", "-observed_at" ], "default": "-capacity" }, "in": "query", "required": false }, { "name": "limit", "description": "Rows per page. The maximum is set by your plan (20 / 100 / 200); asking for more is an error rather than a silent truncation.", "schema": { "type": "integer", "minimum": 1, "default": 50 }, "in": "query", "required": false }, { "name": "cursor", "description": "Opaque cursor from `pagination.next_cursor`. Omit for the first page. Bound to the sort it was minted under.", "schema": { "type": "string" }, "in": "query", "required": false } ] } }, "/v1/capacity/nearby": { "get": { "tags": [ "Capacity" ], "summary": "Capacity records near a point", "description": "As search, around `lat`/`lng` (required) within `radius_km` (default 10, capped per plan), sorted by distance; every asset carries `distance_km`.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CapacityRecord" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": [ { "id": "cap_0698x2v5xyz9kq4m1n7r3b5c8d", "series_id": "cs_0698x2v4abcdkq4m1n7r3b5c8d", "asset": { "id": "sub_0698x2v1abcdkq4m1n7r3b5c8d", "type": "substation", "name": "Mercator", "slug": "mercator-150kv", "country": "BE", "operator": { "id": "op_0698x2v0abcdkq4m1n7r3b5c8d", "slug": "elia", "name": "Elia", "type": "TSO" }, "network_level": "transmission", "voltage_kv": 150, "location": { "type": "Point", "coordinates": [ 4.3517, 50.8503 ], "precision": "exact" }, "distance_km": 8.2 }, "direction": "offtake", "technology": "battery", "capacity": { "type": "available", "value": 42.5, "unit": "MW", "value_mw": 42.5, "qualifier": null, "status": null, "status_label": null }, "firmness": "flexible", "curtailment": { "max_annual_percent": 5 }, "horizon": { "type": "target_year", "year": 2028, "label": "Y+2" }, "scenario": null, "season": null, "variant": null, "details": {}, "methodology": { "id": "elia_ghc_2026", "title": "Elia grid hosting capacity", "capacity_basis": "operator_calculated", "network_state": "n_minus_1", "binding": false, "non_additive": true, "includes_reserved": true, "includes_allocated": null, "includes_pre_reserved": true, "includes_pending_requests": null, "comparability_class": "be_elia_ghc" }, "freshness": { "source_effective_at": "2026-09-01T00:00:00Z", "retrieved_at": "2026-09-25T04:12:51Z", "last_confirmed_at": "2026-09-25T04:12:51Z", "source_health": "healthy" }, "provenance": { "source_id": "be_elia_hosting_capacity", "source_record_id": "12345", "source_url": "https://www.elia.be/", "payload_sha256": "e3b0c442…", "license": "Elia open data licence", "rights_mode": "commercial_use_with_attribution" }, "access": { "status": "granted", "attribution": "Source: Elia" }, "decision_context": { "binding": false, "formal_connection_study_required": true, "source_indicative": true, "statement": "The operator's latest published dataset reports 42.5 MW under methodology elia_ghc_2026." } }, { "id": "cap_0698x2v5xyz9kq4m1n7r3b5c8d", "series_id": "cs_0698x2v4abcdkq4m1n7r3b5c8d", "asset": { "id": "sub_0698x2v1abcdkq4m1n7r3b5c8d", "type": "substation", "name": "Mercator", "slug": "mercator-150kv", "country": "BE", "operator": { "id": "op_0698x2v0abcdkq4m1n7r3b5c8d", "slug": "elia", "name": "Elia", "type": "TSO" }, "network_level": "transmission", "voltage_kv": 150, "location": { "type": "Point", "coordinates": [ 4.3517, 50.8503 ], "precision": "exact" }, "distance_km": 8.2 }, "direction": "offtake", "technology": "battery", "capacity": { "type": "available", "value": null, "unit": "MW", "value_mw": null, "qualifier": null, "status": null, "status_label": null }, "firmness": "flexible", "curtailment": { "max_annual_percent": 5 }, "horizon": { "type": "target_year", "year": 2028, "label": "Y+2" }, "scenario": null, "season": null, "variant": null, "details": {}, "methodology": { "id": "elia_ghc_2026", "title": "Elia grid hosting capacity", "capacity_basis": "operator_calculated", "network_state": "n_minus_1", "binding": false, "non_additive": true, "includes_reserved": true, "includes_allocated": null, "includes_pre_reserved": true, "includes_pending_requests": null, "comparability_class": "be_elia_ghc" }, "freshness": { "source_effective_at": "2026-09-01T00:00:00Z", "retrieved_at": "2026-09-25T04:12:51Z", "last_confirmed_at": "2026-09-25T04:12:51Z", "source_health": "healthy" }, "provenance": { "source_id": "be_elia_hosting_capacity", "source_record_id": "12345", "source_url": "https://www.elia.be/", "payload_sha256": null, "license": "Elia open data licence", "rights_mode": "pending_review" }, "access": { "status": "withheld", "reason": "pending_review", "source_url": "https://www.elia.be/" }, "decision_context": { "binding": false, "formal_connection_study_required": true, "source_indicative": true, "statement": "The operator publishes a value for this record under methodology elia_ghc_2026. It is withheld here because the source's rights mode is pending_review; read it in the operator's own publication." } } ], "pagination": { "has_more": true, "next_cursor": "eyJzIjoiLWNhcGFjaXR5Ii…", "limit": 50 }, "meta": { "request_id": "req_0199…", "warnings": [ "withheld_values: 1 record(s) on this page are listed without their value because the source's licence does not permit redistribution (see access.reason); include_withheld=false drops them" ], "comparability": "best_effort" } } } } }, "400": { "description": "Invalid parameter or cursor (`invalid_parameter`, `invalid_cursor`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_parameter": { "value": { "error": { "code": "invalid_parameter", "message": "Invalid value for min_capacity_mw (expected a number, got \"fifty\").", "request_id": "req_0199…", "details": {} } } }, "invalid_cursor": { "value": { "error": { "code": "invalid_cursor", "message": "The cursor is not valid for this request.", "request_id": "req_0199…", "details": {} } } } } } } }, "401": { "description": "Missing, malformed or revoked API key (`unauthorized`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "value": { "error": { "code": "unauthorized", "message": "The API key (or session) is missing, malformed or has been revoked.", "request_id": "req_0199…", "details": {} } } } } } } }, "403": { "description": "The plan does not include this capability or limit (`plan_required`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "plan_required": { "value": { "error": { "code": "plan_required", "message": "'history' requires the pro plan or above.", "request_id": "req_0199…", "details": { "capability": "history", "required_plan": "pro" }, "required_plan": "pro" } } } } } } }, "404": { "description": "Not found (`country_not_supported`, `operator_not_found`, `operator_not_supported`, `source_not_found`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "country_not_supported": { "value": { "error": { "code": "country_not_supported", "message": "No capacity data is published for country \"DE\" yet.", "request_id": "req_0199…", "details": { "country": "DE" } } } }, "operator_not_found": { "value": { "error": { "code": "operator_not_found", "message": "No operator is known by \"acme\".", "request_id": "req_0199…", "details": {} } } }, "operator_not_supported": { "value": { "error": { "code": "operator_not_supported", "message": "Operator \"stedin\" is known, but no data of theirs has been published here yet.", "request_id": "req_0199…", "details": {} } } }, "source_not_found": { "value": { "error": { "code": "source_not_found", "message": "No source has the id \"be_x\".", "request_id": "req_0199…", "details": {} } } } } } } }, "409": { "description": "Conflict with the state of the data (`source_not_available`, `source_data_stale`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "source_not_available": { "value": { "error": { "code": "source_not_available", "message": "Source \"be_x\" is disabled, listed without being fetched, or has never published.", "request_id": "req_0199…", "details": {} } } }, "source_data_stale": { "value": { "error": { "code": "source_data_stale", "message": "Records match, but none is as fresh as fresh_after asks.", "request_id": "req_0199…", "details": { "newest": "2026-06-30T00:00:00Z" } } } } } } } }, "422": { "description": "Not comparable (`capacity_semantics_not_comparable`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "capacity_semantics_not_comparable": { "value": { "error": { "code": "capacity_semantics_not_comparable", "message": "The requested sources cannot be compared under strict comparability mode.", "request_id": "req_0199…", "details": { "classes": [ "be_elia_ghc", "gb_ltds_headroom" ] } } } } } } } }, "429": { "description": "Rate limit or monthly quota exceeded (`rate_limit_exceeded`, `quota_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limit_exceeded": { "value": { "error": { "code": "rate_limit_exceeded", "message": "Too many requests.", "request_id": "req_0199…", "details": {} } } }, "quota_exceeded": { "value": { "error": { "code": "quota_exceeded", "message": "This month's request quota has been used.", "request_id": "req_0199…", "details": {} } } } } } } }, "451": { "description": "Unavailable for legal reasons (rights) (`source_rights_restricted`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "source_rights_restricted": { "value": { "error": { "code": "source_rights_restricted", "message": "Every source named in this request withholds its values.", "request_id": "req_0199…", "details": { "sources": [ { "source_id": "be_elia_hosting_capacity", "rights_mode": "pending_review", "source_url": "https://www.elia.be/" } ] } } } } } } } } }, "parameters": [ { "name": "country", "description": "ISO 3166-1 alpha-2, comma list. A country with nothing published is `country_not_supported`.", "schema": { "type": "string" }, "in": "query", "required": false }, { "name": "operator", "description": "Operator slug or `op_` id, comma list.", "schema": { "type": "string" }, "in": "query", "required": false }, { "name": "source", "description": "Source id, comma list. Naming only sources that withhold their values is `source_rights_restricted` (451).", "schema": { "type": "string" }, "in": "query", "required": false }, { "name": "asset_type", "description": "Asset type, comma list.", "schema": { "type": "string", "description": "comma list of: substation, node, busbar, feeder, transformer, congestion_zone, connection_point, grid_cell, area" }, "in": "query", "required": false }, { "name": "voltage_min_kv", "description": "Lowest nominal voltage, kV.", "schema": { "type": "number" }, "in": "query", "required": false }, { "name": "voltage_max_kv", "description": "Highest nominal voltage, kV.", "schema": { "type": "number" }, "in": "query", "required": false }, { "name": "direction", "description": "Direction, comma list.", "schema": { "type": "string", "description": "comma list of: injection, offtake, bidirectional, unknown" }, "in": "query", "required": false }, { "name": "technology", "description": "Technology, comma list.", "schema": { "type": "string", "description": "comma list of: generic_generation, generic_load, solar_pv, wind_onshore, wind_offshore, battery, storage_other, hydrogen, electrolyser, ev_charging, data_center, other, unknown" }, "in": "query", "required": false }, { "name": "availability_type", "description": "What the number counts, comma list. Search and nearby default to `available`.", "schema": { "type": "string", "description": "comma list of: available, requested, reserved, allocated, pre_reserved, connected, waitlisted, contracted, installed, total, unknown" }, "in": "query", "required": false }, { "name": "firmness", "description": "Firmness, comma list.", "schema": { "type": "string", "description": "comma list of: firm, flexible, conditional, unknown" }, "in": "query", "required": false }, { "name": "horizon", "description": "`snapshot`, a target year (`2028`) or the operator's label (`Y+2`).", "schema": { "type": "string" }, "in": "query", "required": false }, { "name": "curtailment_max_pct", "description": "Largest acceptable curtailment band. Firm series satisfy any value; series of unknown firmness never do.", "schema": { "type": "number" }, "in": "query", "required": false }, { "name": "min_capacity_mw", "description": "On `value_mw` only: an MVA figure never satisfies it. Withheld values never satisfy any numeric filter.", "schema": { "type": "number" }, "in": "query", "required": false }, { "name": "max_capacity_mw", "description": "On `value_mw` only.", "schema": { "type": "number" }, "in": "query", "required": false }, { "name": "unit", "description": "Unit as published, comma list. Nothing is converted.", "schema": { "type": "string", "description": "comma list of: MW, kW, MVA, kVA, A, GWh, count, percent, status" }, "in": "query", "required": false }, { "name": "min_capacity", "description": "On `value` in the one unit named by `unit` (required, exactly one): `unit=MVA&min_capacity=50`.", "schema": { "type": "number" }, "in": "query", "required": false }, { "name": "max_capacity", "description": "On `value` in the one unit named by `unit`.", "schema": { "type": "number" }, "in": "query", "required": false }, { "name": "status", "description": "Categorical status, comma list (unit=status sources).", "schema": { "type": "string", "description": "comma list of: available, limited, unavailable, waitlist, under_study, unknown" }, "in": "query", "required": false }, { "name": "as_of", "description": "Pro+. RFC 3339 timestamp or date (end of that day, UTC): what the latest published data said then, on our observation clock.", "schema": { "type": "string" }, "in": "query", "required": false }, { "name": "lat", "description": "Latitude, WGS84. With `lng`.", "schema": { "type": "number" }, "in": "query", "required": false }, { "name": "lng", "description": "Longitude, WGS84. With `lat`.", "schema": { "type": "number" }, "in": "query", "required": false }, { "name": "radius_km", "description": "Radius around lat/lng on the asset centroid. Default 10 whenever lat/lng are given. Capped per plan (25 / 50 / 250 / 500 / 1000 km): above the cap is `plan_required`.", "schema": { "type": "number" }, "in": "query", "required": false }, { "name": "bbox", "description": "`min_lon,min_lat,max_lon,max_lat`, WGS84 degrees.", "schema": { "type": "string" }, "in": "query", "required": false }, { "name": "fresh_after", "description": "Only records whose data is at least this recent (source_effective_at, else the source's last change). When records match but none is fresh enough: 409 `source_data_stale` with `details.newest`.", "schema": { "type": "string" }, "in": "query", "required": false }, { "name": "comparability", "description": "`best_effort` (default) returns mixed methodology classes with a warning; `strict` answers 422 unless every record shares one class; `raw` also returns records with unknown dimensions.", "schema": { "type": "string", "enum": [ "strict", "best_effort", "raw" ] }, "in": "query", "required": false }, { "name": "include_withheld", "description": "Default true: withheld records are listed without their value. false drops them.", "schema": { "type": "boolean" }, "in": "query", "required": false }, { "name": "sort", "description": "Sort order. Nulls (withheld values, unstated voltages) sort last either way.", "schema": { "type": "string", "enum": [ "capacity", "-capacity", "distance", "voltage", "-voltage", "name", "source_updated_at", "-source_updated_at", "observed_at", "-observed_at" ], "default": "distance" }, "in": "query", "required": false }, { "name": "limit", "description": "Rows per page. The maximum is set by your plan (20 / 100 / 200); asking for more is an error rather than a silent truncation.", "schema": { "type": "integer", "minimum": 1, "default": 50 }, "in": "query", "required": false }, { "name": "cursor", "description": "Opaque cursor from `pagination.next_cursor`. Omit for the first page. Bound to the sort it was minted under.", "schema": { "type": "string" }, "in": "query", "required": false } ] } }, "/v1/changes": { "get": { "tags": [ "Changes" ], "summary": "The change feed", "description": "Pro+. Every added, changed, removed and restored value, oldest first. The id is the cursor: resume with `since=` (or `cursor=`). Withheld values are null.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Change" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "description": "Invalid parameter or cursor (`invalid_parameter`, `invalid_cursor`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_parameter": { "value": { "error": { "code": "invalid_parameter", "message": "Invalid value for min_capacity_mw (expected a number, got \"fifty\").", "request_id": "req_0199…", "details": {} } } }, "invalid_cursor": { "value": { "error": { "code": "invalid_cursor", "message": "The cursor is not valid for this request.", "request_id": "req_0199…", "details": {} } } } } } } }, "401": { "description": "Missing, malformed or revoked API key (`unauthorized`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "value": { "error": { "code": "unauthorized", "message": "The API key (or session) is missing, malformed or has been revoked.", "request_id": "req_0199…", "details": {} } } } } } } }, "403": { "description": "The plan does not include this capability or limit (`plan_required`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "plan_required": { "value": { "error": { "code": "plan_required", "message": "'history' requires the pro plan or above.", "request_id": "req_0199…", "details": { "capability": "history", "required_plan": "pro" }, "required_plan": "pro" } } } } } } }, "404": { "description": "Not found (`country_not_supported`, `operator_not_found`, `source_not_found`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "country_not_supported": { "value": { "error": { "code": "country_not_supported", "message": "No capacity data is published for country \"DE\" yet.", "request_id": "req_0199…", "details": { "country": "DE" } } } }, "operator_not_found": { "value": { "error": { "code": "operator_not_found", "message": "No operator is known by \"acme\".", "request_id": "req_0199…", "details": {} } } }, "source_not_found": { "value": { "error": { "code": "source_not_found", "message": "No source has the id \"be_x\".", "request_id": "req_0199…", "details": {} } } } } } } }, "409": { "description": "Conflict with the state of the data (`source_not_available`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "source_not_available": { "value": { "error": { "code": "source_not_available", "message": "Source \"be_x\" is disabled, listed without being fetched, or has never published.", "request_id": "req_0199…", "details": {} } } } } } } }, "429": { "description": "Rate limit or monthly quota exceeded (`rate_limit_exceeded`, `quota_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limit_exceeded": { "value": { "error": { "code": "rate_limit_exceeded", "message": "Too many requests.", "request_id": "req_0199…", "details": {} } } }, "quota_exceeded": { "value": { "error": { "code": "quota_exceeded", "message": "This month's request quota has been used.", "request_id": "req_0199…", "details": {} } } } } } } }, "451": { "description": "Unavailable for legal reasons (rights) (`source_rights_restricted`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "source_rights_restricted": { "value": { "error": { "code": "source_rights_restricted", "message": "Every source named in this request withholds its values.", "request_id": "req_0199…", "details": { "sources": [ { "source_id": "be_elia_hosting_capacity", "rights_mode": "pending_review", "source_url": "https://www.elia.be/" } ] } } } } } } } } }, "parameters": [ { "name": "since", "description": "A change id, or an RFC 3339 timestamp / date.", "schema": { "type": "string" }, "in": "query", "required": false }, { "name": "country", "description": "ISO 3166-1 alpha-2, comma list. A country with nothing published is `country_not_supported`.", "schema": { "type": "string" }, "in": "query", "required": false }, { "name": "operator", "description": "Operator slug or `op_` id, comma list.", "schema": { "type": "string" }, "in": "query", "required": false }, { "name": "source", "description": "Source id, comma list. Naming only sources that withhold their values is `source_rights_restricted` (451).", "schema": { "type": "string" }, "in": "query", "required": false }, { "name": "change_type", "description": "Comma list of added, changed, removed, restored.", "schema": { "type": "string" }, "in": "query", "required": false }, { "name": "limit", "description": "Rows per page. The maximum is set by your plan (20 / 100 / 200); asking for more is an error rather than a silent truncation.", "schema": { "type": "integer", "minimum": 1, "default": 50 }, "in": "query", "required": false }, { "name": "cursor", "description": "The last change id seen (`pagination.next_cursor`).", "schema": { "type": "string" }, "in": "query", "required": false } ] } }, "/v1/postcodes/{country}/{postcode}": { "get": { "tags": [ "Capacity" ], "summary": "Areas serving a postcode", "description": "The areas an operator says serve a postcode (the Dutch national map publishes this for every PC6), each with its current capacity records. A mapping is served only from a source whose rights grant its data; mappings from other sources are omitted and counted in `meta.warnings` (`withheld_mappings`), and a postcode only such sources map is `source_rights_restricted`.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PostcodeLookup" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "description": "Invalid parameter or cursor (`invalid_parameter`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_parameter": { "value": { "error": { "code": "invalid_parameter", "message": "Invalid value for min_capacity_mw (expected a number, got \"fifty\").", "request_id": "req_0199…", "details": {} } } } } } } }, "401": { "description": "Missing, malformed or revoked API key (`unauthorized`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "value": { "error": { "code": "unauthorized", "message": "The API key (or session) is missing, malformed or has been revoked.", "request_id": "req_0199…", "details": {} } } } } } } }, "404": { "description": "Not found (`country_not_supported`, `capacity_not_available`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "country_not_supported": { "value": { "error": { "code": "country_not_supported", "message": "No capacity data is published for country \"DE\" yet.", "request_id": "req_0199…", "details": { "country": "DE" } } } }, "capacity_not_available": { "value": { "error": { "code": "capacity_not_available", "message": "The operator publishes no capacity figures for sub_….", "request_id": "req_0199…", "details": {} } } } } } } }, "429": { "description": "Rate limit or monthly quota exceeded (`rate_limit_exceeded`, `quota_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limit_exceeded": { "value": { "error": { "code": "rate_limit_exceeded", "message": "Too many requests.", "request_id": "req_0199…", "details": {} } } }, "quota_exceeded": { "value": { "error": { "code": "quota_exceeded", "message": "This month's request quota has been used.", "request_id": "req_0199…", "details": {} } } } } } } }, "451": { "description": "Unavailable for legal reasons (rights) (`source_rights_restricted`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "source_rights_restricted": { "value": { "error": { "code": "source_rights_restricted", "message": "Every source named in this request withholds its values.", "request_id": "req_0199…", "details": { "sources": [ { "source_id": "be_elia_hosting_capacity", "rights_mode": "pending_review", "source_url": "https://www.elia.be/" } ] } } } } } } } } }, "parameters": [ { "name": "country", "description": "ISO 3166-1 alpha-2.", "schema": { "type": "string" }, "in": "path", "required": true }, { "name": "postcode", "description": "As written; whitespace and case are ignored (`1234 ab`).", "schema": { "type": "string" }, "in": "path", "required": true } ] } }, "/v1/exports": { "get": { "tags": [ "Exports" ], "summary": "Your exports", "description": "Business+. Newest first.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Export" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "description": "Invalid parameter or cursor (`invalid_parameter`, `invalid_cursor`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_parameter": { "value": { "error": { "code": "invalid_parameter", "message": "Invalid value for min_capacity_mw (expected a number, got \"fifty\").", "request_id": "req_0199…", "details": {} } } }, "invalid_cursor": { "value": { "error": { "code": "invalid_cursor", "message": "The cursor is not valid for this request.", "request_id": "req_0199…", "details": {} } } } } } } }, "401": { "description": "Missing, malformed or revoked API key (`unauthorized`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "value": { "error": { "code": "unauthorized", "message": "The API key (or session) is missing, malformed or has been revoked.", "request_id": "req_0199…", "details": {} } } } } } } }, "403": { "description": "The plan does not include this capability or limit (`plan_required`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "plan_required": { "value": { "error": { "code": "plan_required", "message": "'history' requires the pro plan or above.", "request_id": "req_0199…", "details": { "capability": "history", "required_plan": "pro" }, "required_plan": "pro" } } } } } } }, "429": { "description": "Rate limit or monthly quota exceeded (`rate_limit_exceeded`, `quota_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limit_exceeded": { "value": { "error": { "code": "rate_limit_exceeded", "message": "Too many requests.", "request_id": "req_0199…", "details": {} } } }, "quota_exceeded": { "value": { "error": { "code": "quota_exceeded", "message": "This month's request quota has been used.", "request_id": "req_0199…", "details": {} } } } } } } } }, "parameters": [ { "name": "limit", "description": "Rows per page. The maximum is set by your plan (20 / 100 / 200); asking for more is an error rather than a silent truncation.", "schema": { "type": "integer", "minimum": 1, "default": 50 }, "in": "query", "required": false }, { "name": "cursor", "description": "Opaque cursor from `pagination.next_cursor`. Omit for the first page. Bound to the sort it was minted under.", "schema": { "type": "string" }, "in": "query", "required": false } ] }, "post": { "tags": [ "Exports" ], "summary": "Create an export", "description": "Business+. An asynchronous job: `kind` (capacity_current | capacity_history | substations | changes), `format` (csv | jsonl | geojson — geojson for capacity_current and substations) and `filters`, the matching list route's query parameters as a JSON object. Built by the worker with the same queries and rights as the API; kept 7 days, and expired early if a source's rights change. At most 3 queued or running per account (`export_limit_exceeded`).", "responses": { "202": { "description": "Accepted: queued", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Export" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "description": "Invalid parameter or cursor (`invalid_parameter`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_parameter": { "value": { "error": { "code": "invalid_parameter", "message": "Invalid value for min_capacity_mw (expected a number, got \"fifty\").", "request_id": "req_0199…", "details": {} } } } } } } }, "401": { "description": "Missing, malformed or revoked API key (`unauthorized`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "value": { "error": { "code": "unauthorized", "message": "The API key (or session) is missing, malformed or has been revoked.", "request_id": "req_0199…", "details": {} } } } } } } }, "403": { "description": "The plan does not include this capability or limit (`plan_required`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "plan_required": { "value": { "error": { "code": "plan_required", "message": "'history' requires the pro plan or above.", "request_id": "req_0199…", "details": { "capability": "history", "required_plan": "pro" }, "required_plan": "pro" } } } } } } }, "404": { "description": "Not found (`country_not_supported`, `operator_not_found`, `source_not_found`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "country_not_supported": { "value": { "error": { "code": "country_not_supported", "message": "No capacity data is published for country \"DE\" yet.", "request_id": "req_0199…", "details": { "country": "DE" } } } }, "operator_not_found": { "value": { "error": { "code": "operator_not_found", "message": "No operator is known by \"acme\".", "request_id": "req_0199…", "details": {} } } }, "source_not_found": { "value": { "error": { "code": "source_not_found", "message": "No source has the id \"be_x\".", "request_id": "req_0199…", "details": {} } } } } } } }, "409": { "description": "Conflict with the state of the data (`source_not_available`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "source_not_available": { "value": { "error": { "code": "source_not_available", "message": "Source \"be_x\" is disabled, listed without being fetched, or has never published.", "request_id": "req_0199…", "details": {} } } } } } } }, "429": { "description": "Rate limit or monthly quota exceeded (`rate_limit_exceeded`, `quota_exceeded`, `export_limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limit_exceeded": { "value": { "error": { "code": "rate_limit_exceeded", "message": "Too many requests.", "request_id": "req_0199…", "details": {} } } }, "quota_exceeded": { "value": { "error": { "code": "quota_exceeded", "message": "This month's request quota has been used.", "request_id": "req_0199…", "details": {} } } }, "export_limit_exceeded": { "value": { "error": { "code": "export_limit_exceeded", "message": "This account already has 3 exports queued or running.", "request_id": "req_0199…", "details": { "limit": 3 } } } } } } } }, "451": { "description": "Unavailable for legal reasons (rights) (`source_rights_restricted`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "source_rights_restricted": { "value": { "error": { "code": "source_rights_restricted", "message": "Every source named in this request withholds its values.", "request_id": "req_0199…", "details": { "sources": [ { "source_id": "be_elia_hosting_capacity", "rights_mode": "pending_review", "source_url": "https://www.elia.be/" } ] } } } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "kind", "format" ], "properties": { "kind": { "type": "string", "enum": [ "capacity_current", "capacity_history", "substations", "changes" ] }, "format": { "type": "string", "enum": [ "csv", "jsonl", "geojson" ] }, "filters": { "type": "object" } } }, "example": { "kind": "capacity_current", "format": "csv", "filters": { "country": "GB", "direction": "injection", "min_capacity_mw": 10 } } } } } } }, "/v1/exports/{id}": { "get": { "tags": [ "Exports" ], "summary": "Export status", "description": "Business+. `download_url` is set once it has succeeded.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Export" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "description": "Invalid parameter or cursor (`invalid_parameter`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_parameter": { "value": { "error": { "code": "invalid_parameter", "message": "Invalid value for min_capacity_mw (expected a number, got \"fifty\").", "request_id": "req_0199…", "details": {} } } } } } } }, "401": { "description": "Missing, malformed or revoked API key (`unauthorized`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "value": { "error": { "code": "unauthorized", "message": "The API key (or session) is missing, malformed or has been revoked.", "request_id": "req_0199…", "details": {} } } } } } } }, "403": { "description": "The plan does not include this capability or limit (`plan_required`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "plan_required": { "value": { "error": { "code": "plan_required", "message": "'history' requires the pro plan or above.", "request_id": "req_0199…", "details": { "capability": "history", "required_plan": "pro" }, "required_plan": "pro" } } } } } } }, "404": { "description": "Not found (`export_not_found`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "export_not_found": { "value": { "error": { "code": "export_not_found", "message": "No export with that id belongs to this account.", "request_id": "req_0199…", "details": {} } } } } } } }, "429": { "description": "Rate limit or monthly quota exceeded (`rate_limit_exceeded`, `quota_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limit_exceeded": { "value": { "error": { "code": "rate_limit_exceeded", "message": "Too many requests.", "request_id": "req_0199…", "details": {} } } }, "quota_exceeded": { "value": { "error": { "code": "quota_exceeded", "message": "This month's request quota has been used.", "request_id": "req_0199…", "details": {} } } } } } } } }, "parameters": [ { "name": "id", "description": "An `exp_` id.", "schema": { "type": "string" }, "in": "path", "required": true } ] } }, "/v1/exports/{id}/download": { "get": { "tags": [ "Exports" ], "summary": "Download an export", "description": "Business+. The file, streamed: `text/csv`, `application/x-ndjson` or `application/geo+json`. A few downloads run at once across the service; one more is `download_limit_exceeded` with `Retry-After`.", "responses": { "200": { "description": "Success", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid parameter or cursor (`invalid_parameter`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_parameter": { "value": { "error": { "code": "invalid_parameter", "message": "Invalid value for min_capacity_mw (expected a number, got \"fifty\").", "request_id": "req_0199…", "details": {} } } } } } } }, "401": { "description": "Missing, malformed or revoked API key (`unauthorized`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "value": { "error": { "code": "unauthorized", "message": "The API key (or session) is missing, malformed or has been revoked.", "request_id": "req_0199…", "details": {} } } } } } } }, "403": { "description": "The plan does not include this capability or limit (`plan_required`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "plan_required": { "value": { "error": { "code": "plan_required", "message": "'history' requires the pro plan or above.", "request_id": "req_0199…", "details": { "capability": "history", "required_plan": "pro" }, "required_plan": "pro" } } } } } } }, "404": { "description": "Not found (`export_not_found`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "export_not_found": { "value": { "error": { "code": "export_not_found", "message": "No export with that id belongs to this account.", "request_id": "req_0199…", "details": {} } } } } } } }, "409": { "description": "Conflict with the state of the data (`export_not_ready`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "export_not_ready": { "value": { "error": { "code": "export_not_ready", "message": "The export is running; there is no file to download.", "request_id": "req_0199…", "details": { "status": "running", "error": null } } } } } } } }, "410": { "description": "Gone (`export_expired`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "export_expired": { "value": { "error": { "code": "export_expired", "message": "The export has expired. Create it again.", "request_id": "req_0199…", "details": {} } } } } } } }, "429": { "description": "Rate limit or monthly quota exceeded (`rate_limit_exceeded`, `quota_exceeded`, `download_limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limit_exceeded": { "value": { "error": { "code": "rate_limit_exceeded", "message": "Too many requests.", "request_id": "req_0199…", "details": {} } } }, "quota_exceeded": { "value": { "error": { "code": "quota_exceeded", "message": "This month's request quota has been used.", "request_id": "req_0199…", "details": {} } } }, "download_limit_exceeded": { "value": { "error": { "code": "download_limit_exceeded", "message": "Every export download slot is in use.", "request_id": "req_0199…", "details": {} } } } } } } } }, "parameters": [ { "name": "id", "description": "An `exp_` id.", "schema": { "type": "string" }, "in": "path", "required": true } ] } }, "/v1/webhooks": { "get": { "tags": [ "Webhooks" ], "summary": "Your webhooks", "description": "Business+. Never includes the secret.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "description": "Invalid parameter or cursor (`invalid_parameter`, `invalid_cursor`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_parameter": { "value": { "error": { "code": "invalid_parameter", "message": "Invalid value for min_capacity_mw (expected a number, got \"fifty\").", "request_id": "req_0199…", "details": {} } } }, "invalid_cursor": { "value": { "error": { "code": "invalid_cursor", "message": "The cursor is not valid for this request.", "request_id": "req_0199…", "details": {} } } } } } } }, "401": { "description": "Missing, malformed or revoked API key (`unauthorized`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "value": { "error": { "code": "unauthorized", "message": "The API key (or session) is missing, malformed or has been revoked.", "request_id": "req_0199…", "details": {} } } } } } } }, "403": { "description": "The plan does not include this capability or limit (`plan_required`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "plan_required": { "value": { "error": { "code": "plan_required", "message": "'history' requires the pro plan or above.", "request_id": "req_0199…", "details": { "capability": "history", "required_plan": "pro" }, "required_plan": "pro" } } } } } } }, "429": { "description": "Rate limit or monthly quota exceeded (`rate_limit_exceeded`, `quota_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limit_exceeded": { "value": { "error": { "code": "rate_limit_exceeded", "message": "Too many requests.", "request_id": "req_0199…", "details": {} } } }, "quota_exceeded": { "value": { "error": { "code": "quota_exceeded", "message": "This month's request quota has been used.", "request_id": "req_0199…", "details": {} } } } } } } } }, "parameters": [ { "name": "limit", "description": "Rows per page. The maximum is set by your plan (20 / 100 / 200); asking for more is an error rather than a silent truncation.", "schema": { "type": "integer", "minimum": 1, "default": 50 }, "in": "query", "required": false }, { "name": "cursor", "description": "Opaque cursor from `pagination.next_cursor`. Omit for the first page. Bound to the sort it was minted under.", "schema": { "type": "string" }, "in": "query", "required": false } ] }, "post": { "tags": [ "Webhooks" ], "summary": "Create a webhook", "description": "Business+. `url` must be https and public. Deliveries are POSTed JSON with `GridCapacity-Signature: t=,v1=.\">`. The secret is returned here once.", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/WebhookWithSecret" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "description": "Invalid parameter or cursor (`invalid_parameter`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_parameter": { "value": { "error": { "code": "invalid_parameter", "message": "Invalid value for min_capacity_mw (expected a number, got \"fifty\").", "request_id": "req_0199…", "details": {} } } } } } } }, "401": { "description": "Missing, malformed or revoked API key (`unauthorized`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "value": { "error": { "code": "unauthorized", "message": "The API key (or session) is missing, malformed or has been revoked.", "request_id": "req_0199…", "details": {} } } } } } } }, "403": { "description": "The plan does not include this capability or limit (`plan_required`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "plan_required": { "value": { "error": { "code": "plan_required", "message": "'history' requires the pro plan or above.", "request_id": "req_0199…", "details": { "capability": "history", "required_plan": "pro" }, "required_plan": "pro" } } } } } } }, "404": { "description": "Not found (`country_not_supported`, `operator_not_found`, `source_not_found`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "country_not_supported": { "value": { "error": { "code": "country_not_supported", "message": "No capacity data is published for country \"DE\" yet.", "request_id": "req_0199…", "details": { "country": "DE" } } } }, "operator_not_found": { "value": { "error": { "code": "operator_not_found", "message": "No operator is known by \"acme\".", "request_id": "req_0199…", "details": {} } } }, "source_not_found": { "value": { "error": { "code": "source_not_found", "message": "No source has the id \"be_x\".", "request_id": "req_0199…", "details": {} } } } } } } }, "429": { "description": "Rate limit or monthly quota exceeded (`rate_limit_exceeded`, `quota_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limit_exceeded": { "value": { "error": { "code": "rate_limit_exceeded", "message": "Too many requests.", "request_id": "req_0199…", "details": {} } } }, "quota_exceeded": { "value": { "error": { "code": "quota_exceeded", "message": "This month's request quota has been used.", "request_id": "req_0199…", "details": {} } } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string" }, "filters": { "type": "object" } } }, "example": { "url": "https://hooks.example.com/grid", "filters": { "countries": [ "NL" ], "change_types": [ "changed", "added" ] } } } } } } }, "/v1/webhooks/{id}": { "delete": { "tags": [ "Webhooks" ], "summary": "Delete a webhook", "description": "Business+. Pending deliveries are dropped.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Deleted" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "description": "Invalid parameter or cursor (`invalid_parameter`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_parameter": { "value": { "error": { "code": "invalid_parameter", "message": "Invalid value for min_capacity_mw (expected a number, got \"fifty\").", "request_id": "req_0199…", "details": {} } } } } } } }, "401": { "description": "Missing, malformed or revoked API key (`unauthorized`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "value": { "error": { "code": "unauthorized", "message": "The API key (or session) is missing, malformed or has been revoked.", "request_id": "req_0199…", "details": {} } } } } } } }, "403": { "description": "The plan does not include this capability or limit (`plan_required`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "plan_required": { "value": { "error": { "code": "plan_required", "message": "'history' requires the pro plan or above.", "request_id": "req_0199…", "details": { "capability": "history", "required_plan": "pro" }, "required_plan": "pro" } } } } } } }, "404": { "description": "Not found (`webhook_not_found`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "webhook_not_found": { "value": { "error": { "code": "webhook_not_found", "message": "No webhook with that id belongs to this account.", "request_id": "req_0199…", "details": {} } } } } } } }, "429": { "description": "Rate limit or monthly quota exceeded (`rate_limit_exceeded`, `quota_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limit_exceeded": { "value": { "error": { "code": "rate_limit_exceeded", "message": "Too many requests.", "request_id": "req_0199…", "details": {} } } }, "quota_exceeded": { "value": { "error": { "code": "quota_exceeded", "message": "This month's request quota has been used.", "request_id": "req_0199…", "details": {} } } } } } } } }, "parameters": [ { "name": "id", "description": "A `wh_` id.", "schema": { "type": "string" }, "in": "path", "required": true } ] } }, "/v1/webhooks/{id}/rotate": { "post": { "tags": [ "Webhooks" ], "summary": "Rotate a webhook secret", "description": "Business+. The new secret is returned once and signs every later delivery; the old one stops at once.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/WebhookWithSecret" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "description": "Invalid parameter or cursor (`invalid_parameter`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_parameter": { "value": { "error": { "code": "invalid_parameter", "message": "Invalid value for min_capacity_mw (expected a number, got \"fifty\").", "request_id": "req_0199…", "details": {} } } } } } } }, "401": { "description": "Missing, malformed or revoked API key (`unauthorized`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "value": { "error": { "code": "unauthorized", "message": "The API key (or session) is missing, malformed or has been revoked.", "request_id": "req_0199…", "details": {} } } } } } } }, "403": { "description": "The plan does not include this capability or limit (`plan_required`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "plan_required": { "value": { "error": { "code": "plan_required", "message": "'history' requires the pro plan or above.", "request_id": "req_0199…", "details": { "capability": "history", "required_plan": "pro" }, "required_plan": "pro" } } } } } } }, "404": { "description": "Not found (`webhook_not_found`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "webhook_not_found": { "value": { "error": { "code": "webhook_not_found", "message": "No webhook with that id belongs to this account.", "request_id": "req_0199…", "details": {} } } } } } } }, "429": { "description": "Rate limit or monthly quota exceeded (`rate_limit_exceeded`, `quota_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limit_exceeded": { "value": { "error": { "code": "rate_limit_exceeded", "message": "Too many requests.", "request_id": "req_0199…", "details": {} } } }, "quota_exceeded": { "value": { "error": { "code": "quota_exceeded", "message": "This month's request quota has been used.", "request_id": "req_0199…", "details": {} } } } } } } } }, "parameters": [ { "name": "id", "description": "A `wh_` id.", "schema": { "type": "string" }, "in": "path", "required": true } ] } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Your API key: `Authorization: Bearer gc_live_...`. A `gc_test_` key reaches the same data and counts against the same monthly quota: live and test are labels for your own systems." }, "apiKeyHeader": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "The same key, as a header." } }, "schemas": { "Meta": { "type": "object", "properties": { "request_id": { "type": "string" }, "comparability": { "type": [ "string", "null" ], "description": "On the capacity routes: the comparability mode the records were selected under." }, "warnings": { "type": "array", "items": { "type": "string" } } }, "required": [ "request_id", "warnings" ] }, "Pagination": { "type": "object", "properties": { "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] }, "limit": { "type": "integer", "format": "int64", "description": "The page size this response was built with." } }, "required": [ "has_more", "next_cursor", "limit" ] }, "Deleted": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean" } }, "required": [ "id", "deleted" ] }, "RunRequested": { "type": "object", "properties": { "source_id": { "type": "string" }, "next_due_at": { "type": [ "string", "null" ] } }, "required": [ "source_id", "next_due_at" ] }, "RunApproved": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64" }, "approved_by": { "type": "string" } }, "required": [ "id", "approved_by" ] }, "ReviewDecided": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64" }, "decision": { "type": "string" } }, "required": [ "id", "decision" ] }, "PlanCapabilities": { "type": "object", "properties": { "history": { "type": "boolean" }, "change_feed": { "type": "boolean" }, "as_of": { "type": "boolean" }, "bulk_exports": { "type": "boolean" }, "webhooks": { "type": "boolean" }, "redistribution_rights": { "type": "boolean" } }, "required": [ "history", "change_feed", "as_of", "bulk_exports", "webhooks", "redistribution_rights" ] }, "PlanOffer": { "type": "object", "properties": { "plan": { "type": "string" }, "label": { "type": "string" }, "price_monthly_eur": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0, "description": "Whole euros. `null` for a plan quoted rather than listed." }, "price_yearly_eur": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0, "description": "Whole euros. Ten months for twelve. `null` where there is no yearly price." }, "price_from_monthly_eur": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0, "description": "\"From €X a month\", for a quoted plan." }, "self_serve": { "type": "boolean", "description": "Free by registering, the paid plans through checkout. `false` means contact sales." }, "purchasable": { "type": "boolean", "description": "Bought through Stripe checkout." }, "monthly_requests": { "type": [ "integer", "null" ], "format": "int64", "description": "`null` means genuinely unlimited, not a very large number." }, "rate_limit_rps": { "type": "integer", "format": "int64", "minimum": 0 }, "api_keys": { "type": "integer", "format": "int64", "minimum": 0 }, "max_page_size": { "type": "integer", "format": "int32", "minimum": 0 }, "nearby_radius_km_max": { "type": "integer", "format": "int64", "minimum": 0 }, "capabilities": { "$ref": "#/components/schemas/PlanCapabilities" } }, "required": [ "plan", "label", "price_monthly_eur", "price_yearly_eur", "price_from_monthly_eur", "self_serve", "purchasable", "monthly_requests", "rate_limit_rps", "api_keys", "max_page_size", "nearby_radius_km_max", "capabilities" ] }, "PlanList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PlanOffer" } }, "currency": { "type": "string" }, "independence": { "type": "string" } }, "required": [ "data", "currency", "independence" ] }, "KeyInfo": { "type": "object", "properties": { "live": { "type": "boolean" }, "plan": { "$ref": "#/components/schemas/PlanOffer" }, "requests_this_month": { "type": "integer", "format": "int64", "description": "Requests counted against this month's quota, including this one. Test keys are metered like live ones." } }, "required": [ "live", "plan", "requests_this_month" ] }, "RestrictedSource": { "type": "object", "properties": { "source_id": { "type": "string" }, "rights_mode": { "type": "string" }, "source_url": { "type": "string" } }, "required": [ "source_id", "rights_mode", "source_url" ] }, "OperatorRef": { "type": "object", "properties": { "id": { "type": "string" }, "slug": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "TSO", "DSO", "TSO_DSO", "joint", "other" ] } }, "required": [ "id", "slug", "name", "type" ] }, "Location": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "Point" ] }, "coordinates": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2, "description": "`[lon, lat]`, WGS84." }, "precision": { "type": "string", "enum": [ "exact", "approximate", "obfuscated", "municipality", "region", "none", "unknown" ] } }, "required": [ "type", "coordinates", "precision" ] }, "AssetRef": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "substation", "node", "busbar", "feeder", "transformer", "congestion_zone", "connection_point", "grid_cell", "area" ] }, "name": { "type": "string" }, "slug": { "type": "string" }, "country": { "type": "string" }, "operator": { "$ref": "#/components/schemas/OperatorRef" }, "network_level": { "type": [ "string", "null" ] }, "voltage_kv": { "type": [ "number", "null" ], "format": "double" }, "location": { "oneOf": [ { "$ref": "#/components/schemas/Location" }, { "type": "null" } ] }, "distance_km": { "type": [ "number", "null" ], "format": "double", "description": "Only on nearby and radius queries. The contract types it as optional, so it is the one field that is absent rather than null when it does not apply." } }, "required": [ "id", "type", "name", "slug", "country", "operator", "network_level", "voltage_kv", "location" ] }, "MethodologyRef": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "capacity_basis": { "type": "string" }, "network_state": { "type": "string" }, "binding": { "type": "boolean" }, "non_additive": { "type": "boolean" }, "includes_reserved": { "type": [ "boolean", "null" ] }, "includes_allocated": { "type": [ "boolean", "null" ] }, "includes_pre_reserved": { "type": [ "boolean", "null" ] }, "includes_pending_requests": { "type": [ "boolean", "null" ] }, "comparability_class": { "type": "string" } }, "required": [ "id", "title", "capacity_basis", "network_state", "binding", "non_additive", "includes_reserved", "includes_allocated", "includes_pre_reserved", "includes_pending_requests", "comparability_class" ] }, "MethodologyDetail": { "allOf": [ { "$ref": "#/components/schemas/MethodologyRef" }, { "type": "object", "properties": { "summary": { "type": "string" }, "disclaimers": { "type": "array", "items": { "type": "string" } }, "documentation_url": { "type": [ "string", "null" ] }, "version": { "type": "string" } }, "required": [ "summary", "disclaimers", "documentation_url", "version" ] } ] }, "CountrySources": { "type": "object", "properties": { "total": { "type": "integer", "format": "int64" }, "granted": { "type": "integer", "format": "int64" }, "withheld": { "type": "integer", "format": "int64" } }, "required": [ "total", "granted", "withheld" ] }, "Country": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "coverage_status": { "type": "string", "enum": [ "live", "partial", "planned", "none" ] }, "operators": { "type": "integer", "format": "int64" }, "sources": { "$ref": "#/components/schemas/CountrySources" }, "assets": { "type": "integer", "format": "int64" }, "series": { "type": "integer", "format": "int64" }, "newest_source_effective_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "code", "name", "slug", "coverage_status", "operators", "sources", "assets", "series", "newest_source_effective_at" ] }, "CoverageTotals": { "type": "object", "properties": { "operators": { "type": "integer", "format": "int64" }, "sources": { "type": "integer", "format": "int64" }, "assets": { "type": "integer", "format": "int64" }, "series": { "type": "integer", "format": "int64" }, "observations": { "type": "integer", "format": "int64" } }, "required": [ "operators", "sources", "assets", "series", "observations" ] }, "Coverage": { "type": "object", "properties": { "countries": { "type": "array", "items": { "$ref": "#/components/schemas/Country" } }, "totals": { "$ref": "#/components/schemas/CoverageTotals" }, "generated_at": { "type": "string", "format": "date-time" } }, "required": [ "countries", "totals", "generated_at" ] }, "SourceSummary": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "country": { "type": "string" }, "operator": { "$ref": "#/components/schemas/OperatorRef" }, "landing_url": { "type": "string" }, "cadence": { "type": "string", "enum": [ "15min", "hourly", "daily", "weekly", "monthly", "quarterly", "semiannual", "annual", "ad_hoc", "unknown" ] }, "rights_mode": { "type": "string", "enum": [ "redistribution_allowed", "commercial_use_with_attribution", "derived_only", "internal_cache_only", "link_only", "pending_review", "blocked" ], "description": "The effective mode: `COALESCE(rights_override, rights_mode)`. What is enforced." }, "health": { "type": "string", "enum": [ "healthy", "stale", "degraded", "failing", "disabled", "unknown" ] }, "publication_status": { "type": "string", "enum": [ "published", "held" ] }, "last_success_at": { "type": [ "string", "null" ], "format": "date-time" }, "source_effective_at": { "type": [ "string", "null" ], "format": "date-time" }, "assets": { "type": "integer", "format": "int64" }, "series": { "type": "integer", "format": "int64" } }, "required": [ "id", "name", "country", "operator", "landing_url", "cadence", "rights_mode", "health", "publication_status", "last_success_at", "source_effective_at", "assets", "series" ] }, "Operator": { "allOf": [ { "$ref": "#/components/schemas/OperatorRef" }, { "type": "object", "properties": { "short_name": { "type": [ "string", "null" ] }, "country": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "eic_code": { "type": [ "string", "null" ] }, "covered": { "type": "boolean", "description": "At least one of its sources has published values we may serve." }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/SourceSummary" } }, "assets": { "type": "integer", "format": "int64" }, "registry": { "type": "object" } }, "required": [ "short_name", "country", "website", "eic_code", "covered", "sources", "assets", "registry" ] } ] }, "Evidence": { "type": "object", "properties": { "url": { "type": "string" }, "quote": { "type": "string" }, "retrieved_at": { "type": "string" } }, "required": [ "url", "quote", "retrieved_at" ] }, "SourceRights": { "type": "object", "properties": { "technical_access": { "type": "string", "enum": [ "yes", "no", "unknown" ] }, "commercial_use": { "type": "string", "enum": [ "yes", "no", "unknown" ] }, "cache_right": { "type": "string", "enum": [ "yes", "no", "unknown" ] }, "redistribution_right": { "type": "string", "enum": [ "yes", "no", "unknown" ] }, "derived_data_allowed": { "type": "string", "enum": [ "yes", "no", "unknown" ] }, "evidence": { "type": "array", "items": { "$ref": "#/components/schemas/Evidence" } }, "note": { "type": [ "string", "null" ] } }, "required": [ "technical_access", "commercial_use", "cache_right", "redistribution_right", "derived_data_allowed", "evidence", "note" ] }, "Source": { "allOf": [ { "$ref": "#/components/schemas/SourceSummary" }, { "type": "object", "properties": { "summary": { "type": "string" }, "acquisition_type": { "type": "string" }, "endpoint": { "type": [ "string", "null" ] }, "dataset_ref": { "type": [ "string", "null" ] }, "license_name": { "type": [ "string", "null" ] }, "license_url": { "type": [ "string", "null" ] }, "attribution_text": { "type": [ "string", "null" ] }, "attribution_required": { "type": "boolean" }, "rights": { "$ref": "#/components/schemas/SourceRights" }, "semantics": { "type": "object" }, "methodologies": { "type": "array", "items": { "$ref": "#/components/schemas/MethodologyDetail" } } }, "required": [ "summary", "acquisition_type", "endpoint", "dataset_ref", "license_name", "license_url", "attribution_text", "attribution_required", "rights", "semantics", "methodologies" ] } ] }, "LastRun": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64" }, "status": { "type": "string", "enum": [ "running", "published", "unchanged", "held", "failed", "abandoned" ] }, "started_at": { "type": "string", "format": "date-time" }, "finished_at": { "type": [ "string", "null" ], "format": "date-time" }, "hold_reasons": { "type": "array", "items": { "type": "string" }, "description": "The checks that held the run, by name, with how many items each found at fault where it counts them (`value_max (3)`). Never a check's detail: that is the operator's, on `/v1/admin/runs/{id}`." }, "outcome": { "type": "object" } }, "required": [ "id", "status", "started_at", "finished_at", "hold_reasons", "outcome" ] }, "SourceStatus": { "type": "object", "properties": { "source_id": { "type": "string" }, "health": { "type": "string", "enum": [ "healthy", "stale", "degraded", "failing", "disabled", "unknown" ] }, "publication_status": { "type": "string", "enum": [ "published", "held" ] }, "last_attempt_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_success_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_published_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_change_at": { "type": [ "string", "null" ], "format": "date-time" }, "source_effective_at": { "type": [ "string", "null" ], "format": "date-time" }, "freshness_seconds": { "type": [ "integer", "null" ], "format": "int64", "description": "Seconds since `coalesce(source_effective_at, last_change_at)`: how old the data is, not how recently we fetched it. `null` when neither is known." }, "stale_after_days": { "type": "integer", "format": "int64" }, "consecutive_failures": { "type": "integer", "format": "int32" }, "last_run": { "oneOf": [ { "$ref": "#/components/schemas/LastRun" }, { "type": "null" } ] } }, "required": [ "source_id", "health", "publication_status", "last_attempt_at", "last_success_at", "last_published_at", "last_change_at", "source_effective_at", "freshness_seconds", "stale_after_days", "consecutive_failures", "last_run" ] }, "CapacityValue": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "available", "requested", "reserved", "allocated", "pre_reserved", "connected", "waitlisted", "contracted", "installed", "total", "unknown" ] }, "value": { "type": [ "number", "null" ], "format": "double" }, "unit": { "type": "string", "enum": [ "MW", "kW", "MVA", "kVA", "A", "GWh", "count", "percent", "status" ] }, "value_mw": { "type": [ "number", "null" ], "format": "double" }, "qualifier": { "type": [ "string", "null" ] }, "status": { "oneOf": [ { "type": "string", "enum": [ "available", "limited", "unavailable", "waitlist", "under_study", "unknown" ] }, { "type": "null" } ] }, "status_label": { "type": [ "string", "null" ] } }, "required": [ "type", "value", "unit", "value_mw", "qualifier", "status", "status_label" ] }, "Curtailment": { "type": "object", "properties": { "max_annual_percent": { "type": "number", "format": "double" } }, "required": [ "max_annual_percent" ] }, "Horizon": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "snapshot", "target_year", "period" ] }, "year": { "type": [ "integer", "null" ], "format": "int32" }, "label": { "type": [ "string", "null" ] } }, "required": [ "type", "year", "label" ] }, "Freshness": { "type": "object", "properties": { "source_effective_at": { "type": [ "string", "null" ], "format": "date-time" }, "retrieved_at": { "type": "string", "format": "date-time", "description": "When we first retrieved the value as it now stands (the start of its observation interval)." }, "last_confirmed_at": { "type": "string", "format": "date-time" }, "source_health": { "type": "string", "enum": [ "healthy", "stale", "degraded", "failing", "disabled", "unknown" ] } }, "required": [ "source_effective_at", "retrieved_at", "last_confirmed_at", "source_health" ] }, "Provenance": { "type": "object", "properties": { "source_id": { "type": "string" }, "source_record_id": { "type": "string" }, "source_url": { "type": "string" }, "payload_sha256": { "type": [ "string", "null" ], "description": "SHA-256 of the operator's record as we stored it. `null` whenever the value is withheld: the hash of a small record confirms a guessed value, and a withheld value must not be confirmable either." }, "license": { "type": [ "string", "null" ] }, "rights_mode": { "type": "string", "enum": [ "redistribution_allowed", "commercial_use_with_attribution", "derived_only", "internal_cache_only", "link_only", "pending_review", "blocked" ] } }, "required": [ "source_id", "source_record_id", "source_url", "payload_sha256", "license", "rights_mode" ] }, "DecisionContext": { "type": "object", "properties": { "binding": { "type": "boolean" }, "formal_connection_study_required": { "type": "boolean", "const": true, "description": "Always true. No published figure is a connection offer." }, "source_indicative": { "type": "boolean" }, "statement": { "type": "string" } }, "required": [ "binding", "formal_connection_study_required", "source_indicative", "statement" ] }, "CapacityRecord": { "type": "object", "properties": { "id": { "type": "string" }, "series_id": { "type": "string" }, "asset": { "$ref": "#/components/schemas/AssetRef" }, "direction": { "type": "string", "enum": [ "injection", "offtake", "bidirectional", "unknown" ] }, "technology": { "type": "string", "enum": [ "generic_generation", "generic_load", "solar_pv", "wind_onshore", "wind_offshore", "battery", "storage_other", "hydrogen", "electrolyser", "ev_charging", "data_center", "other", "unknown" ] }, "capacity": { "$ref": "#/components/schemas/CapacityValue" }, "firmness": { "type": "string", "enum": [ "firm", "flexible", "conditional", "unknown" ] }, "curtailment": { "oneOf": [ { "$ref": "#/components/schemas/Curtailment" }, { "type": "null" } ] }, "horizon": { "$ref": "#/components/schemas/Horizon" }, "scenario": { "type": [ "string", "null" ] }, "season": { "type": [ "string", "null" ] }, "variant": { "type": [ "string", "null" ] }, "details": { "type": "object" }, "methodology": { "$ref": "#/components/schemas/MethodologyRef" }, "freshness": { "$ref": "#/components/schemas/Freshness" }, "provenance": { "$ref": "#/components/schemas/Provenance" }, "access": { "$ref": "#/components/schemas/Access" }, "decision_context": { "$ref": "#/components/schemas/DecisionContext" } }, "required": [ "id", "series_id", "asset", "direction", "technology", "capacity", "firmness", "curtailment", "horizon", "scenario", "season", "variant", "details", "methodology", "freshness", "provenance", "access", "decision_context" ] }, "Observation": { "type": "object", "properties": { "id": { "type": "string" }, "value": { "type": [ "number", "null" ], "format": "double" }, "value_mw": { "type": [ "number", "null" ], "format": "double" }, "qualifier": { "type": [ "string", "null" ] }, "status": { "oneOf": [ { "type": "string", "enum": [ "available", "limited", "unavailable", "waitlist", "under_study", "unknown" ] }, { "type": "null" } ] }, "status_label": { "type": [ "string", "null" ] }, "observed_from": { "type": "string", "format": "date-time" }, "observed_to": { "type": [ "string", "null" ], "format": "date-time" }, "source_effective_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "value", "value_mw", "qualifier", "status", "status_label", "observed_from", "observed_to", "source_effective_at" ] }, "SeriesHistory": { "type": "object", "properties": { "series_id": { "type": "string" }, "direction": { "type": "string", "enum": [ "injection", "offtake", "bidirectional", "unknown" ] }, "technology": { "type": "string", "enum": [ "generic_generation", "generic_load", "solar_pv", "wind_onshore", "wind_offshore", "battery", "storage_other", "hydrogen", "electrolyser", "ev_charging", "data_center", "other", "unknown" ] }, "availability_type": { "type": "string", "enum": [ "available", "requested", "reserved", "allocated", "pre_reserved", "connected", "waitlisted", "contracted", "installed", "total", "unknown" ] }, "firmness": { "type": "string", "enum": [ "firm", "flexible", "conditional", "unknown" ] }, "unit": { "type": "string", "enum": [ "MW", "kW", "MVA", "kVA", "A", "GWh", "count", "percent", "status" ] }, "horizon": { "$ref": "#/components/schemas/Horizon" }, "scenario": { "type": [ "string", "null" ] }, "season": { "type": [ "string", "null" ] }, "variant": { "type": [ "string", "null" ] }, "methodology_id": { "type": "string" }, "access": { "$ref": "#/components/schemas/Access" }, "observations": { "type": "array", "items": { "$ref": "#/components/schemas/Observation" } } }, "required": [ "series_id", "direction", "technology", "availability_type", "firmness", "unit", "horizon", "scenario", "season", "variant", "methodology_id", "access", "observations" ] }, "AssetSeriesHistory": { "allOf": [ { "$ref": "#/components/schemas/SeriesHistory" }, { "type": "object", "properties": { "asset": { "$ref": "#/components/schemas/AssetRef" } }, "required": [ "asset" ] } ] }, "Change": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "The cursor: strictly increasing, never reused." }, "change_type": { "type": "string", "enum": [ "added", "changed", "removed", "restored" ] }, "detected_at": { "type": "string", "format": "date-time" }, "source_effective_at": { "type": [ "string", "null" ], "format": "date-time" }, "series_id": { "type": "string" }, "asset": { "$ref": "#/components/schemas/AssetRef" }, "source_id": { "type": "string" }, "direction": { "type": "string", "enum": [ "injection", "offtake", "bidirectional", "unknown" ] }, "technology": { "type": "string", "enum": [ "generic_generation", "generic_load", "solar_pv", "wind_onshore", "wind_offshore", "battery", "storage_other", "hydrogen", "electrolyser", "ev_charging", "data_center", "other", "unknown" ] }, "availability_type": { "type": "string", "enum": [ "available", "requested", "reserved", "allocated", "pre_reserved", "connected", "waitlisted", "contracted", "installed", "total", "unknown" ] }, "unit": { "type": "string", "enum": [ "MW", "kW", "MVA", "kVA", "A", "GWh", "count", "percent", "status" ] }, "old_value": { "type": [ "number", "null" ], "format": "double" }, "new_value": { "type": [ "number", "null" ], "format": "double" }, "access": { "$ref": "#/components/schemas/Access" } }, "required": [ "id", "change_type", "detected_at", "source_effective_at", "series_id", "asset", "source_id", "direction", "technology", "availability_type", "unit", "old_value", "new_value", "access" ] }, "Identity": { "type": "object", "properties": { "source_id": { "type": "string" }, "source_asset_id": { "type": "string" }, "source_name": { "type": [ "string", "null" ] }, "source_url": { "type": [ "string", "null" ] }, "match_method": { "type": "string" } }, "required": [ "source_id", "source_asset_id", "source_name", "source_url", "match_method" ] }, "Related": { "type": "object", "properties": { "asset": { "$ref": "#/components/schemas/AssetRef" }, "relation": { "type": "string", "enum": [ "co_located", "feeds", "part_of_zone" ] } }, "required": [ "asset", "relation" ] }, "CapacitySummary": { "type": "object", "properties": { "series": { "type": "integer", "format": "int64" }, "withheld": { "type": "integer", "format": "int64" }, "sources": { "type": "array", "items": { "type": "string" } }, "last_changed_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "series", "withheld", "sources", "last_changed_at" ] }, "Substation": { "allOf": [ { "$ref": "#/components/schemas/AssetRef" }, { "type": "object", "properties": { "municipality": { "type": [ "string", "null" ] }, "region": { "type": [ "string", "null" ] }, "postcode": { "type": [ "string", "null" ] }, "voltage_levels_kv": { "type": "array", "items": { "type": "number", "format": "double" } }, "status": { "type": "string", "enum": [ "active", "not_seen", "retired", "merged" ] }, "first_seen_at": { "type": "string", "format": "date-time" }, "last_seen_at": { "type": "string", "format": "date-time" }, "attributes": { "type": "object" }, "identities": { "type": "array", "items": { "$ref": "#/components/schemas/Identity" } }, "related": { "type": "array", "items": { "$ref": "#/components/schemas/Related" } }, "capacity_summary": { "$ref": "#/components/schemas/CapacitySummary" } }, "required": [ "municipality", "region", "postcode", "voltage_levels_kv", "status", "first_seen_at", "last_seen_at", "attributes", "identities", "related", "capacity_summary" ] } ] }, "PostcodeArea": { "type": "object", "properties": { "asset": { "$ref": "#/components/schemas/AssetRef" }, "source_id": { "type": "string" }, "capacity": { "type": "array", "items": { "$ref": "#/components/schemas/CapacityRecord" } } }, "required": [ "asset", "source_id", "capacity" ] }, "PostcodeLookup": { "type": "object", "properties": { "country": { "type": "string" }, "postcode": { "type": "string" }, "areas": { "type": "array", "items": { "$ref": "#/components/schemas/PostcodeArea" } } }, "required": [ "country", "postcode", "areas" ] }, "Export": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "capacity_current", "capacity_history", "substations", "changes" ] }, "format": { "type": "string", "enum": [ "csv", "jsonl", "geojson" ] }, "status": { "type": "string", "enum": [ "queued", "running", "succeeded", "failed", "expired" ], "description": "queued | running | succeeded | failed | expired" }, "filters": { "type": "object" }, "row_count": { "type": [ "integer", "null" ], "format": "int64" }, "byte_size": { "type": [ "integer", "null" ], "format": "int64", "description": "Size of the file as downloaded (uncompressed), in bytes." }, "error": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "finished_at": { "type": [ "string", "null" ], "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "download_url": { "type": [ "string", "null" ], "description": "Set once the export has succeeded, until it expires." } }, "required": [ "id", "kind", "format", "status", "filters", "row_count", "byte_size", "error", "created_at", "started_at", "finished_at", "expires_at", "download_url" ] }, "Webhook": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "filters": { "type": "object" }, "active": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "last_success_at": { "type": [ "string", "null" ], "format": "date-time" }, "consecutive_failures": { "type": "integer", "format": "int32" } }, "required": [ "id", "url", "filters", "active", "created_at", "last_success_at", "consecutive_failures" ] }, "WebhookWithSecret": { "allOf": [ { "$ref": "#/components/schemas/Webhook" }, { "type": "object", "properties": { "secret": { "type": "string", "description": "Shown once. Verify `GridCapacity-Signature: t=,v1=` as HMAC-SHA256(secret, \".\")." } }, "required": [ "secret" ] } ] }, "Access": { "description": "Whether the value is served. `withheld` whenever the source's effective rights mode does not permit redistribution: the record is listed, its value, value_mw, qualifier, status and details are null or empty, and `source_url` links the operator's own publication.", "oneOf": [ { "type": "object", "required": [ "status", "attribution" ], "properties": { "status": { "const": "granted" }, "attribution": { "type": [ "string", "null" ] } } }, { "type": "object", "required": [ "status", "reason", "source_url" ], "properties": { "status": { "const": "withheld" }, "reason": { "type": "string", "enum": [ "redistribution_allowed", "commercial_use_with_attribution", "derived_only", "internal_cache_only", "link_only", "pending_review", "blocked" ] }, "source_url": { "type": "string" } } } ] }, "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id", "details" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Switch on this, not on the message." }, "message": { "type": "string" }, "request_id": { "type": "string" }, "details": { "type": "object", "description": "Code-specific: `capability` and `required_plan` for plan_required, `classes` for capacity_semantics_not_comparable, `newest` for source_data_stale, `sources` for source_rights_restricted." }, "required_plan": { "type": "string", "description": "On a plan refusal: the cheapest plan that would have answered." } } } } }, "GeoJsonAssets": { "type": "object", "description": "A GeoJSON FeatureCollection of asset points. No capacity values.", "required": [ "type", "features", "feature_limit", "truncated" ], "properties": { "type": { "const": "FeatureCollection" }, "features": { "type": "array", "items": { "type": "object" } }, "feature_limit": { "type": "integer" }, "truncated": { "type": "boolean", "description": "True when more assets matched than feature_limit; narrow the bbox." } } } } }, "externalDocs": { "description": "Guides and quickstart", "url": "https://gridcapacityapi.com/docs" } }