IEA Open Data Skill

Fetches and analyzes international energy data from the IEA free API endpoints at api.iea.org. No API key is required for these endpoints.

Important limitation: The IEA paywalls most of its detailed energy balance, supply, and demand data behind a subscription. This skill covers only the free, open endpoints that return JSON data without authentication.

Free Endpoints (Verified Working)

Endpoint	Description	Records
/evs	Global EV Tracker -- sales, stock, charging, projections	~16,000
/prices	Energy end-use prices by country, sector, product	~41,000
/ghg	CO2 and GHG emissions from fuel combustion by country	~207,000
/nze	Net Zero Emissions by 2050 scenario data	~6,700
/ccus	CCUS policies and regulations database	~90
/sdg	SDG 7 energy access indicators (large dataset)	varies

No API Key Required

All endpoints are open. No authentication header needed. Simply:

curl -s "https://api.iea.org/evs"

---

API Structure

Base URL: https://api.iea.org/

All endpoints return JSON arrays of objects. Filter by appending query parameters that match field names in the response objects.

General query pattern:

GET https://api.iea.org/{endpoint}?{field1}={value1}&{field2}={value2}

Parameters use the exact field names from the response JSON. Some endpoints use human-readable names (e.g., region, year), others use CODE_ prefixed fields (e.g., CODE_COUNTRY, CODE_PRODUCT).

---

Endpoint Details

1. Electric Vehicles (/evs)

Global EV Tracker data: sales, stock, charging infrastructure, and STEPS projections.

Fields: region, category, parameter, mode, powertrain, year, unit, value

Query parameters (case-sensitive, use exact values):

Parameter	Example Values
region	USA, China, Europe, World, Norway, Germany, etc.
category	Historical, Projection-STEPS
parameter	EV sales, EV stock, EV sales share, EV stock share, EV charging points, Electricity demand, Battery demand, Oil displacement Mbd
mode	Cars, Vans, Buses, Trucks, 2 and 3 wheelers, EV
powertrain	BEV, PHEV, FCEV, EV
year	2010 through 2030

Example:

# US EV car sales in 2023
curl -s "https://api.iea.org/evs?region=USA&category=Historical&parameter=EV+sales&mode=Cars&year=2023"

# Global EV stock share trend
curl -s "https://api.iea.org/evs?region=World&category=Historical&parameter=EV+stock+share&mode=Cars&powertrain=EV"

2. Energy Prices (/prices)

End-use energy prices by country, sector, product, with annual and monthly data.

Fields: CODE_COUNTRY, CODE_YEAR, CODE_SECTOR, CODE_PRODUCT, CODE_INDICATOR, CODE_UNIT, Unit, Country, Product, Sector, Currency, Value, updated_at

Query parameters (use CODE_ fields for filtering):

Parameter	Example Values
CODE_COUNTRY	USA, FRANCE, GERMANY, JAPAN, CHINA, BELGIUM, etc.
CODE_SECTOR	TRANS, IND, RES, ELEGEN, NA
CODE_PRODUCT	GASOLINE, DIESEL, NATGAS, ELECT, LPG, LIGHTFO, FUELOIL, STEAMCO, HEATPUM
CODE_INDICATOR	PRICE, PRICEMONTHLY, PRICE CONVERTED, HEATHOUSE, SHOWER, COOKING, CARS
CODE_UNIT	USDCUR, NCCUR, EXTAX, TAX, USDPPP

Example:

# US gasoline prices in transport sector
curl -s "https://api.iea.org/prices?CODE_COUNTRY=USA&CODE_PRODUCT=GASOLINE&CODE_SECTOR=TRANS"

# Natural gas residential prices across OECD
curl -s "https://api.iea.org/prices?CODE_PRODUCT=NATGAS&CODE_SECTOR=RES&CODE_INDICATOR=PRICE"

3. GHG Emissions (/ghg)

CO2 and GHG emissions from fuel combustion, by country, product, and flow type. Historical data from 1971 to most recent year.

Fields: CODE_COUNTRY, COUNTRY, CODE_PRODUCT, PRODUCT, CODE_TIME, TIME, CODE_FLOW, FLOW, VALUE

Query parameters (use CODE_ fields):

Parameter	Example Values
CODE_COUNTRY	USA, CHN, IND, DEU, JPN, WORLD, etc. (OECD-style codes)
CODE_PRODUCT	TOTAL, COAL, OIL, NATGAS, BIOWASTE, HYDRO, NUCLEAR, SOLWIND, OTHER
CODE_FLOW	CO2FUEL (total CO2 from fuel combustion), CO2GDP (CO2/GDP), CO2POP (CO2/capita), GHGFUEL (total GHG), ELYIND (electricity industry), TRANSP (transport), INDUST (industry), BUILD (buildings)

Example:

# US total CO2 from fuel combustion
curl -s "https://api.iea.org/ghg?CODE_COUNTRY=USA&CODE_PRODUCT=TOTAL&CODE_FLOW=CO2FUEL"

# CO2 intensity (per GDP) for major emitters
curl -s "https://api.iea.org/ghg?CODE_PRODUCT=TOTAL&CODE_FLOW=CO2GDP"

Note: Without filters, this endpoint returns ~207K records. Always filter by at least CODE_COUNTRY or CODE_FLOW to keep response sizes manageable.

4. Net Zero Emissions Scenario (/nze)

IEA Net Zero Emissions by 2050 (NZE) scenario data -- energy supply, demand, capacity, emissions projections from 2019 to 2050.

Fields: Year, Product, Flow, Unit, Category, Value

Query parameters:

Parameter	Example Values
Year	2019, 2025, 2030, 2035, 2040, 2050
Product	Total, Oil, Coal, Natural gas, Nuclear, Solar PV, Wind, Bioenergy, Hydrogen, Electricity, etc.
Flow	Total primary energy demand, Electricity generation, Power sector, Buildings, Transport, Industry, etc.
Category	Energy, CO2 combustion and processes emissions, CO2 removal, Capacity, Economic indicators, Population indicators, etc.

Example:

# Oil demand in NZE scenario for milestone years
curl -s "https://api.iea.org/nze?Product=Oil&Flow=Total+primary+energy+demand"

# Electricity generation by source in 2050
curl -s "https://api.iea.org/nze?Year=2050&Flow=Electricity+generation"

5. CCUS Policies (/ccus)

Database of carbon capture, utilization and storage policies and regulations worldwide.

Fields: Base legislation (nested object with Policy ID, Title, Year, Jurisdiction, Region, Description, Status, Link), Region, Description, Link, Issue, Regulation or law

Example:

# All CCUS policies (small dataset, ~90 records)
curl -s "https://api.iea.org/ccus"

6. SDG 7 (/sdg)

SDG 7 energy access indicators. This is a large dataset; filter to avoid timeouts.

Example:

curl -s "https://api.iea.org/sdg" --max-time 30

---

Workflow

Step 1 -- Resolve Intent

Map the user's question to an endpoint:

User Intent	Endpoint	Key Filters
EV sales, stock, charging	/evs	region, year, parameter
Energy prices by country	/prices	CODE_COUNTRY, CODE_PRODUCT
CO2 emissions trends	/ghg	CODE_COUNTRY, CODE_FLOW
Net zero scenario	/nze	Year, Product, Flow
CCUS policies	/ccus	(small dataset, no filters needed)
Energy access	/sdg	(filter carefully)

Step 2 -- Fetch Data

Use curl to query the appropriate endpoint with filters:

curl -s "https://api.iea.org/{endpoint}?{filters}" --max-time 30

Default behavior:

• Always apply at least one filter on large endpoints (ghg, prices, evs)
• Use --max-time 30 since some endpoints are slow for unfiltered queries
• Parse JSON response with jq or python3 -c "import json..."

Step 3 -- Parse Response

All responses are flat JSON arrays:

[
  {"region": "USA", "category": "Historical", "parameter": "EV sales", "mode": "Cars", "powertrain": "BEV", "year": 2023, "unit": "Vehicles", "value": 1100000},
  ...
]

No pagination. The full dataset is returned in a single response (which is why filtering is important for large endpoints).

Step 4 -- Produce Output

Format: Raw Data Table + Narrative

Present a markdown table of the most relevant rows (cap at ~20 rows), then a narrative summary covering:

1. Current state -- most recent value(s) and year
2. Trend -- direction and magnitude over time (% change)
3. Cross-country comparison if applicable
4. Context -- relate to global energy transition goals
5. Units and caveats -- always state units; note data vintage

Example output structure:

## Global EV Car Sales by Region (2019-2023)

| Year | China     | Europe    | USA       | World     |
|------|-----------|-----------|-----------|-----------|
| 2023 | 8,100,000 | 3,200,000 | 1,400,000 | 14,200,000|
| 2022 | 6,900,000 | 2,700,000 | 990,000   | 10,500,000|
| ...  | ...       | ...       | ...       | ...       |

**Summary:** Global EV car sales reached 14.2 million in 2023, up 35% YoY.
China dominated with 57% share. BEVs accounted for ~70% of sales globally.
The IEA STEPS projection estimates 20+ million annual sales by 2030.
Data: IEA Global EV Tracker (api.iea.org/evs).

---

Error Handling

HTTP Code	Meaning	Action
200 + empty array	No matching data	Broaden filters or check field values
404	Endpoint not found	Verify endpoint name from the list above
500	Server error	Retry; IEA API can be intermittent
Timeout	Response too large	Add more filters to reduce dataset size
JSON parse error	Response truncated	Add filters; unfiltered large endpoints may truncate

---

Caveats and Data Limitations

• Free tier only: Most IEA detailed energy balance, supply, demand, and trade data requires a paid subscription. This skill covers only the 6 free endpoints listed above.
• No API key or auth: These endpoints are open but not officially documented as a stable API. Endpoints may change without notice.
• Large responses: The /ghg endpoint returns 207K+ records unfiltered. Always apply at least one filter. The /sdg endpoint can also be very large.
• Query parameters are case-sensitive: Use exact field values as shown in the response data (e.g., USA not usa, GASOLINE not gasoline).
• No pagination: Full datasets are returned in a single response. This means very large unfiltered queries may time out or return truncated JSON.
• Data vintage: Prices and GHG data are typically 1-2 years behind current. Check the updated_at field (prices) or max year (ghg) for data currency.
• STEPS projections (EVs): The category=Projection-STEPS data in the EVs endpoint reflects IEA Stated Policies Scenario, not a forecast.
• Country codes vary: The /ghg endpoint uses OECD-style codes (USA, CHN, DEU), while /prices uses longer names (FRANCE, GERMANY). Check the actual response data for the correct code format per endpoint.

---

Implementation Notes

• Use curl with --max-time 30 for all IEA requests (some endpoints are slow)
• For cross-endpoint queries, make separate requests and merge client-side
• URL-encode spaces as + in query parameters (e.g., EV+sales)
• All timestamps are in UTC; prices include an updated_at field
• See references/api_reference.md for the complete field value catalogs
• See references/python_example.py for a stdlib-only client example