Obtain an API key from the Electricity Maps developer portal; authenticate all requests by adding the 'auth-token: YOUR_TOKEN' header — the /zones endpoint does not require authentication and lists all available zones with their access tier.
Call GET /v3/zones to retrieve the full zone list; each zone entry includes an 'access' field indicating whether it is available on the free tier or requires a paid plan — filter to zones with 'access': 'full' or match your subscription level before querying.
Request past carbon intensity data via GET /v3/carbon-intensity/history?zone={ZONE_ID}; the response includes an 'history' array of {datetime, carbonIntensity, fossilFuelPercentage} objects covering approximately the last 24 hours at hourly resolution on the free tier.
For longer historical windows, use the paid historical endpoint GET /v3/carbon-intensity/past-range?zone={ZONE_ID}&datetime={start}&endDatetime={end}; parse the response array and store records keyed by (zone, datetime) to support deduplication on re-ingestion.
Handle missing data points: some zones have data gaps due to source outages; check for null carbonIntensity values and fill gaps using linear interpolation or a default regional average only if your downstream use case (e.g., Scope 2 accounting) explicitly permits it.
For power breakdown (renewable vs. fossil mix), query GET /v3/power-breakdown/history?zone={ZONE_ID} in addition to carbon intensity — this provides per-source generation (solar, wind, hydro, etc.) and import/export flows needed for market-based Scope 2 calculations.
Known gotchas
Electricity Maps zone identifiers do not always align with ISO/RTO boundaries; a single ISO may map to multiple Electricity Maps zones (e.g., CAISO covers multiple CA zones), and cross-referencing requires consulting the zone metadata rather than assuming a 1:1 mapping.
The 'carbonIntensity' value is in gCO2eq/kWh and represents the consumption mix including imports; do not use it directly as a production-based intensity factor for Scope 2 market-based accounting, which requires the zone's production mix only.
Historical data is typically finalized with a multi-hour delay as real-time estimates are revised when actual generation data becomes available; values queried shortly after a time period are preliminary and may change — for compliance reporting, re-query data at least 48 hours after the interval ends.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp