Quickstart

1. Get a key#

Create an account. The Free plan starts immediately, with no card, and your first key is shown once on the next screen. 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. The Free plan allows a 25 km radius.

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

const url = new URL("https://api.gridcapacityapi.com/v1/capacity/nearby");
url.search = new URLSearchParams({ lat: "51.5074", lng: "-0.1278", radius_km: "25", limit: "5" }).toString();

const res = await fetch(url, {
  headers: { Authorization: `Bearer ${process.env.GRID_API_KEY}` },
});
if (!res.ok) throw new Error((await res.json()).error.code);
const { data, pagination } = await res.json();

for (const r of data) {
  // Never print r.capacity.value alone: it means nothing without its unit and type.
  console.log(r.asset.name, r.direction, r.capacity.type, r.capacity.value, r.capacity.unit);
}

import os, requests

r = requests.get(
    "https://api.gridcapacityapi.com/v1/capacity/nearby",
    params={"lat": 51.5074, "lng": -0.1278, "radius_km": 25, "limit": 5},
    headers={"Authorization": f"Bearer {os.environ['GRID_API_KEY']}"},
    timeout=15,
)
r.raise_for_status()
for rec in r.json()["data"]:
    print(rec["asset"]["name"], rec["direction"], rec["capacity"]["type"],
          rec["capacity"]["value"], rec["capacity"]["unit"])

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:

{
  "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.

$ 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_..."

Next#

• The capacity model: every field and enum.
• Pagination: walking a result set with cursors.
• The API reference: every endpoint, runnable in the page.