IEA Energy Data

Get country-year energy statistics for any indicator in the IEA indicator catalogue: energy supply and consumption, electricity generation, CO2 emissions, renewables, oil, gas and coal trade, prices, efficiency, RD&D budgets and the SDG7 series. The Actor supports batch datasets, GET /query, and a free GET /indicators search.

Coverage

78 indicators as of 25 September 2026, the full IEA indicator catalogue on that day, all returning data. The indicator list is refreshed every 24 hours, so codes IEA adds or removes are reflected automatically. Run with listIndicators: true (free) for the current list with units, years and dimensions.

Area	Example codes	Unit	Observed years
SDG7	SDG71 access to electricity, SDG72, SDG72modern renewable share, SDG73 energy intensity, SDG94	%, MJ per 2021 USD PPP	1990/2000–2022 (SDG71 is served through 2050)
CO2	TotCO2, CO2BySector, CO2BySource, CO2PerCap, CO2IntensityPower	MtCO2, tCO2 per capita, index	1990–2023
Electricity and heat	ElecGenByFuel, ElecGenByFuelLC, ElecConsBySector, SolarGen, WindGen, NuclearGen	GWh, TWh, TJ	1990–2024
Supply and consumption	TESbySource, TFCbySource, TFCbySector, DomesticProduction, NetImports	TJ, PJ, MJ per capita	1990–2024
Oil, gas, coal	OilProd, CrudeImportsExports, NatGasConsBySector, CoalProdByType	TJ, TJ gross	1990–2024
Prices	GasPrice (gasoline)	USD/litre	1990–2025
Efficiency	EEIManufacturing, EEIPassengerTransport, ResidentialConsByEndUse	MJ per USD PPP, MJ per pkm, PJ	2000–2024
RD&D budgets	TotalRDDSpending, RDDTechSplitUSD, RDDPerGDP	million USD (2024 prices and PPP)	1990–2024

Coverage differs by indicator and country; aggregates such as WORLD are available on request. This is historical data (plus the SDG7.1 series IEA publishes to 2050), not current-year estimates. Run a listing for every indicator's flow and product codes.

Each row names the IEA dataset it belongs to and includes the retrieval time, data version and data age. Data is refreshed after 24 hours. If fresh data cannot be retrieved, a cached copy up to seven days old may be used and its age is visible; after that, the request fails.

Input

Batch input example (the default runs this selection and yields three US rows):

{
  "indicators": ["SDG72modern"],
  "countries": ["USA"],
  "yearStart": 2020,
  "maxRows": 1000
}

Field	Meaning
listIndicators	true outputs one row per indicator instead of data, and charges no row event.
indicators	IEA codes such as TotCO2, ElecGenByFuel, or ["all"]. Codes are checked against the live catalogue; a mistyped code fails with the closest matches. Case is ignored.
countries	ISO 2 or ISO 3 codes (DE, DEU), region codes (WORLD, EU27_2020), IEA country codes for territories without an ISO mapping (BURKINA), or ["all"]. all excludes regional aggregates.
yearStart, yearEnd	Inclusive. yearEnd empty means the latest year available.
flows, products	Optional dimension filters, such as ["ESOLARPV", "EWIND"] for ElecGenByFuel or ["COAL"] for CO2BySource. Unknown codes fail with the available list.
maxRows	Stop after this many rows (up to 20,000). With all indicators, they are read in catalogue order.

Listing example: {"listIndicators": true}. The first listing computes statistics for every indicator and can take a minute; the result is then cached for 24 hours.

Standby HTTP

• GET /query?indicator=ElecGenByFuel&country=DEU&year=2022&flow=ESOLARPV returns rows. indicator, country, flow and product accept comma-separated lists; yearStart/yearEnd can replace year; with no year parameter the latest year per country is returned. maxRows is limited to 100. An unknown code returns HTTP 400 with suggestions.
• GET /indicators?search=solar is free and returns matching indicators with unit, years, country count and flow/product codes. AI agents can use Apify MCP to run a batch and retrieve its dataset. For an immediate response, search free GET /indicators, then call GET /query.

The OpenAPI description is in .actor/web_server_openapi.json. Apify Standby URLs require an Apify API token; use the URL shown on the Actor's Endpoints tab. Enable Standby in Actor settings when deploying.

