{"openapi":"3.1.0","info":{"title":"GridHub Electricity Data API","version":"1.0.0","description":"Real-time and historical electricity market data — demand, generation mix, wholesale prices, carbon intensity, and interconnector flows — across 25 grids in the US, UK, Australia, and continental Europe. Sourced from EIA, NESO, Elexon, AEMO, and ENTSO-E.","contact":{"email":"jalcodev@gmail.com","url":"https://grid-hub.app/contact"},"license":{"name":"See /v1/zones for per-source licensing"}},"servers":[{"url":"https://api.grid-hub.app"}],"paths":{"/v1/zones":{"get":{"summary":"List all covered zones","description":"Coverage list with per-zone licence and attribution info.","security":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"zones":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"source":{"type":"string"},"tz":{"type":"string"},"currency":{"type":"string"},"license":{"type":"string"},"attribution":{"type":"string"}}}}}}}}}}}},"/v1/status":{"get":{"summary":"Ingestion freshness per source/zone","security":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"now":{"type":"integer"},"sources":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string"},"zone":{"type":"string"},"last_ok":{"type":"integer"},"last_error":{"type":"string"}}}}}}}}}}}},"/v1/geo/zones":{"get":{"summary":"Zone boundary polygons","description":"GeoJSON FeatureCollection of covered zone boundaries.","security":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","description":"GeoJSON FeatureCollection"}}}}}}},"/v1/geo/interconnectors":{"get":{"summary":"Interconnector lines","description":"GeoJSON LineStrings for tracked interconnector pairs, with from/to zone ids.","security":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","description":"GeoJSON FeatureCollection"}}}}}}},"/v1/geo/plants":{"get":{"summary":"Power plants ≥250MW","security":[],"parameters":[{"name":"zone","in":"query","required":false,"schema":{"type":"string"}},{"name":"fuel","in":"query","required":false,"schema":{"type":"string"}},{"name":"min_mw","in":"query","required":false,"schema":{"type":"number"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","description":"GeoJSON FeatureCollection"}}}}}}},"/v1/map/snapshot":{"get":{"summary":"Full current-state snapshot","description":"Every covered zone's latest metrics in one call. Priced at $0.002 per call, payable via x402 (USDC on Base).","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.002000"},"protocols":[{"x402":{}}]},"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"generated":{"type":"integer"},"zones":{"type":"object","additionalProperties":{"type":"object","properties":{"metrics":{"type":"object","additionalProperties":{"type":"object","properties":{"value":{"type":"number"},"unit":{"type":"string"},"ts":{"type":"integer","description":"Unix timestamp (seconds)"},"resolution":{"type":"string"}}}}}}}}}}}},"402":{"description":"Payment required — see the PAYMENT-REQUIRED header for x402 v2 payment details."},"404":{"description":"Unknown zone."}}}},"/v1/brief/{zone}":{"get":{"summary":"Zone brief — current state with historical context","description":"Composite snapshot for one zone: current price, demand, carbon intensity and generation mix, each ranked against that zone's own trailing 30-day distribution (percentile, median, min/max), plus 24h trend direction and a plain-language summary. One call replaces the four-to-five separate requests otherwise needed, and returns the interpretation rather than raw series. Context blocks are omitted for metrics a zone does not publish; each reports its actual data window and sample count. Priced at $0.02 per call, payable via x402 (USDC on Base).","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.020000"},"protocols":[{"x402":{}}]},"parameters":[{"name":"zone","in":"path","required":true,"schema":{"type":"string","enum":["US-CAISO","US-ERCOT","US-PJM","US-MISO","US-NYISO","US-ISONE","US-SPP","GB","AU-NSW","AU-QLD","AU-VIC","AU-SA","AU-TAS","DE-LU","FR","ES","IT-NO","NL","BE","PL","SE-3","NO-2","DK-1","AT","CH"]},"description":"Zone identifier — see GET /v1/zones for the full list."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"zone":{"type":"string"},"zone_name":{"type":"string"},"as_of":{"type":"integer","description":"Unix timestamp (seconds)"},"current":{"type":"object","description":"Most recent value at or before request time, per metric.","additionalProperties":{"type":"object","properties":{"value":{"type":"number"},"unit":{"type":"string"},"ts":{"type":"integer"}}}},"context":{"type":"object","description":"Trailing-window distribution stats per metric. Omitted for metrics with insufficient data.","additionalProperties":{"type":"object","properties":{"percentile":{"type":"integer","description":"Rank of the current value within the window, 0-100"},"vs_median_pct":{"type":"number"},"median":{"type":"number"},"min":{"type":"number"},"max":{"type":"number"},"sample_count":{"type":"integer"},"window_days_actual":{"type":"number"},"unit":{"type":"string"}}}},"context_window_requested_days":{"type":"integer"},"trend_24h":{"type":"object","additionalProperties":{"type":"object","properties":{"direction":{"type":"string","enum":["rising","falling","flat"]},"change_pct":{"type":"number"},"from_value":{"type":"number"}}}},"generation_mix":{"type":"object","description":"Generation by fuel. Unit varies by zone — see generation_mix_unit.","additionalProperties":{"type":"number"}},"generation_mix_unit":{"type":"string"},"summary":{"type":"string","description":"Plain-language reading, derived from the numbers above."},"coverage_note":{"type":"string"},"attribution":{"type":"string"},"license":{"type":"string"}}}}}},"402":{"description":"Payment required — see the PAYMENT-REQUIRED header for x402 v2 payment details."},"404":{"description":"Unknown zone."}}}},"/v1/latest/{zone}":{"get":{"summary":"Latest snapshot for one zone","description":"Most recent demand, price, generation mix, carbon intensity, and interchange for a single zone. Priced at $0.001 per call, payable via x402 (USDC on Base).","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.001000"},"protocols":[{"x402":{}}]},"parameters":[{"name":"zone","in":"path","required":true,"schema":{"type":"string","enum":["US-CAISO","US-ERCOT","US-PJM","US-MISO","US-NYISO","US-ISONE","US-SPP","GB","AU-NSW","AU-QLD","AU-VIC","AU-SA","AU-TAS","DE-LU","FR","ES","IT-NO","NL","BE","PL","SE-3","NO-2","DK-1","AT","CH"]},"description":"Zone identifier — see GET /v1/zones for the full list."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"zone":{"type":"string"},"metrics":{"type":"object","additionalProperties":{"type":"object","properties":{"value":{"type":"number"},"unit":{"type":"string"},"ts":{"type":"integer","description":"Unix timestamp (seconds)"},"resolution":{"type":"string"}}}},"attribution":{"type":"string"},"license":{"type":"string"},"updated":{"type":"integer"}}}}}},"402":{"description":"Payment required — see the PAYMENT-REQUIRED header for x402 v2 payment details."},"404":{"description":"Unknown zone."}}}},"/v1/demand/{zone}":{"get":{"summary":"Historical demand","description":"Demand (MW) time series for one zone. Priced at $0.01 per call, payable via x402 (USDC on Base).","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.010000"},"protocols":[{"x402":{}}]},"parameters":[{"name":"zone","in":"path","required":true,"schema":{"type":"string","enum":["US-CAISO","US-ERCOT","US-PJM","US-MISO","US-NYISO","US-ISONE","US-SPP","GB","AU-NSW","AU-QLD","AU-VIC","AU-SA","AU-TAS","DE-LU","FR","ES","IT-NO","NL","BE","PL","SE-3","NO-2","DK-1","AT","CH"]},"description":"Zone identifier — see GET /v1/zones for the full list."},{"name":"start","in":"query","required":false,"schema":{"type":"integer"},"description":"Unix seconds. Defaults to 24h before now."},{"name":"end","in":"query","required":false,"schema":{"type":"integer"},"description":"Unix seconds. Defaults to now."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":5000},"description":"Max rows returned. Default 1000."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"zone":{"type":"string"},"metric":{"type":"string"},"start":{"type":"integer"},"end":{"type":"integer"},"count":{"type":"integer"},"attribution":{"type":"string"},"license":{"type":"string"},"data":{"type":"array","items":{"type":"object","properties":{"fuel":{"type":"string","description":"present for generation/capacity metrics"},"ts":{"type":"integer"},"value":{"type":"number"},"unit":{"type":"string"},"resolution":{"type":"string"}}}}}}}}},"402":{"description":"Payment required — see the PAYMENT-REQUIRED header for x402 v2 payment details."},"404":{"description":"Unknown zone."}}}},"/v1/generation/{zone}":{"get":{"summary":"Historical generation mix","description":"Generation by fuel type (MW or %) time series for one zone. Priced at $0.01 per call, payable via x402 (USDC on Base).","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.010000"},"protocols":[{"x402":{}}]},"parameters":[{"name":"zone","in":"path","required":true,"schema":{"type":"string","enum":["US-CAISO","US-ERCOT","US-PJM","US-MISO","US-NYISO","US-ISONE","US-SPP","GB","AU-NSW","AU-QLD","AU-VIC","AU-SA","AU-TAS","DE-LU","FR","ES","IT-NO","NL","BE","PL","SE-3","NO-2","DK-1","AT","CH"]},"description":"Zone identifier — see GET /v1/zones for the full list."},{"name":"start","in":"query","required":false,"schema":{"type":"integer"},"description":"Unix seconds. Defaults to 24h before now."},{"name":"end","in":"query","required":false,"schema":{"type":"integer"},"description":"Unix seconds. Defaults to now."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":5000},"description":"Max rows returned. Default 1000."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"zone":{"type":"string"},"metric":{"type":"string"},"start":{"type":"integer"},"end":{"type":"integer"},"count":{"type":"integer"},"attribution":{"type":"string"},"license":{"type":"string"},"data":{"type":"array","items":{"type":"object","properties":{"fuel":{"type":"string","description":"present for generation/capacity metrics"},"ts":{"type":"integer"},"value":{"type":"number"},"unit":{"type":"string"},"resolution":{"type":"string"}}}}}}}}},"402":{"description":"Payment required — see the PAYMENT-REQUIRED header for x402 v2 payment details."},"404":{"description":"Unknown zone."}}}},"/v1/price/{zone}":{"get":{"summary":"Historical wholesale price","description":"Wholesale price time series for one zone, in local currency per MWh. Priced at $0.01 per call, payable via x402 (USDC on Base).","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.010000"},"protocols":[{"x402":{}}]},"parameters":[{"name":"zone","in":"path","required":true,"schema":{"type":"string","enum":["US-CAISO","US-ERCOT","US-PJM","US-MISO","US-NYISO","US-ISONE","US-SPP","GB","AU-NSW","AU-QLD","AU-VIC","AU-SA","AU-TAS","DE-LU","FR","ES","IT-NO","NL","BE","PL","SE-3","NO-2","DK-1","AT","CH"]},"description":"Zone identifier — see GET /v1/zones for the full list."},{"name":"start","in":"query","required":false,"schema":{"type":"integer"},"description":"Unix seconds. Defaults to 24h before now."},{"name":"end","in":"query","required":false,"schema":{"type":"integer"},"description":"Unix seconds. Defaults to now."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":5000},"description":"Max rows returned. Default 1000."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"zone":{"type":"string"},"metric":{"type":"string"},"start":{"type":"integer"},"end":{"type":"integer"},"count":{"type":"integer"},"attribution":{"type":"string"},"license":{"type":"string"},"data":{"type":"array","items":{"type":"object","properties":{"fuel":{"type":"string","description":"present for generation/capacity metrics"},"ts":{"type":"integer"},"value":{"type":"number"},"unit":{"type":"string"},"resolution":{"type":"string"}}}}}}}}},"402":{"description":"Payment required — see the PAYMENT-REQUIRED header for x402 v2 payment details."},"404":{"description":"Unknown zone."}}}},"/v1/carbon-intensity/{zone}":{"get":{"summary":"Historical carbon intensity","description":"Grid carbon intensity (gCO2/kWh) time series for one zone. Priced at $0.01 per call, payable via x402 (USDC on Base).","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.010000"},"protocols":[{"x402":{}}]},"parameters":[{"name":"zone","in":"path","required":true,"schema":{"type":"string","enum":["US-CAISO","US-ERCOT","US-PJM","US-MISO","US-NYISO","US-ISONE","US-SPP","GB","AU-NSW","AU-QLD","AU-VIC","AU-SA","AU-TAS","DE-LU","FR","ES","IT-NO","NL","BE","PL","SE-3","NO-2","DK-1","AT","CH"]},"description":"Zone identifier — see GET /v1/zones for the full list."},{"name":"start","in":"query","required":false,"schema":{"type":"integer"},"description":"Unix seconds. Defaults to 24h before now."},{"name":"end","in":"query","required":false,"schema":{"type":"integer"},"description":"Unix seconds. Defaults to now."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":5000},"description":"Max rows returned. Default 1000."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"zone":{"type":"string"},"metric":{"type":"string"},"start":{"type":"integer"},"end":{"type":"integer"},"count":{"type":"integer"},"attribution":{"type":"string"},"license":{"type":"string"},"data":{"type":"array","items":{"type":"object","properties":{"fuel":{"type":"string","description":"present for generation/capacity metrics"},"ts":{"type":"integer"},"value":{"type":"number"},"unit":{"type":"string"},"resolution":{"type":"string"}}}}}}}}},"402":{"description":"Payment required — see the PAYMENT-REQUIRED header for x402 v2 payment details."},"404":{"description":"Unknown zone."}}}},"/v1/interchange/{zone}":{"get":{"summary":"Historical interconnector flows","description":"Cross-border power flow (MW) time series for one zone. Priced at $0.01 per call, payable via x402 (USDC on Base).","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.010000"},"protocols":[{"x402":{}}]},"parameters":[{"name":"zone","in":"path","required":true,"schema":{"type":"string","enum":["US-CAISO","US-ERCOT","US-PJM","US-MISO","US-NYISO","US-ISONE","US-SPP","GB","AU-NSW","AU-QLD","AU-VIC","AU-SA","AU-TAS","DE-LU","FR","ES","IT-NO","NL","BE","PL","SE-3","NO-2","DK-1","AT","CH"]},"description":"Zone identifier — see GET /v1/zones for the full list."},{"name":"start","in":"query","required":false,"schema":{"type":"integer"},"description":"Unix seconds. Defaults to 24h before now."},{"name":"end","in":"query","required":false,"schema":{"type":"integer"},"description":"Unix seconds. Defaults to now."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":5000},"description":"Max rows returned. Default 1000."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"zone":{"type":"string"},"metric":{"type":"string"},"start":{"type":"integer"},"end":{"type":"integer"},"count":{"type":"integer"},"attribution":{"type":"string"},"license":{"type":"string"},"data":{"type":"array","items":{"type":"object","properties":{"fuel":{"type":"string","description":"present for generation/capacity metrics"},"ts":{"type":"integer"},"value":{"type":"number"},"unit":{"type":"string"},"resolution":{"type":"string"}}}}}}}}},"402":{"description":"Payment required — see the PAYMENT-REQUIRED header for x402 v2 payment details."},"404":{"description":"Unknown zone."}}}},"/v1/capacity/{zone}":{"get":{"summary":"Historical installed capacity","description":"Annual installed generation capacity (MW) by fuel type. European zones only. Priced at $0.01 per call, payable via x402 (USDC on Base).","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.010000"},"protocols":[{"x402":{}}]},"parameters":[{"name":"zone","in":"path","required":true,"schema":{"type":"string","enum":["DE-LU","FR","ES","NL","BE","PL","NO-2","DK-1","AT","CH"]},"description":"Zone identifier — see GET /v1/zones for the full list."},{"name":"start","in":"query","required":false,"schema":{"type":"integer"},"description":"Unix seconds. Defaults to 24h before now."},{"name":"end","in":"query","required":false,"schema":{"type":"integer"},"description":"Unix seconds. Defaults to now."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":5000},"description":"Max rows returned. Default 1000."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"zone":{"type":"string"},"metric":{"type":"string"},"start":{"type":"integer"},"end":{"type":"integer"},"count":{"type":"integer"},"attribution":{"type":"string"},"license":{"type":"string"},"data":{"type":"array","items":{"type":"object","properties":{"fuel":{"type":"string","description":"present for generation/capacity metrics"},"ts":{"type":"integer"},"value":{"type":"number"},"unit":{"type":"string"},"resolution":{"type":"string"}}}}}}}}},"402":{"description":"Payment required — see the PAYMENT-REQUIRED header for x402 v2 payment details."},"404":{"description":"Unknown zone."}}}}}}