API reference
Every endpoint, and you can run them here
Press Send and the real API answers. You need no key to look around: the calls go through the site’s own proxy, at most ten rows each.
- operations
- 32operations
- key in a header
- Bearerkey in a header
- one shape everywhere
- JSONone shape everywhere
- RFC 3339 times
- UTCRFC 3339 times
Try it
Send a real request
What a Developer key can call, run here through the site's proxy so you need no key: at most ten rows, a 25 km radius, and nothing that Pro or Business adds.
GET/v1/capacity/nearbyDeveloper and up
Capacity records around a point, nearest first, with every dimension, the methodology, both clocks, provenance and access.
Runs against the live API through the site’s proxy. No key needed, at most ten rows. With your own key there is no cap.
The same call from your code
curl "https://api.gridcapacityapi.com/v1/capacity/nearby?lat=51.5074&lng=-0.1278&radius_km=25&limit=3" \
-H "Authorization: Bearer $GRID_API_KEY"Operations
Every route and parameter
Rendered from the API's own OpenAPI document, so this list cannot promise a route or a parameter the API does not have. Open one to see its parameters and answers.
Meta3 operations
GET/v1/healthNo key
Service status
Answers without a key. Reports whether the database is reachable, the build version, and which sign-in methods this deployment offers.
Responses
- 200Success
GET/v1/plansNo key
Plans, prices and entitlements
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
- 200Success
GET/v1/key
The key making this request
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
- 200Success
- 400Invalid parameter or cursor (`invalid_parameter`)
- 401Missing, malformed or revoked API key (`unauthorized`)
- 429Rate limit or monthly quota exceeded (`rate_limit_exceeded`, `quota_exceeded`)
Coverage3 operations
GET/v1/coverageNo key
Coverage per country
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
- 200Success
- 400Invalid parameter or cursor (`invalid_parameter`)
- 429Rate limit or monthly quota exceeded (`rate_limit_exceeded`)
GET/v1/assets.geojsonNo key
Asset points as GeoJSON
Public and rate limited, no key. Asset points, never capacity values, at most 5,000 features; `truncated` says when more matched. Each point carries a room band per direction for colouring a map (`gen`, `dem`: 3 is 20 MW or MVA or more, 2 is 5 to 20, 1 under 5, 0 none, null when no servable figure), from current snapshot `available` figures of sources whose rights allow values, and `held` when its only figures are withheld.
| Parameter | Type | Description |
|---|---|---|
| bboxquery | string | `min_lon,min_lat,max_lon,max_lat`, WGS84 degrees. |
| countryquery | string | ISO 3166-1 alpha-2, comma list. A country with nothing published is `country_not_supported`. |
| operatorquery | string | Operator slug or `op_` id, comma list. |
| sourcequery | string | Source id, comma list: assets that source describes. |
| asset_typequery | string | Asset type, comma list. |
Responses
- 200Success
- 400Invalid parameter or cursor (`invalid_parameter`)
- 404Not found (`operator_not_found`)
- 429Rate limit or monthly quota exceeded (`rate_limit_exceeded`)
GET/v1/tiles/assets/{z}/{x}/{y}.mvtNo key
Asset points as vector tiles
Public and rate limited, no key. A Mapbox vector tile (layer `assets`) of asset points with id, type, name, slug, country, operator, operator_name, voltage_kv, precision and the room bands `gen`, `dem` and `held` (as in `/v1/assets.geojson`); no values. At most 20,000 points per tile; `X-Feature-Limit-Reached: true` when capped.
| Parameter | Type | Description |
|---|---|---|
| zpathrequired | integer | Zoom. |
| xpathrequired | integer | Tile column. |
| ypathrequired | integer | Tile row (the URL ends in `.mvt`). |
Responses
- 200Success
- 400Invalid parameter or cursor (`invalid_parameter`)
- 429Rate limit or monthly quota exceeded (`rate_limit_exceeded`)
Catalogue7 operations
GET/v1/countries
Countries
Every country in the reference list with its computed coverage status.
| Parameter | Type | Description |
|---|---|---|
| statusquery | live | partial | planned | none | Coverage status. |
| limitquery | integer | Rows per page. The maximum is set by your plan (100 on Developer, 200 above); asking for more is an error rather than a silent truncation. |
| cursorquery | string | Opaque cursor from `pagination.next_cursor`. Omit for the first page. Bound to the sort it was minted under. |
Responses
- 200Success
- 400Invalid parameter or cursor (`invalid_parameter`, `invalid_cursor`)
- 401Missing, malformed or revoked API key (`unauthorized`)
- 429Rate limit or monthly quota exceeded (`rate_limit_exceeded`, `quota_exceeded`)
GET/v1/operators
Operators
TSOs and DSOs, with their sources and asset counts. `covered` means at least one of their sources has published values we may serve.
| Parameter | Type | Description |
|---|---|---|
| countryquery | string | ISO 3166-1 alpha-2. |
| typequery | TSO | DSO | TSO_DSO | joint | other | Operator type. |
| coveredquery | boolean | Only covered (or only uncovered) operators. |
| limitquery | integer | Rows per page. The maximum is set by your plan (100 on Developer, 200 above); asking for more is an error rather than a silent truncation. |
| cursorquery | string | Opaque cursor from `pagination.next_cursor`. Omit for the first page. Bound to the sort it was minted under. |
Responses
- 200Success
- 400Invalid parameter or cursor (`invalid_parameter`, `invalid_cursor`)
- 401Missing, malformed or revoked API key (`unauthorized`)
- 404Not found (`country_not_supported`)
- 429Rate limit or monthly quota exceeded (`rate_limit_exceeded`, `quota_exceeded`)
GET/v1/operators/{id}
One operator
By `op_` id or slug, with its sources.
| Parameter | Type | Description |
|---|---|---|
| idpathrequired | string | `op_` id or slug. |
Responses
- 200Success
- 400Invalid parameter or cursor (`invalid_parameter`)
- 401Missing, malformed or revoked API key (`unauthorized`)
- 404Not found (`operator_not_found`)
- 429Rate limit or monthly quota exceeded (`rate_limit_exceeded`, `quota_exceeded`)
GET/v1/sources
Sources
Every operator publication, registry-only ones included (health `disabled`). `rights_mode` is the effective mode, override included.
| Parameter | Type | Description |
|---|---|---|
| countryquery | string | ISO 3166-1 alpha-2. |
| operatorquery | string | Operator slug or `op_` id. |
| rights_modequery | redistribution_allowed | commercial_use_with_attribution | derived_only | internal_cache_only | link_only | pending_review | blocked | Effective rights mode. |
| healthquery | healthy | stale | degraded | failing | disabled | unknown | Health. |
| limitquery | integer | Rows per page. The maximum is set by your plan (100 on Developer, 200 above); asking for more is an error rather than a silent truncation. |
| cursorquery | string | Opaque cursor from `pagination.next_cursor`. Omit for the first page. Bound to the sort it was minted under. |
Responses
- 200Success
- 400Invalid parameter or cursor (`invalid_parameter`, `invalid_cursor`)
- 401Missing, malformed or revoked API key (`unauthorized`)
- 404Not found (`country_not_supported`, `operator_not_found`)
- 429Rate limit or monthly quota exceeded (`rate_limit_exceeded`, `quota_exceeded`)
GET/v1/sources/{id}
One source
The full manifest facts: methodologies, licence, rights evidence (URL, verbatim quote, date) and semantics.
| Parameter | Type | Description |
|---|---|---|
| idpathrequired | string | The public id. |
Responses
- 200Success
- 400Invalid parameter or cursor (`invalid_parameter`)
- 401Missing, malformed or revoked API key (`unauthorized`)
- 404Not found (`source_not_found`)
- 429Rate limit or monthly quota exceeded (`rate_limit_exceeded`, `quota_exceeded`)
GET/v1/sources/{id}/status
Source health and freshness
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.
| Parameter | Type | Description |
|---|---|---|
| idpathrequired | string | The public id. |
Responses
- 200Success
- 400Invalid parameter or cursor (`invalid_parameter`)
- 401Missing, malformed or revoked API key (`unauthorized`)
- 404Not found (`source_not_found`)
- 429Rate limit or monthly quota exceeded (`rate_limit_exceeded`, `quota_exceeded`)
GET/v1/methodologies/{id}
One methodology
How one source computes its numbers: basis, network state, what is included, comparability class, disclaimers.
| Parameter | Type | Description |
|---|---|---|
| idpathrequired | string | The public id. |
Responses
- 200Success
- 400Invalid parameter or cursor (`invalid_parameter`)
- 401Missing, malformed or revoked API key (`unauthorized`)
- 404Not found (`methodology_not_found`)
- 429Rate limit or monthly quota exceeded (`rate_limit_exceeded`, `quota_exceeded`)
Assets3 operations
GET/v1/substations
Grid assets
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.
| Parameter | Type | Description |
|---|---|---|
| countryquery | string | ISO 3166-1 alpha-2, comma list. A country with nothing published is `country_not_supported`. |
| operatorquery | string | Operator slug or `op_` id, comma list. |
| sourcequery | string | Assets with an identity in these sources. |
| asset_typequery | string | Asset type, comma list. |
| qquery | string | Name search (substring or trigram similarity). |
| slugquery | string | Exact slug, with `country` for the site's asset pages. |
| bboxquery | string | `min_lon,min_lat,max_lon,max_lat`, WGS84 degrees. |
| latquery | number | Latitude, WGS84. With `lng`. |
| lngquery | number | Longitude, WGS84. With `lat`. |
| radius_kmquery | number | Radius around lat/lng on the asset centroid. Default 10 whenever lat/lng are given. Capped per plan (50 / 250 / 500 / 1000 km): above the cap is `plan_required`. |
| voltage_min_kvquery | number | Lowest nominal voltage, kV. |
| voltage_max_kvquery | number | Highest nominal voltage, kV. |
| has_capacityquery | boolean | Only assets with (or without) active capacity series. |
| sortquery | name | voltage | -voltage | distance | Sort order. Nulls (withheld values, unstated voltages) sort last either way. |
| limitquery | integer | Rows per page. The maximum is set by your plan (100 on Developer, 200 above); asking for more is an error rather than a silent truncation. |
| cursorquery | string | Opaque cursor from `pagination.next_cursor`. Omit for the first page. Bound to the sort it was minted under. |
Responses
- 200Success
- 400Invalid parameter or cursor (`invalid_parameter`, `invalid_cursor`)
- 401Missing, malformed or revoked API key (`unauthorized`)
- 403The plan does not include this capability or limit (`plan_required`)
- 404Not found (`country_not_supported`, `operator_not_found`, `operator_not_supported`, `source_not_found`)
- 429Rate limit or monthly quota exceeded (`rate_limit_exceeded`, `quota_exceeded`)
GET/v1/substations/{id}
One substation
The asset, its source identities, related assets and a capacity summary. A merged asset's id resolves to the asset it was merged into.
| Parameter | Type | Description |
|---|---|---|
| idpathrequired | string | A `sub_` id. |
Responses
- 200Success
- 400Invalid parameter or cursor (`invalid_parameter`)
- 401Missing, malformed or revoked API key (`unauthorized`)
- 404Not found (`asset_not_found`)
- 429Rate limit or monthly quota exceeded (`rate_limit_exceeded`, `quota_exceeded`)
GET/v1/grid-assets/{id}
One grid asset of any type
As `/v1/substations/{id}`, for any asset id prefix (`sub_`, `zone_`, `node_`, …).
| Parameter | Type | Description |
|---|---|---|
| idpathrequired | string | Any grid-asset id. |
Responses
- 200Success
- 400Invalid parameter or cursor (`invalid_parameter`)
- 401Missing, malformed or revoked API key (`unauthorized`)
- 404Not found (`asset_not_found`)
- 429Rate limit or monthly quota exceeded (`rate_limit_exceeded`, `quota_exceeded`)
Capacity7 operations
GET/v1/substations/{id}/capacity
Current capacity of a substation
Every current capacity record of the asset (all availability types unless filtered). `as_of` is Pro+.
| Parameter | Type | Description |
|---|---|---|
| idpathrequired | string | A `sub_` id. |
| directionquery | string | Direction, comma list. |
| technologyquery | string | Technology, comma list. |
| availability_typequery | string | What the number counts, comma list. Search and nearby default to `available`. |
| firmnessquery | string | Firmness, comma list. |
| horizonquery | string | `snapshot`, a target year (`2028`) or the operator's label (`Y+2`). |
| curtailment_max_pctquery | number | Largest acceptable curtailment band. Firm series satisfy any value; series of unknown firmness never do. |
| min_capacity_mwquery | number | On `value_mw` only: an MVA figure never satisfies it. Withheld values never satisfy any numeric filter. |
| max_capacity_mwquery | number | On `value_mw` only. |
| unitquery | string | Unit as published, comma list. Nothing is converted. |
| min_capacityquery | number | On `value` in the one unit named by `unit` (required, exactly one): `unit=MVA&min_capacity=50`. |
| max_capacityquery | number | On `value` in the one unit named by `unit`. |
| statusquery | string | Categorical status, comma list (unit=status sources). |
| sourcequery | string | Source id, comma list. Naming only sources that withhold their values is `source_rights_restricted` (451). |
| as_ofquery | string | Pro+. RFC 3339 timestamp or date (end of that day, UTC): what the latest published data said then, on our observation clock. |
| include_withheldquery | boolean | Default true: withheld records are listed without their value. false drops them. |
| sortquery | capacity | -capacity | distance | voltage | -voltage | name | source_updated_at | -source_updated_at | observed_at | -observed_at | Sort order. Nulls (withheld values, unstated voltages) sort last either way. |
| limitquery | integer | Rows per page. The maximum is set by your plan (100 on Developer, 200 above); asking for more is an error rather than a silent truncation. |
| cursorquery | string | Opaque cursor from `pagination.next_cursor`. Omit for the first page. Bound to the sort it was minted under. |
Responses
- 200Success
- 400Invalid parameter or cursor (`invalid_parameter`, `invalid_cursor`)
- 401Missing, malformed or revoked API key (`unauthorized`)
- 403The plan does not include this capability or limit (`plan_required`)
- 404Not found (`asset_not_found`, `capacity_not_available`, `source_not_found`)
- 409Conflict with the state of the data (`source_not_available`)
- 429Rate limit or monthly quota exceeded (`rate_limit_exceeded`, `quota_exceeded`)
- 451Unavailable for legal reasons (rights) (`source_rights_restricted`)
GET/v1/substations/{id}/capacity/history
History of a substation's capacity
Pro+. Each series with its observations as intervals `[observed_from, observed_to)` of our observation clock, overlapping `from`..`to`.
| Parameter | Type | Description |
|---|---|---|
| idpathrequired | string | A `sub_` id. |
| fromquery | string | RFC 3339 or date (start of day). |
| toquery | string | RFC 3339 or date (end of day, exclusive). |
| directionquery | string | Direction, comma list. |
| technologyquery | string | Technology, comma list. |
| availability_typequery | string | What the number counts, comma list. Search and nearby default to `available`. |
| firmnessquery | string | Firmness, comma list. |
| horizonquery | string | `snapshot`, a target year (`2028`) or the operator's label (`Y+2`). |
| limitquery | integer | Rows per page. The maximum is set by your plan (100 on Developer, 200 above); asking for more is an error rather than a silent truncation. |
| cursorquery | string | Opaque cursor from `pagination.next_cursor`. Omit for the first page. Bound to the sort it was minted under. |
Responses
- 200Success
- 400Invalid parameter or cursor (`invalid_parameter`, `invalid_cursor`)
- 401Missing, malformed or revoked API key (`unauthorized`)
- 403The plan does not include this capability or limit (`plan_required`)
- 404Not found (`asset_not_found`)
- 429Rate limit or monthly quota exceeded (`rate_limit_exceeded`, `quota_exceeded`)
GET/v1/grid-assets/{id}/capacity
Current capacity of any grid asset
As `/v1/substations/{id}/capacity`, for any asset type: a Dutch supply area (`zone_`), a Belgian municipality (`area_`), a node. `as_of` is Pro+.
| Parameter | Type | Description |
|---|---|---|
| idpathrequired | string | Any grid-asset id. |
| directionquery | string | Direction, comma list. |
| technologyquery | string | Technology, comma list. |
| availability_typequery | string | What the number counts, comma list. Search and nearby default to `available`. |
| firmnessquery | string | Firmness, comma list. |
| horizonquery | string | `snapshot`, a target year (`2028`) or the operator's label (`Y+2`). |
| curtailment_max_pctquery | number | Largest acceptable curtailment band. Firm series satisfy any value; series of unknown firmness never do. |
| min_capacity_mwquery | number | On `value_mw` only: an MVA figure never satisfies it. Withheld values never satisfy any numeric filter. |
| max_capacity_mwquery | number | On `value_mw` only. |
| unitquery | string | Unit as published, comma list. Nothing is converted. |
| min_capacityquery | number | On `value` in the one unit named by `unit` (required, exactly one): `unit=MVA&min_capacity=50`. |
| max_capacityquery | number | On `value` in the one unit named by `unit`. |
| statusquery | string | Categorical status, comma list (unit=status sources). |
| sourcequery | string | Source id, comma list. Naming only sources that withhold their values is `source_rights_restricted` (451). |
| as_ofquery | string | Pro+. RFC 3339 timestamp or date (end of that day, UTC): what the latest published data said then, on our observation clock. |
| include_withheldquery | boolean | Default true: withheld records are listed without their value. false drops them. |
| sortquery | capacity | -capacity | distance | voltage | -voltage | name | source_updated_at | -source_updated_at | observed_at | -observed_at | Sort order. Nulls (withheld values, unstated voltages) sort last either way. |
| limitquery | integer | Rows per page. The maximum is set by your plan (100 on Developer, 200 above); asking for more is an error rather than a silent truncation. |
| cursorquery | string | Opaque cursor from `pagination.next_cursor`. Omit for the first page. Bound to the sort it was minted under. |
Responses
- 200Success
- 400Invalid parameter or cursor (`invalid_parameter`, `invalid_cursor`)
- 401Missing, malformed or revoked API key (`unauthorized`)
- 403The plan does not include this capability or limit (`plan_required`)
- 404Not found (`asset_not_found`, `capacity_not_available`, `source_not_found`)
- 409Conflict with the state of the data (`source_not_available`)
- 429Rate limit or monthly quota exceeded (`rate_limit_exceeded`, `quota_exceeded`)
- 451Unavailable for legal reasons (rights) (`source_rights_restricted`)
GET/v1/grid-assets/{id}/capacity/history
History of any grid asset's capacity
As `/v1/substations/{id}/capacity/history`, for any asset type. Pro+.
| Parameter | Type | Description |
|---|---|---|
| idpathrequired | string | Any grid-asset id. |
| fromquery | string | RFC 3339 or date (start of day). |
| toquery | string | RFC 3339 or date (end of day, exclusive). |
| directionquery | string | Direction, comma list. |
| technologyquery | string | Technology, comma list. |
| availability_typequery | string | What the number counts, comma list. Search and nearby default to `available`. |
| firmnessquery | string | Firmness, comma list. |
| horizonquery | string | `snapshot`, a target year (`2028`) or the operator's label (`Y+2`). |
| limitquery | integer | Rows per page. The maximum is set by your plan (100 on Developer, 200 above); asking for more is an error rather than a silent truncation. |
| cursorquery | string | Opaque cursor from `pagination.next_cursor`. Omit for the first page. Bound to the sort it was minted under. |
Responses
- 200Success
- 400Invalid parameter or cursor (`invalid_parameter`, `invalid_cursor`)
- 401Missing, malformed or revoked API key (`unauthorized`)
- 403The plan does not include this capability or limit (`plan_required`)
- 404Not found (`asset_not_found`)
- 429Rate limit or monthly quota exceeded (`rate_limit_exceeded`, `quota_exceeded`)
GET/v1/capacity/search
Search capacity records
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.
| Parameter | Type | Description |
|---|---|---|
| countryquery | string | ISO 3166-1 alpha-2, comma list. A country with nothing published is `country_not_supported`. |
| operatorquery | string | Operator slug or `op_` id, comma list. |
| sourcequery | string | Source id, comma list. Naming only sources that withhold their values is `source_rights_restricted` (451). |
| asset_typequery | string | Asset type, comma list. |
| voltage_min_kvquery | number | Lowest nominal voltage, kV. |
| voltage_max_kvquery | number | Highest nominal voltage, kV. |
| directionquery | string | Direction, comma list. |
| technologyquery | string | Technology, comma list. |
| availability_typequery | string | What the number counts, comma list. Search and nearby default to `available`. |
| firmnessquery | string | Firmness, comma list. |
| horizonquery | string | `snapshot`, a target year (`2028`) or the operator's label (`Y+2`). |
| curtailment_max_pctquery | number | Largest acceptable curtailment band. Firm series satisfy any value; series of unknown firmness never do. |
| min_capacity_mwquery | number | On `value_mw` only: an MVA figure never satisfies it. Withheld values never satisfy any numeric filter. |
| max_capacity_mwquery | number | On `value_mw` only. |
| unitquery | string | Unit as published, comma list. Nothing is converted. |
| min_capacityquery | number | On `value` in the one unit named by `unit` (required, exactly one): `unit=MVA&min_capacity=50`. |
| max_capacityquery | number | On `value` in the one unit named by `unit`. |
| statusquery | string | Categorical status, comma list (unit=status sources). |
| as_ofquery | string | Pro+. RFC 3339 timestamp or date (end of that day, UTC): what the latest published data said then, on our observation clock. |
| latquery | number | Latitude, WGS84. With `lng`. |
| lngquery | number | Longitude, WGS84. With `lat`. |
| radius_kmquery | number | Radius around lat/lng on the asset centroid. Default 10 whenever lat/lng are given. Capped per plan (50 / 250 / 500 / 1000 km): above the cap is `plan_required`. |
| bboxquery | string | `min_lon,min_lat,max_lon,max_lat`, WGS84 degrees. |
| fresh_afterquery | string | 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`. |
| comparabilityquery | strict | best_effort | raw | `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. |
| include_withheldquery | boolean | Default true: withheld records are listed without their value. false drops them. |
| sortquery | capacity | -capacity | distance | voltage | -voltage | name | source_updated_at | -source_updated_at | observed_at | -observed_at | Sort order. Nulls (withheld values, unstated voltages) sort last either way. |
| limitquery | integer | Rows per page. The maximum is set by your plan (100 on Developer, 200 above); asking for more is an error rather than a silent truncation. |
| cursorquery | string | Opaque cursor from `pagination.next_cursor`. Omit for the first page. Bound to the sort it was minted under. |
Responses
- 200Success
- 400Invalid parameter or cursor (`invalid_parameter`, `invalid_cursor`)
- 401Missing, malformed or revoked API key (`unauthorized`)
- 403The plan does not include this capability or limit (`plan_required`)
- 404Not found (`country_not_supported`, `operator_not_found`, `operator_not_supported`, `source_not_found`)
- 409Conflict with the state of the data (`source_not_available`, `source_data_stale`)
- 422Not comparable (`capacity_semantics_not_comparable`)
- 429Rate limit or monthly quota exceeded (`rate_limit_exceeded`, `quota_exceeded`)
- 451Unavailable for legal reasons (rights) (`source_rights_restricted`)
GET/v1/capacity/nearby
Capacity records near a point
As search, around `lat`/`lng` (required) within `radius_km` (default 10, capped per plan), sorted by distance; every asset carries `distance_km`.
| Parameter | Type | Description |
|---|---|---|
| countryquery | string | ISO 3166-1 alpha-2, comma list. A country with nothing published is `country_not_supported`. |
| operatorquery | string | Operator slug or `op_` id, comma list. |
| sourcequery | string | Source id, comma list. Naming only sources that withhold their values is `source_rights_restricted` (451). |
| asset_typequery | string | Asset type, comma list. |
| voltage_min_kvquery | number | Lowest nominal voltage, kV. |
| voltage_max_kvquery | number | Highest nominal voltage, kV. |
| directionquery | string | Direction, comma list. |
| technologyquery | string | Technology, comma list. |
| availability_typequery | string | What the number counts, comma list. Search and nearby default to `available`. |
| firmnessquery | string | Firmness, comma list. |
| horizonquery | string | `snapshot`, a target year (`2028`) or the operator's label (`Y+2`). |
| curtailment_max_pctquery | number | Largest acceptable curtailment band. Firm series satisfy any value; series of unknown firmness never do. |
| min_capacity_mwquery | number | On `value_mw` only: an MVA figure never satisfies it. Withheld values never satisfy any numeric filter. |
| max_capacity_mwquery | number | On `value_mw` only. |
| unitquery | string | Unit as published, comma list. Nothing is converted. |
| min_capacityquery | number | On `value` in the one unit named by `unit` (required, exactly one): `unit=MVA&min_capacity=50`. |
| max_capacityquery | number | On `value` in the one unit named by `unit`. |
| statusquery | string | Categorical status, comma list (unit=status sources). |
| as_ofquery | string | Pro+. RFC 3339 timestamp or date (end of that day, UTC): what the latest published data said then, on our observation clock. |
| latquery | number | Latitude, WGS84. With `lng`. |
| lngquery | number | Longitude, WGS84. With `lat`. |
| radius_kmquery | number | Radius around lat/lng on the asset centroid. Default 10 whenever lat/lng are given. Capped per plan (50 / 250 / 500 / 1000 km): above the cap is `plan_required`. |
| bboxquery | string | `min_lon,min_lat,max_lon,max_lat`, WGS84 degrees. |
| fresh_afterquery | string | 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`. |
| comparabilityquery | strict | best_effort | raw | `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. |
| include_withheldquery | boolean | Default true: withheld records are listed without their value. false drops them. |
| sortquery | capacity | -capacity | distance | voltage | -voltage | name | source_updated_at | -source_updated_at | observed_at | -observed_at | Sort order. Nulls (withheld values, unstated voltages) sort last either way. |
| limitquery | integer | Rows per page. The maximum is set by your plan (100 on Developer, 200 above); asking for more is an error rather than a silent truncation. |
| cursorquery | string | Opaque cursor from `pagination.next_cursor`. Omit for the first page. Bound to the sort it was minted under. |
Responses
- 200Success
- 400Invalid parameter or cursor (`invalid_parameter`, `invalid_cursor`)
- 401Missing, malformed or revoked API key (`unauthorized`)
- 403The plan does not include this capability or limit (`plan_required`)
- 404Not found (`country_not_supported`, `operator_not_found`, `operator_not_supported`, `source_not_found`)
- 409Conflict with the state of the data (`source_not_available`, `source_data_stale`)
- 422Not comparable (`capacity_semantics_not_comparable`)
- 429Rate limit or monthly quota exceeded (`rate_limit_exceeded`, `quota_exceeded`)
- 451Unavailable for legal reasons (rights) (`source_rights_restricted`)
GET/v1/postcodes/{country}/{postcode}
Areas serving a postcode
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`.
| Parameter | Type | Description |
|---|---|---|
| countrypathrequired | string | ISO 3166-1 alpha-2. |
| postcodepathrequired | string | As written; whitespace and case are ignored (`1234 ab`). |
Responses
- 200Success
- 400Invalid parameter or cursor (`invalid_parameter`)
- 401Missing, malformed or revoked API key (`unauthorized`)
- 404Not found (`country_not_supported`, `capacity_not_available`)
- 429Rate limit or monthly quota exceeded (`rate_limit_exceeded`, `quota_exceeded`)
- 451Unavailable for legal reasons (rights) (`source_rights_restricted`)
Changes1 operation
GET/v1/changes
The change feed
Pro+. Every added, changed, removed and restored value, oldest first. The id is the cursor: resume with `since=<last id>` (or `cursor=`). Withheld values are null.
| Parameter | Type | Description |
|---|---|---|
| sincequery | string | A change id, or an RFC 3339 timestamp / date. |
| countryquery | string | ISO 3166-1 alpha-2, comma list. A country with nothing published is `country_not_supported`. |
| operatorquery | string | Operator slug or `op_` id, comma list. |
| sourcequery | string | Source id, comma list. Naming only sources that withhold their values is `source_rights_restricted` (451). |
| change_typequery | string | Comma list of added, changed, removed, restored. |
| limitquery | integer | Rows per page. The maximum is set by your plan (100 on Developer, 200 above); asking for more is an error rather than a silent truncation. |
| cursorquery | string | The last change id seen (`pagination.next_cursor`). |
Responses
- 200Success
- 400Invalid parameter or cursor (`invalid_parameter`, `invalid_cursor`)
- 401Missing, malformed or revoked API key (`unauthorized`)
- 403The plan does not include this capability or limit (`plan_required`)
- 404Not found (`country_not_supported`, `operator_not_found`, `source_not_found`)
- 409Conflict with the state of the data (`source_not_available`)
- 429Rate limit or monthly quota exceeded (`rate_limit_exceeded`, `quota_exceeded`)
- 451Unavailable for legal reasons (rights) (`source_rights_restricted`)
Exports4 operations
GET/v1/exports
Your exports
Business+. Newest first.
| Parameter | Type | Description |
|---|---|---|
| limitquery | integer | Rows per page. The maximum is set by your plan (100 on Developer, 200 above); asking for more is an error rather than a silent truncation. |
| cursorquery | string | Opaque cursor from `pagination.next_cursor`. Omit for the first page. Bound to the sort it was minted under. |
Responses
- 200Success
- 400Invalid parameter or cursor (`invalid_parameter`, `invalid_cursor`)
- 401Missing, malformed or revoked API key (`unauthorized`)
- 403The plan does not include this capability or limit (`plan_required`)
- 429Rate limit or monthly quota exceeded (`rate_limit_exceeded`, `quota_exceeded`)
POST/v1/exports
Create an export
Business+. An asynchronous job: `kind` (capacity_current | capacity_history | substations | changes), `format` (csv | jsonl | geojson, and geojson only 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
- 202Accepted: queued
- 400Invalid parameter or cursor (`invalid_parameter`)
- 401Missing, malformed or revoked API key (`unauthorized`)
- 403The plan does not include this capability or limit (`plan_required`)
- 404Not found (`country_not_supported`, `operator_not_found`, `source_not_found`)
- 409Conflict with the state of the data (`source_not_available`)
- 429Rate limit or monthly quota exceeded (`rate_limit_exceeded`, `quota_exceeded`, `export_limit_exceeded`)
- 451Unavailable for legal reasons (rights) (`source_rights_restricted`)
GET/v1/exports/{id}
Export status
Business+. `download_url` is set once it has succeeded.
| Parameter | Type | Description |
|---|---|---|
| idpathrequired | string | An `exp_` id. |
Responses
- 200Success
- 400Invalid parameter or cursor (`invalid_parameter`)
- 401Missing, malformed or revoked API key (`unauthorized`)
- 403The plan does not include this capability or limit (`plan_required`)
- 404Not found (`export_not_found`)
- 429Rate limit or monthly quota exceeded (`rate_limit_exceeded`, `quota_exceeded`)
GET/v1/exports/{id}/download
Download an export
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`.
| Parameter | Type | Description |
|---|---|---|
| idpathrequired | string | An `exp_` id. |
Responses
- 200Success
- 400Invalid parameter or cursor (`invalid_parameter`)
- 401Missing, malformed or revoked API key (`unauthorized`)
- 403The plan does not include this capability or limit (`plan_required`)
- 404Not found (`export_not_found`)
- 409Conflict with the state of the data (`export_not_ready`)
- 410Gone (`export_expired`)
- 429Rate limit or monthly quota exceeded (`rate_limit_exceeded`, `quota_exceeded`, `download_limit_exceeded`)
Webhooks4 operations
GET/v1/webhooks
Your webhooks
Business+. Never includes the secret.
| Parameter | Type | Description |
|---|---|---|
| limitquery | integer | Rows per page. The maximum is set by your plan (100 on Developer, 200 above); asking for more is an error rather than a silent truncation. |
| cursorquery | string | Opaque cursor from `pagination.next_cursor`. Omit for the first page. Bound to the sort it was minted under. |
Responses
- 200Success
- 400Invalid parameter or cursor (`invalid_parameter`, `invalid_cursor`)
- 401Missing, malformed or revoked API key (`unauthorized`)
- 403The plan does not include this capability or limit (`plan_required`)
- 429Rate limit or monthly quota exceeded (`rate_limit_exceeded`, `quota_exceeded`)
POST/v1/webhooks
Create a webhook
Business+. `url` must be https and public. Deliveries are POSTed JSON with `GridCapacity-Signature: t=<unix>,v1=<hex HMAC-SHA256 of "<t>.<body>">`. The secret is returned here once.
Responses
- 201Created
- 400Invalid parameter or cursor (`invalid_parameter`)
- 401Missing, malformed or revoked API key (`unauthorized`)
- 403The plan does not include this capability or limit (`plan_required`)
- 404Not found (`country_not_supported`, `operator_not_found`, `source_not_found`)
- 429Rate limit or monthly quota exceeded (`rate_limit_exceeded`, `quota_exceeded`)
DELETE/v1/webhooks/{id}
Delete a webhook
Business+. Pending deliveries are dropped.
| Parameter | Type | Description |
|---|---|---|
| idpathrequired | string | A `wh_` id. |
Responses
- 200Success
- 400Invalid parameter or cursor (`invalid_parameter`)
- 401Missing, malformed or revoked API key (`unauthorized`)
- 403The plan does not include this capability or limit (`plan_required`)
- 404Not found (`webhook_not_found`)
- 429Rate limit or monthly quota exceeded (`rate_limit_exceeded`, `quota_exceeded`)
POST/v1/webhooks/{id}/rotate
Rotate a webhook secret
Business+. The new secret is returned once and signs every later delivery; the old one stops at once.
| Parameter | Type | Description |
|---|---|---|
| idpathrequired | string | A `wh_` id. |
Responses
- 200Success
- 400Invalid parameter or cursor (`invalid_parameter`)
- 401Missing, malformed or revoked API key (`unauthorized`)
- 403The plan does not include this capability or limit (`plan_required`)
- 404Not found (`webhook_not_found`)
- 429Rate limit or monthly quota exceeded (`rate_limit_exceeded`, `quota_exceeded`)
The contract
Learn it once
What is true of every endpoint, so the second one you call holds no surprises.
One envelope
Lists return { data, pagination, meta }, one object { data, meta }. Errors return { error: { code, message, request_id, details } }. Branch on code; it will not change.
Cursor pagination
limit and cursor. Keyed on the sort value plus a tiebreaker id, so page 2,000 costs what page 1 costs.
Every field present
A value that does not apply is null, never omitted, so a row has the same keys on every page.
Provenance and rights
Every figure carries the publication it was read from, its methodology and its access status. A value the licence withholds is listed with value null.
Capabilities, not plan names
A refused call names the capability and the cheapest plan that would have answered it.
RateLimit headers
Every keyed response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset, so you can see the wall coming.