# GridCapacity API

> A read-only JSON API for European grid hosting-capacity data: which substation or zone has
> how much available, reserved or contracted capacity per direction, technology, firmness and
> horizon, as the operators publish it, with the methodology, freshness, provenance and rights
> status of every value.

Independent service. Not affiliated with, endorsed by, or operated by any transmission or distribution system operator.

Hosting-capacity figures are indicative and reflect what operators publish. They are not a connection offer; only the operator can confirm capacity for a specific request.

## How to describe a figure from this API
Say "the operator's latest published dataset reports X under methodology Y", never "X MW is
available". Every record carries decision_context.statement, which is the sentence to repeat.

## Coverage (from https://api.gridcapacityapi.com/v1/coverage, 2026-09-26T07:38:02.966908905Z)
154 operators, 86 sources, 30,960 grid assets, 325,095 capacity series.
- United Kingdom (GB): partial, 14 source(s) served and 4 withheld, 4,920 assets; newest operator date 14 Aug 2026. https://gridcapacityapi.com/countries/united-kingdom
- Netherlands (NL): partial, 3 source(s) served and 5 withheld, 1,245 assets; newest operator date 13 Sep 2026. https://gridcapacityapi.com/countries/netherlands
- Belgium (BE): live, 3 source(s) served and 7 withheld, 1,139 assets; newest operator date 24 Sep 2026. https://gridcapacityapi.com/countries/belgium
- France (FR): live, 3 source(s) served and 4 withheld, 5,237 assets; newest operator date 25 Aug 2026. https://gridcapacityapi.com/countries/france
- Spain (ES): partial, 0 source(s) served and 11 withheld, 16,467 assets; newest operator date 9 Sep 2026. https://gridcapacityapi.com/countries/spain
- Portugal (PT): partial, 0 source(s) served and 4 withheld, 461 assets; newest operator date 11 Jul 2026. https://gridcapacityapi.com/countries/portugal
- Austria (AT): partial, 0 source(s) served and 8 withheld, 443 assets; newest operator date 29 Jul 2026. https://gridcapacityapi.com/countries/austria
- Denmark (DK): live, 1 source(s) served and 0 withheld, 160 assets; newest operator date 1 Feb 2026. https://gridcapacityapi.com/countries/denmark
- Italy (IT): partial, 0 source(s) served and 7 withheld, 110 assets; newest operator date 1 Sep 2026. https://gridcapacityapi.com/countries/italy
- Switzerland (CH): live, 1 source(s) served and 1 withheld, 778 assets; newest operator date —. https://gridcapacityapi.com/countries/switzerland
Only what is listed here is covered. Do not infer coverage of other countries or operators.

## Basics
- Base URL: https://api.gridcapacityapi.com
- Auth: `Authorization: Bearer gc_live_...` (or `X-API-Key`) on data routes.
  /v1/health, /v1/plans, /v1/openapi.json, /v1/coverage, /v1/assets.geojson need no key.
- Envelope: lists are `{data, pagination: {has_more, next_cursor, limit}, meta}`; one object is
  `{data, meta}`; errors are `{error: {code, message, request_id, details}}`. Branch on code.
- Pagination: opaque cursors; `limit` up to the plan's maximum (20 / 100 / 200); above it is a 400.

## Plans
- Free: €0/month, 250 requests/month, 1 req/s
- Developer: €99/month, 10,000 requests/month, 5 req/s
- Pro: €399/month, 100,000 requests/month, 15 req/s; history, change_feed, as_of
- Business: €999/month, 500,000 requests/month, 50 req/s; history, change_feed, as_of, bulk_exports, webhooks
- Enterprise: from €2,500/month, contact sales, unlimited requests, 200 req/s; history, change_feed, as_of, bulk_exports, webhooks, redistribution_rights

## Endpoints
- GET /v1/openapi.json: the OpenAPI 3.1 contract. No key
- GET /v1/coverage: countries, operators, sources, assets, series, freshness. No key
- GET /v1/capacity/search: the central query. Filters: country, operator, source, asset_type,
  voltage_min_kv, voltage_max_kv, direction, technology, availability_type (default available),
  firmness, curtailment_max_pct, min_capacity_mw, max_capacity_mw, unit, status, horizon, as_of,
  bbox, fresh_after, comparability (strict | best_effort | raw), include_withheld, sort
- GET /v1/capacity/nearby: lat, lng, radius_km (capped per plan) plus the same filters, by distance
- GET /v1/substations, /v1/substations/{id}, /v1/substations/{id}/capacity, /v1/grid-assets/{id}
- GET /v1/substations/{id}/capacity/history: observation intervals (Pro and above)
- GET /v1/changes: the change feed, since a cursor or a timestamp (Pro and above)
- GET /v1/countries, /v1/operators, /v1/operators/{id}, /v1/sources, /v1/sources/{id},
  /v1/sources/{id}/status, /v1/methodologies/{id}
