Skip to content

Start

Quickstart

A key, a first request and a first capacity record, in curl, JavaScript and Python.

1. Get a key

Create an account to look around the dashboard and try requests in the browser. API keys come with a paid plan, starting with Developer. Once you subscribe, your first key is shown once. Copy it: only a hash is stored, so it cannot be shown again.

2. Ask what is near a point

The nearby search is the quickest way to see real records: every capacity record within a radius, nearest first. Every paid plan allows at least 50 km.

curl "https://api.gridcapacityapi.com/v1/capacity/nearby?lat=51.5074&lng=-0.1278&radius_km=25&limit=5" \
  -H "Authorization: Bearer gc_live_..."

No key yet?

The same request runs from the test calls on your dashboard with a free account.

3. Read a record the way it is meant

One record is one value of one series: a single combination of asset, direction, technology, availability type, firmness and horizon. Here is its shape, with placeholder values:

JSON
{
  "id": "cap_01k5wxyz…",
  "series_id": "cs_01k5…",
  "asset": {
    "id": "sub_01k5wabc…",
    "type": "substation",
    "name": "Example 150 kV substation",
    "slug": "example-150kv",
    "country": "BE",
    "operator": {
      "id": "op_…",
      "slug": "example-tso",
      "name": "Example TSO",
      "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": "example_ghc_2026",
    "title": "Example hosting-capacity method, 2026 edition",
    "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": "example_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": "xx_example_hosting_capacity",
    "source_record_id": "12345",
    "source_url": "https://operator.example/hosting-capacity",
    "payload_sha256": "9f86d081884c7d65…",
    "license": "CC BY 4.0",
    "rights_mode": "commercial_use_with_attribution"
  },
  "access": {
    "status": "granted",
    "attribution": "Source: Example TSO"
  },
  "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 example_ghc_2026."
  }
}
  • capacity.value is in capacity.unit. value_mw is set only when the operator published active power; for MVA it is null.
  • access.status is "withheld" when the operator’s terms do not let us serve the value. The record is still there, with value: null and a link.
  • freshness.source_effective_at is the operator’s date; retrieved_at is ours. They are different clocks, and both matter.
  • decision_context.statement is the sentence to show a person. It says what the operator’s dataset reports, never that capacity is available to them.

4. Narrow it down

The central search takes the same filters as nearby, without the point. Every dimension is a filter, and withheld records are included unless you say otherwise.

Terminal
curl "https://api.gridcapacityapi.com/v1/capacity/search?country=GB&direction=injection&technology=battery&availability_type=available&include_withheld=false" \  -H "Authorization: Bearer gc_live_..."

Filtering on megawatts

min_capacity_mw filters on value_mw, so an MVA record never satisfies it. That is by design. To filter MVA figures, ask for them in their own unit: unit=MVA&min_capacity=10.

Next

Try itMake test calls from your dashboardFrom your dashboard, no key needed.ReferenceEvery endpoint and parameterRendered from the OpenAPI document.