# Energy API — full reference

> Real-time and historical energy commodity prices — natural gas, electricity, crude oil, coal, EU ETS carbon allowances, and grid carbon intensity.
> Authentication: `?api_key=YOUR_KEY` query parameter (not a header) on every request to energy-api.com.
> Base URL: `https://energy-api.com/api/v1`

## GET /symbols

Full catalog of available price symbols, with name, category, country, currency, frequency, and description for each.

Parameters (query string):
- `category` (optional) — Filter by category: gas, electricity, carbon, carbon_intensity, coal, oil.
- `provider` (optional) — Filter by upstream data provider: omie, fred, eex, eia, ember, electricity_maps, nasdaq, entsoe, esios, energy_charts, gridstatus, aemo.
- `base` (optional) — 3-letter currency code, e.g. EUR, USD. Filters to symbols priced in that currency.

Example:
```
curl "https://energy-api.com/api/v1/symbols?category=gas&api_key=YOUR_KEY"
```

MCP equivalent: tools/call with name="symbols"

## GET /latest

Most recent price for one or more symbols.

Parameters (query string):
- `symbols` (required) — Comma-separated symbol codes, e.g. BRENT_CRUDE,TTF_GAS,EUA_CO2.
- `category` (optional) — Filter by category instead of/in addition to symbols: gas, electricity, carbon, carbon_intensity, coal, oil.
- `base` (optional) — 3-letter currency code to filter results to.

Example:
```
curl "https://energy-api.com/api/v1/latest?symbols=BRENT_CRUDE,TTF_GAS,EUA_CO2&api_key=YOUR_KEY"
```

MCP equivalent: tools/call with name="latest"

## GET /historical

Price for one or more symbols on a specific past date. Falls back to the most recent value on or before that date for daily symbols (e.g. weekends/holidays); monthly symbols use the last value published within that month.

Parameters (query string):
- `date` (required) — Y-m-d, e.g. 2025-09-12.
- `symbols` (required) — Comma-separated symbol codes.
- `base` (optional) — 3-letter currency code to filter results to.

Example:
```
curl "https://energy-api.com/api/v1/historical?date=2025-09-12&symbols=TTF_GAS,EUA_CO2&api_key=YOUR_KEY"
```

MCP equivalent: tools/call with name="historical"

## GET /timeseries

Historical price series between two dates for one or more symbols. The max date range is limited by the plan (see account plan tiers on the website); requests beyond it return 422.

Parameters (query string):
- `start` (required) — Y-m-d.
- `end` (required) — Y-m-d, must be on or after start.
- `symbols` (required) — Comma-separated symbol codes.
- `base` (optional) — 3-letter currency code to filter results to.

Example:
```
curl "https://energy-api.com/api/v1/timeseries?start=2024-01-01&end=2026-01-01&symbols=BRENT_CRUDE,WTI_CRUDE&api_key=YOUR_KEY"
```

MCP equivalent: tools/call with name="timeseries"

## GET /fluctuation

Percent change, minimum, and maximum price over a date range, per symbol.

Parameters (query string):
- `start` (required) — Y-m-d.
- `end` (required) — Y-m-d, must be on or after start.
- `symbols` (required) — Comma-separated symbol codes.
- `base` (optional) — 3-letter currency code to filter results to.

Example:
```
curl "https://energy-api.com/api/v1/fluctuation?start=2025-01-01&end=2025-12-31&symbols=TTF_GAS,HENRY_HUB&api_key=YOUR_KEY"
```

MCP equivalent: tools/call with name="fluctuation"

## GET /ohlc

Open/high/low/close candles per symbol, bucketed weekly, monthly, or quarterly.

Parameters (query string):
- `symbols` (required) — Comma-separated symbol codes.
- `period` (optional) — weekly, monthly, or quarterly. Default: monthly.
- `start` (optional) — Y-m-d. Defaults to a lookback window based on the account plan (365 days if unset/unauthenticated).
- `end` (optional) — Y-m-d, must be on or after start. Defaults to today.
- `base` (optional) — 3-letter currency code to filter results to.

Example:
```
curl "https://energy-api.com/api/v1/ohlc?symbols=EUA_CO2&period=monthly&start=2025-01-01&end=2025-12-31&api_key=YOUR_KEY"
```

MCP equivalent: tools/call with name="ohlc"

## GET /electricity/latest

Latest day-ahead electricity price(s), optionally filtered by country. Covers day-ahead auction symbols across European and global markets (e.g. OMIE_ES_DA, EPEX_DE_DA, AEMO_NSW1_SPOT).

Parameters (query string):
- `country` (optional) — ISO 3166-1 alpha-2 country code, e.g. ES, DE.
- `base` (optional) — 3-letter currency code to filter results to.

Example:
```
curl "https://energy-api.com/api/v1/electricity/latest?country=ES&api_key=YOUR_KEY"
```