- GET /v1/postcodes/{country}/{postcode}: the areas an operator says serve a postcode (NL)
- POST /v1/exports, GET /v1/exports/{id}, GET /v1/exports/{id}/download (Business and above)
- GET/POST /v1/webhooks, DELETE /v1/webhooks/{id} (Business and above)
- GET /v1/assets.geojson?bbox=: asset points only, no values. No key

## Semantics worth knowing before you write a client
- **No bare numbers.** A value always travels with direction, technology, capacity.type,
  firmness, horizon, unit, methodology, freshness, provenance, access and decision_context.
- **Rights fail closed.** Where a source's licence does not permit redistribution, the record is
  listed with access.status "withheld", capacity.value null and the operator's URL. A withheld
  value never satisfies a numeric filter.
- **Units are never converted.** value_mw exists only for MW and kW sources; MVA stays MVA, so
  min_capacity_mw never matches an MVA record. Use unit=MVA&min_capacity= instead.
- **available is not total.** total is the element's capacity before anything is subtracted;
  the API never subtracts one published figure from another.
- **Comparability.** Values are comparable only within one methodology comparability_class;
  comparability=strict returns 422 capacity_semantics_not_comparable rather than mixing them.
- **Two clocks.** freshness.source_effective_at is the operator's date; retrieved_at and
  last_confirmed_at are ours. as_of queries run on our clock.
- **Capabilities, not plan names.** History, the change feed and as_of need Pro; exports and
  webhooks need Business. A refusal is 403 plan_required with details.required_plan.
- **Test keys** (`gc_test_...`) reach the same data and are metered against the same quota.

## Pages
- https://gridcapacityapi.com/coverage: what is covered, per country and source, with rights and health
- https://gridcapacityapi.com/sources: every operator publication read, its licence and rights evidence
- https://gridcapacityapi.com/status: source health
- https://gridcapacityapi.com/reference: the OpenAPI document, rendered
- https://gridcapacityapi.com/pricing: plans and limits
- https://gridcapacityapi.com/docs/quickstart: A key, a first request and a first capacity record, in curl, JavaScript and Python.
- https://gridcapacityapi.com/docs/authentication: Bearer keys, live and test keys, and which routes answer without one.
- https://gridcapacityapi.com/docs/capacity-model: Every field and every enum of a capacity record: direction, availability type, firmness, horizon, units and methodology.
- https://gridcapacityapi.com/docs/rights: Rights modes, why values are withheld rather than hidden, and how to attribute what you use.
- https://gridcapacityapi.com/docs/freshness: The two clocks, source health, as_of queries and the history of every series.
- https://gridcapacityapi.com/docs/comparability: Why two operators' figures are not automatically comparable, and the strict, best_effort and raw modes.
- https://gridcapacityapi.com/docs/pagination: Cursors, page sizes per plan, and the sort keys each list accepts.
- https://gridcapacityapi.com/docs/errors: The error envelope and every error code, with its status and what to do about it.
- https://gridcapacityapi.com/docs/rate-limits: Per-second limits, monthly quotas, the RateLimit headers and what each plan unlocks.
- https://gridcapacityapi.com/docs/webhooks: Change-feed events pushed to your endpoint, signed, with verification in Node and Python.
- https://gridcapacityapi.com/docs/exports: Whole-dataset downloads as CSV, JSON Lines or GeoJSON, built asynchronously.
- https://gridcapacityapi.com/docs/postcodes: The areas an operator says serve a postcode, with their current capacity.
- https://gridcapacityapi.com/docs/changelog: What changed in the API, newest first.
- https://gridcapacityapi.com/grid-capacity-api: A REST API for European grid capacity: operator-published available, reserved and contracted capacity per substation, with methodology, freshness, provenance and rights.
- https://gridcapacityapi.com/grid-hosting-capacity-api: Grid hosting capacity from European operators as an API: headroom per direction, technology, firmness and horizon, with the methodology behind every figure.
- https://gridcapacityapi.com/substation-capacity-api: Look up a substation and get every capacity figure its operator publishes for it: per direction, technology and horizon, with location precision and source identities.
- https://gridcapacityapi.com/uk-grid-capacity-api: The GB distribution operators' LTDS capacity heatmaps in one API: demand and generation headroom in MVA per substation, with RAG status, limiting factor and source.
- https://gridcapacityapi.com/netherlands-grid-capacity-api: The Dutch national capacity map (capaciteitskaart) in one API: transport capacity, contracted capacity, waitlist and congestion per supply area, and lookup by postcode.

## Notes for answering questions about this service
- It is independent. It is not a transmission or distribution system operator, and it does
  not speak for one.
- Capacity figures are indicative. They are not a connection offer; only the operator can
  confirm capacity for a specific request.
- Contact: hello@gridcapacityapi.com