Output

One dataset row per country, indicator, year, flow and product. Two dimensions are never merged: an indicator with 13 generation sources returns 13 rows per country-year. These rows came from a local run on 25 September 2026 (indicators: ["all"], countries: ["DEU"], year 2022):

{
  "country": "DEU",
  "country_name": "Germany",
  "indicator": "ElecGenByFuel",
  "indicator_name": "Electricity generation by source",
  "year": 2022,
  "value": 61022,
  "unit": "GWh",
  "flow": "ESOLARPV",
  "flow_label": "Solar PV",
  "product": "ELECTR",
  "product_label": "Electricity",
  "source_dataset": "Electricity Information",
  "source_retrieved_at": "2026-09-25T16:06:37.112Z",
  "source_age_hours": 0.042,
  "...": "..."
}

Single-series indicators have one flow and product: null:

{ "country": "DEU", "country_name": "Germany", "indicator": "SDG72modern", "year": 2022, "value": 19.56, "unit": "%",
  "flow": "MODREN", "flow_label": "Share of modern renewables", "product": null, "product_label": null,
  "source_dataset": "Sustainable Development Goal 7", "...": "..." }

A listIndicators row:

{ "indicator": "GasPrice", "indicator_name": "Gasoline price", "unit": "USD/litre", "source_dataset": "World Energy Prices",
  "categories": ["Prices"], "year_start": 1990, "year_end": 2025, "country_count": 108, "row_count": 2487,
  "flows": [{ "code": "PRICE", "label": "Price (USD/litre)" }],
  "products": [{ "code": "GASOMID.TRANS", "label": "Mid-grade motor gasoline" }], "status": "ok" }

RUN_SUMMARY records the number delivered, the stop reason, stale-cache use and the indicators and IEA datasets included. A listing also writes the INDICATOR_CATALOGUE record. Empty valid queries succeed with zero rows. If data cannot be retrieved, a batch run fails and Standby returns HTTP 502; a spending cap yields only charged rows.

Pricing

No price is configured by this repository. The historical proposal was USD 0.001 per row; it is not an established Store price. In PPE mode, batch output uses the priced synthetic apify-default-dataset-item event when present; otherwise it charges the custom energy-row event. Standby needs the custom energy-row event. The indicator list (listIndicators, GET /indicators) never charges a row event; if the synthetic dataset-item event is priced, a listing run writes only the INDICATOR_CATALOGUE record so that only the automatic apify-actor-start event applies. Outside PPE mode, rows are delivered without event charges.

Use cases

• Look up a country's electricity mix, CO2 by sector or energy supply by source with the IEA dataset named on every row.
• Compare indicators across countries and years in one dataset, with units and dimensions explicit.
• Search the free catalogue, then request bounded data with age in every result.

FAQ

Which indicators are available? Every code in the live IEA catalogue: 78 on 25 September 2026. Run {"listIndicators": true} or call GET /indicators. Both are free.

I typed a code and the run failed. Codes are validated against the catalogue. The error lists the five closest codes, for example ElecGenByFule suggests ElecGenByFuel.

Why several rows for one country and year? Many indicators have a flow dimension (fuel, sector, import/export) and some a product dimension (coal, oil, gas). Each combination is its own row with flow and product codes and labels. Use flows/products to filter.

Why is a country-year missing? Coverage is uneven, and IEA marks some observations as null; those are dropped rather than reported as zero. A zero-row result is different from a retrieval failure.

Why is country_name null? About 90 IEA codes (small territories and a few aggregates such as MIDDLEEAST) have no entry in IEA's country list. The raw code is kept and can be requested directly.

Are the SDG71 values after 2024 forecasts? IEA publishes SDG71 through 2050 without labelling those years. Treat years after the latest historical release as IEA-provided values of unknown status.

How recent is the data? Latest years are 2022 to 2025 depending on the indicator. The retrieval timestamp records when the data was retrieved, not a newer observation year.

Is this Actor affiliated with IEA? No. It is independent of and not endorsed by IEA.

Why is the first listing slow? Units, years and country counts are computed from every full indicator. The result is cached for 24 hours.