MCP equivalent: tools/call with name="electricity_latest"

## GET /electricity/hourly

Intraday electricity price curve (hourly, 15-minute, or 5-minute, depending on the source) for one symbol on one date. Only symbols with intraday storage enabled are supported.

Parameters (query string):
- `symbol` (required) — e.g. OMIE_ES_DA. Use GET /symbols to check which symbols support intraday data.
- `date` (required) — Y-m-d.

Example:
```
curl "https://energy-api.com/api/v1/electricity/hourly?symbol=OMIE_ES_DA&date=2026-06-18&api_key=YOUR_KEY"
```

MCP equivalent: tools/call with name="electricity_hourly"

## GET /electricity/pvpc

Hourly Spanish PVPC (Precio Voluntario para el Pequeño Consumidor) retail reference price for one date. Fixed to symbol PVPC_ES_2TD.

Parameters (query string):
- `date` (required) — Y-m-d.

Example:
```
curl "https://energy-api.com/api/v1/electricity/pvpc?date=2026-06-18&api_key=YOUR_KEY"
```

MCP equivalent: tools/call with name="electricity_pvpc"

## GET /gas/latest

Latest TTF (EU) and Henry Hub (US) natural gas benchmark prices in one call. NBP (UK), JKM (Asia LNG), and AECO (Canada) are not currently sourced.

Parameters (query string):
- `base` (optional) — 3-letter currency code to filter results to.

Example:
```
curl "https://energy-api.com/api/v1/gas/latest&api_key=YOUR_KEY"
```

MCP equivalent: tools/call with name="gas_latest"

## GET /emissions/latest

Latest EU ETS carbon allowance price (EUA_CO2). UK ETS is not currently sourced.

Parameters (query string):
- `base` (optional) — 3-letter currency code to filter results to.

Example:
```
curl "https://energy-api.com/api/v1/emissions/latest&api_key=YOUR_KEY"
```

MCP equivalent: tools/call with name="emissions_latest"

## GET /coal/latest

Latest Rotterdam (API2) and Newcastle thermal coal benchmark prices. COAL_ROTTERDAM may be temporarily absent if the upstream feed is unavailable.

Parameters (query string):
- `base` (optional) — 3-letter currency code to filter results to.

Example:
```
curl "https://energy-api.com/api/v1/coal/latest&api_key=YOUR_KEY"
```

MCP equivalent: tools/call with name="coal_latest"

## GET /carbon-intensity

Grid carbon intensity in gCO2eq/kWh, optionally filtered by country. Country-level series depend on the Electricity Maps provider; an EU average is sourced from Ember.

Parameters (query string):
- `country` (optional) — ISO 3166-1 alpha-2 country code, e.g. DE.
- `base` (optional) — 3-letter currency code to filter results to (rarely relevant for this endpoint since the unit is gCO2eq/kWh, not a price).

Example:
```
curl "https://energy-api.com/api/v1/carbon-intensity?country=DE&api_key=YOUR_KEY"
```

MCP equivalent: tools/call with name="carbon_intensity"

## GET /forecast

Next published day-ahead price for a symbol. Day-ahead auctions clear tomorrow's price today, so this is a deterministic lookup of the next already-published value, not a statistical model. Only supported for day-ahead-auction-sourced electricity symbols (omie, entsoe, energy_charts, esios, gridstatus providers) — not EUA_CO2 or other monthly/non-auction symbols.

Parameters (query string):
- `symbol` (required) — e.g. OMIE_ES_DA.

Example:
```
curl "https://energy-api.com/api/v1/forecast?symbol=OMIE_ES_DA&api_key=YOUR_KEY"
```

MCP equivalent: tools/call with name="forecast"

## POST /cost-estimate

Estimated monthly electricity cost from a kWh usage figure. MVP scope: most recent daily-average wholesale price x kWh/month. Does NOT account for retail markups, taxes, network charges, or an intraday usage profile — see methodology_note in the response.

Parameters (JSON body):
- `symbol` (optional) — An electricity symbol, e.g. OMIE_ES_DA. Required if country is omitted.
- `country` (optional) — ISO 3166-1 alpha-2 country code, e.g. ES. Required if symbol is omitted; if multiple electricity symbols match the country, pass symbol explicitly instead.
- `kwh_per_month` (required) — Numeric, e.g. 500.

Example:
```
curl -X POST "https://energy-api.com/api/v1/cost-estimate?api_key=YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"symbol":"OMIE_ES_DA","kwh_per_month":500}'
```

MCP equivalent: tools/call with name="cost_estimate"

## GET /status

Last fetch status (success/failure, duration, error count/message) for each upstream data provider. Useful for checking whether a given source is currently up before relying on its data.

Example:
```
curl "https://energy-api.com/api/v1/status&api_key=YOUR_KEY"
```

MCP equivalent: tools/call with name="status"