# IEA Energy Data (SDG7 & energy indicators) (`aitorsm/iea-energy-data`) Actor

Query any indicator in the public IEA indicator catalogue by country and year, with a free indicator list, flow and product dimensions, provenance and source age. Includes batch, HTTP and MCP access.

- **URL**: https://apify.com/aitorsm/iea-energy-data.md
- **Developed by:** [Aitor Sanchez-Mansilla](https://apify.com/aitorsm) (community)
- **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 1 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.50 / 1,000 data points

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## 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):

```json
{
  "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`):

```json
{
  "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`:

```json
{ "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:

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

# Actor input Schema

## `listIndicators` (type: `boolean`):

Output one row per indicator in the live IEA catalogue (code, name, unit, IEA dataset, years available, country count, flow and product dimensions) instead of data. No row event is charged. The first run can take a minute because it computes statistics for every indicator; later runs use a 24-hour cache.

## `indicators` (type: `array`):

IEA indicator codes such as SDG72modern, TotCO2, ElecGenByFuel or TESbySource, validated against the current IEA catalogue (78 codes on 2026-09-25). Enter a single item all for every indicator. Run with listIndicators to see codes, units and years.

## `countries` (type: `array`):

ISO 2 or ISO 3 country codes, such as US or USA, a region code such as WORLD, or an IEA country code. Enter a single item all for every country (regional aggregates are then excluded).

## `yearStart` (type: `integer`):

Inclusive start year. Coverage starts in 1990 or 2000 depending on the indicator.

## `yearEnd` (type: `integer`):

Inclusive end year. Leave empty for the latest year available (2022–2025 for historical series; SDG71 extends to 2050).

## `flows` (type: `array`):

Optional flow codes to keep, such as ESOLARPV in ElecGenByFuel or TOTTRANS in CO2BySector. Flows are the sector, fuel or series dimension of an indicator.

## `products` (type: `array`):

Optional product codes to keep, such as COAL in CO2BySource or NATGAS in TESbySource.

## `maxRows` (type: `integer`):

Stop after this many rows even when more data exists.

## Actor input object example

```json
{
  "listIndicators": false,
  "indicators": [
    "SDG72modern"
  ],
  "countries": [
    "USA"
  ],
  "yearStart": 2020,
  "maxRows": 1000
}
```

# Actor output Schema

## `overview` (type: `string`):

No description

## `runSummary` (type: `string`):

No description

## `indicatorCatalogue` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "indicators": [
        "SDG72modern"
    ],
    "countries": [
        "USA"
    ],
    "yearStart": 2020
};

// Run the Actor and wait for it to finish
const run = await client.actor("aitorsm/iea-energy-data").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "indicators": ["SDG72modern"],
    "countries": ["USA"],
    "yearStart": 2020,
}

# Run the Actor and wait for it to finish
run = client.actor("aitorsm/iea-energy-data").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "indicators": [
    "SDG72modern"
  ],
  "countries": [
    "USA"
  ],
  "yearStart": 2020
}' |
apify call aitorsm/iea-energy-data --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,aitorsm/iea-energy-data"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/C5GoRCnk3HHoFIMR3/builds/838yMDogaGY1cef5g/openapi.json