# IEA Energy Data Scraper \[$1.50/1K💰] | CO2 | Electricity (`ahmed_jasarevic/iea-public-energy-data`) Actor

Extract free IEA energy statistics for 78 indicators and 185 countries: CO2 emissions, electricity generation, renewables, supply, consumption and prices. No API key needed.

- **URL**: https://apify.com/ahmed_jasarevic/iea-public-energy-data.md
- **Developed by:** [Ahmed Jasarevic](https://apify.com/ahmed_jasarevic) (community)
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.40 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
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 Public Energy Data Scraper

Extract free energy statistics from the International Energy Agency (IEA) — CO2 emissions, electricity generation, renewables, oil, gas, coal, energy supply and consumption, prices, efficiency and SDG7 indicators — without a browser, an API key, or a paid subscription.

This Apify Actor uses the public API behind the [IEA Data Browser](https://www.iea.org/data-and-statistics/data-tools/energy-statistics-data-browser) and returns tidy, analysis-ready rows that drop straight into CSV, Excel, BI tools or a database.

### Build Energy & Climate Datasets For Analysis

- **CO2 and emissions research** — pull greenhouse-gas and CO2 emission time series by country or region.
- **Electricity and renewables tracking** — extract generation by source (solar, wind, hydro, nuclear) for any country set.
- **Energy market and price analysis** — compare energy prices, supply, consumption and efficiency indicators across countries.
- **Climate and SDG reporting** — collect SDG7 energy-access and renewables indicators for dashboards and reports.
- **Data journalism and academic research** — assemble reproducible historical time series from a single run.

### How It Works

![How the IEA Energy Data Scraper works: indicator and country codes become normalized energy time-series rows without a browser or API key.](https://api.apify.com/v2/key-value-stores/oeuA0kLOyhbRM4fzt/records/how-it-works-iea-public-energy-data)

The Actor loads the live IEA indicator and country catalogs, validates every selected code and batches countries into parallel indicator requests. Year, flow, product, null-value and latest-only filters are applied before rows are pushed.

Each row covers one indicator, country, year, flow and product with its value, unit, labels, categories and source dataset. Catalog modes return indicator and country metadata.

1. The Actor fetches the live IEA indicator and country catalogs.
2. Selected indicators and countries are validated and normalized (unknown codes fail with suggestions, never silent wrong data).
3. Countries are split into batches and each indicator is fetched in parallel with a configurable concurrency limit.
4. Year, flow, product, null-value and latest-only filters are applied.
5. Normalized rows are pushed to the Apify dataset in batches.

No Apify Proxy is needed and no browser is launched. The Actor identifies itself with a clear User-Agent, retries rate limits and transient server errors with exponential backoff, and reports partial failures and graceful cancellation.

### Input Parameters

| Field | Type | Required | Default | Notes |
| --- | --- | --- | --- | --- |
| `mode` | string | No | `data` | `data` fetches statistics; `indicators` and `countries` return the live catalogs. |
| `indicators` | array | No | `["TESbySource"]` | Indicator IDs such as `TotCO2`, `ElecGenByFuel`, `SDG71`, `GasPrice`, or `["all"]` for all 78. |
| `countries` | array | No | `["WORLD"]` | ISO 2/3 codes, IEA codes, names, regions, or `["all"]`. E.g. `DE`, `DEU`, `Germany`, `EU27_2020`. |
| `startYear` | integer | No | `1990` | First year, inclusive. `0` = earliest available. |
| `endYear` | integer | No | `0` | Last year, inclusive. `0` = latest available. |
| `latestOnly` | boolean | No | `false` | Keep only the most recent year per indicator and country/region. |
| `includeNullValues` | boolean | No | `false` | Keep rows where the IEA reports no numeric value. |
| `flows` | array | No | `[]` | Optional flow codes or labels, e.g. `ESOLARPV`, `EWIND`, `Coal`. |
| `products` | array | No | `[]` | Optional product codes or labels, e.g. `ELECTR`, `TOTAL`, `Electricity`. |
| `maxConcurrency` | integer | No | `6` | Simultaneous requests, 1–20. |
| `countryBatchSize` | integer | No | `25` | Countries per API request, 1–100. |
| `maxRows` | integer | No | `0` | Stop after this many rows. `0` = no limit. |

Flow and product filters match both API codes and human-readable labels, case-insensitively.

### Output Fields

One row per indicator, country/region, year, flow and product:

`recordType` (`energyStat`, `indicator`, `country`), `indicator`, `indicatorName`, `categories`, `country`, `countryName`, `iso2`, `iso3`, `year`, `value`, `unit`, `flow`, `flowLabel`, `product`, `productLabel`, `seriesLabel`, `statsCode`, `isRegion`, `sourceDataset`, `sourceUrl`, `retrievedAt`, `note`.

The dataset includes two views: **Energy data** and **Catalogs**.

### Example Input

Latest CO2 emissions for three countries:

```json
{
  "mode": "data",
  "indicators": ["TotCO2"],
  "countries": ["DEU", "FRA", "USA"],
  "latestOnly": true
}
```

Solar and wind electricity generation for the EU since 2015:

```json
{
  "mode": "data",
  "indicators": ["ElecGenByFuel"],
  "countries": ["EU27_2020"],
  "startYear": 2015,
  "flows": ["ESOLARPV", "EWIND"]
}
```

List the full indicator catalog:

```json
{ "mode": "indicators" }
```

### Example Output

```json
{
  "recordType": "energyStat",
  "indicator": "ElecGenByFuel",
  "indicatorName": "Electricity generation by source",
  "categories": ["Electricity and heat", "Energy supply"],
  "country": "DEU",
  "countryName": "Germany",
  "year": 2022,
  "value": 61022,
  "unit": "GWh",
  "flow": "ESOLARPV",
  "flowLabel": "Solar PV",
  "product": "ELECTR",
  "productLabel": "Electricity",
  "seriesLabel": "Solar PV",
  "sourceDataset": "Electricity Information",
  "sourceUrl": "https://www.iea.org/data-and-statistics",
  "retrievedAt": "2026-10-20T12:00:00.000Z"
}
```

Catalog modes return metadata rows instead:

```json
{
  "recordType": "indicator",
  "indicator": "TotCO2",
  "indicatorName": "Total CO2 emissions",
  "categories": ["CO2 emissions", "Key indicators"],
  "sourceDataset": "World Energy Balances",
  "sourceUrl": "https://www.iea.org/data-and-statistics",
  "note": null
}
```

### Automate Energy Data Refreshes With Schedules & Webhooks

- **Schedule monthly or quarterly runs** to keep energy and emissions time series current as the IEA republishes data.
- **Pipe results to Google Sheets, a data warehouse, Zapier, Make or your own webhook** for automated dashboards and alerts.
- **Read the dataset through the Apify REST API** to feed a data pipeline, BI tool or research notebook.
- **Use `latestOnly`** for compact "current value" snapshots, or a year range for full history.

### Related Actors

- [EIA Energy Scraper](https://apify.com/fortuitous_pirate/eia-energy-scraper) — US Energy Information Administration data (petroleum, electricity sales, natural gas prices) to complement IEA global series.
- [IEA Energy Data (SDG7 & energy indicators)](https://apify.com/aitorsm/iea-energy-data) — an alternative IEA indicator query tool with batch, HTTP and MCP access.
- [FRANCE Energy Ratings (DPE)](https://apify.com/euroscrape/france-energy-ratings) — building-level energy performance certificates for France.
- [data.gov.my Scraper](https://apify.com/jungle_synthesizer/datagovmy-malaysia-statistics-scraper) — Malaysia open-data statistics, including fuel prices and industrial production.
- [Wikipedia Scraper](https://apify.com/ahmed_jasarevic/wikipedia-scraper) — enrich country and topic context for reports.

### Frequently Asked Questions

#### Why use this Actor instead of the official IEA API?

The IEA's formal Releases API with an API key is offered only to customers on an Enterprise or Global Enterprise licence. The public data behind the IEA Data Browser, however, is free to query. This Actor uses that free public API, so you get the Data Browser's indicators without a paid licence or API key.

#### What are alternatives to scraping IEA data?

Alternatives include the EIA (US data) for US-specific energy series, Eurostat for EU statistics, or the free IEA Data Browser manually. This Actor automates the public IEA Data Browser into clean rows and adds live indicator and country catalogs so you can discover valid codes in-run.

#### Is IEA data free to use?

Many IEA series are published under the CC BY 4.0 licence, but terms can vary by dataset. This Actor only accesses free, public data; it does not access IEA paywalled products or paid licences. Check the source page for each indicator before redistributing derived data.

#### How many indicators and countries are covered?

78 public IEA indicators and 185 countries, regions and aggregates, including ISO country codes, `WORLD`, `EU27_2020`, `G20`, OECD aggregates and IEA regions.

#### Can I get historical time series?

Yes. Coverage is typically 1960 or 1990 through the latest available year, depending on the indicator. Use `startYear` and `endYear` to bound the range.

#### Why does `latestOnly` sometimes return a projection?

Some indicators include projections — for example the SDG7 series extends to 2050 — so `latestOnly` selects the latest reported year, which can be a projection. Set `endYear` to a historical year to exclude projections.

### For AI Agents & LLM Apps

Purpose: return tidy IEA energy statistics rows (or catalog metadata) for selected indicators, countries and years.

Minimal working input:

```json
{ "mode": "data", "indicators": ["TotCO2"], "countries": ["DEU"], "latestOnly": true }
```

Catalog-discovery variant:

```json
{ "mode": "indicators" }
```

Output fields: `recordType, indicator, indicatorName, categories, country, countryName, iso2, iso3, year, value, unit, flow, flowLabel, product, productLabel, seriesLabel, statsCode, isRegion, sourceDataset, sourceUrl, retrievedAt, note`.

Behaviors an agent should know:

- `mode` controls the output shape: `data` = statistics rows, `indicators` / `countries` = catalog metadata rows.
- `["all"]` in `indicators` or `countries` expands to every available code — this can be very large; bound it with `maxRows` and year filters.
- `latestOnly: true` keeps one row per indicator/country; it can select a projection year (see FAQ).
- Indicator IDs are case-insensitive and also accept full names; unknown values fail with suggestions rather than returning wrong data.
- Billing: pay-per-event — each `result` row is $0.0015, plus a symbolic $0.00005 Actor-start event.

### Legal & Compliance Disclaimer

This is an independent Actor and is not affiliated with, endorsed by, or sponsored by the International Energy Agency (IEA). It accesses only the free, public data exposed through the public API used by the IEA Data Browser; no login is required, no CAPTCHA solving is performed, and it does not access IEA paywalled products, licences or access controls. IEA statistics are subject to the [IEA terms](https://www.iea.org/terms) and, for many series, the [CC BY 4.0](https://www.iea.org/terms/creative-commons-cc-licenses) licence; terms vary by dataset. Users are responsible for attributing the source and complying with the applicable IEA licence terms and any other applicable law when using or redistributing the data.

### SEO Keywords

iea energy data, iea data browser, iea statistics api, international energy agency data, energy statistics scraper, co2 emissions data, co2 emissions by country, electricity generation by source, renewables data, energy supply and consumption data, energy price data, energy efficiency indicators, sdg7 energy access data, climate data scraper, open energy data, energy time series, world energy balances data, greenhouse gas emissions data, energy data api, iea alternative

# Actor input Schema

## `mode` (type: `string`):

Data fetches energy statistics. Indicators and countries output the live IEA catalogs instead of statistics.

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

Indicator IDs such as TESbySource, TotCO2, ElecGenByFuel, SDG71, or GasPrice. Use \["all"] for every public indicator. The indicator catalog mode lists all IDs.

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

ISO 2/3 codes (DE, DEU), IEA codes (UK), country or region names (Germany, World, EU27_2020), or \["all"] for every country and region. Use the country catalog mode to browse options.

## `startYear` (type: `integer`):

First year to include, inclusive. Use 0 to include the earliest year available.

## `endYear` (type: `integer`):

Last year to include, inclusive. Use 0 to include the latest year available.

## `latestOnly` (type: `boolean`):

Keep only the most recent year for each indicator and country or region. Some indicators include projections, so the latest year can be in the future; set an end year to exclude them.

## `includeNullValues` (type: `boolean`):

Keep rows where the IEA reports no numeric value. When disabled, rows with null values are omitted.

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

Optional flow codes or labels to keep, such as ESOLARPV, EWIND, or Coal. Matches both codes and labels, case-insensitively. Leave empty for all flows.

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

Optional product codes or labels to keep, such as ELECTR, TOTAL, or Electricity. Matches both codes and labels, case-insensitively. Leave empty for all products.

## `maxConcurrency` (type: `integer`):

Maximum number of simultaneous IEA API requests. Higher values finish faster but put more load on the IEA service.

## `countryBatchSize` (type: `integer`):

Number of countries or regions sent in each IEA API request. Larger batches use fewer requests but produce larger responses.

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

Stop after this many dataset rows. Use 0 for no limit. The limit applies across all indicators.

## Actor input object example

```json
{
  "mode": "data",
  "indicators": [
    "TESbySource"
  ],
  "countries": [
    "WORLD"
  ],
  "startYear": 1990,
  "endYear": 0,
  "latestOnly": false,
  "includeNullValues": false,
  "flows": [],
  "products": [],
  "maxConcurrency": 6,
  "countryBatchSize": 25,
  "maxRows": 0
}
```

# Actor output Schema

## `results` (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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("ahmed_jasarevic/iea-public-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 = {}

# Run the Actor and wait for it to finish
run = client.actor("ahmed_jasarevic/iea-public-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 '{}' |
apify call ahmed_jasarevic/iea-public-energy-data --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,ahmed_jasarevic/iea-public-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/4UqCDRdsvwDLCLMqK/builds/CoyDqHvA9HwNRAQYn/openapi.json