World Bank Open Data -- Energy Skill

Country codes: ISO2 codes separated by semicolons, or all for all countries, or WLD for world aggregate only.

Key Indicators by Domain

See references/api_reference.md for the full verified indicator catalog.

Electricity Generation Mix

Energy Consumption and Intensity

Petroleum and Gas Economics

Common Country Codes for PNGE

Aggregate Codes

Workflow

Step 1 -- Resolve Intent

Map the user's question to one or more indicator IDs. If the question involves:

• Country comparison -> select indicator + multiple country codes
• Time trend -> select indicator + single country + date range
• Global ranking -> select indicator + all countries + MRV=1
• Generation mix -> fetch multiple EG.ELC.* indicators for one country

If unsure which indicator matches, check references/api_reference.md or query the indicator metadata:

curl -s "https://api.worldbank.org/v2/topic/5/indicator?format=json&per_page=200" \
  | python3 -c "
import sys, json
data = json.load(sys.stdin)
for ind in data[1]:
    print(f'{ind[\"id\"]}: {ind[\"name\"]}')
"

Step 2 -- Fetch Data

Build the URL with appropriate filters. Default behavior:

• Use date=2015:2022 unless the user specifies a different range
• Use per_page=1000 to minimize pagination
• For rankings, use MRV=1 to get the most recent value per country

Single country time series:

curl -s "https://api.worldbank.org/v2/country/US/indicator/EG.ELC.NGAS.ZS?format=json&date=2010:2022&per_page=50"

Multi-country comparison:

curl -s "https://api.worldbank.org/v2/country/US;SA;RU;CN;IQ;AE;NO;CA/indicator/NY.GDP.PETR.RT.ZS?format=json&date=2015:2021&per_page=200"

Global ranking (all countries, most recent value):

curl -s "https://api.worldbank.org/v2/country/all/indicator/NY.GDP.PETR.RT.ZS?format=json&MRV=1&per_page=300"

Step 3 -- Parse Response

Response is a JSON array: [pagination_meta, data_records].

import json, urllib.request

url = "https://api.worldbank.org/v2/country/US/indicator/EG.ELC.NGAS.ZS?format=json&date=2015:2022"
with urllib.request.urlopen(url) as resp:
    data = json.loads(resp.read())

meta = data[0]      # {"page": 1, "pages": 1, "per_page": 50, "total": 8, ...}
records = data[1]   # [{"indicator": {...}, "country": {...}, "date": "2022", "value": 38.72}, ...]

Always check:

• meta["pages"] -- if greater than 1, paginate with &page=2, &page=3, etc.
• record["value"] -- can be null if no data for that country/year
• meta["total"] -- total records across all pages

Step 4 -- Filter and Sort

For rankings, filter out:

• Records where value is null
• Aggregate/region entries (ISO3 codes with digits or that are not 3 alpha chars)

# Filter to real countries with non-null values
valid = [
    r for r in records
    if r["value"] is not None
    and len(r.get("countryiso3code", "")) == 3
    and r["countryiso3code"].isalpha()
]
# Sort descending by value for rankings
ranked = sorted(valid, key=lambda r: r["value"], reverse=True)

Step 5 -- Produce Output

Format: Raw Data Table + Narrative

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

1. Current state -- most recent values and date for the queried countries
2. Trend -- direction and magnitude over the time window (use % change)
3. Comparative context -- how countries rank relative to each other
4. PNGE relevance -- what the data means for petroleum engineering (e.g., petrostate dependency, energy transition pace, gas market structure)
5. Units and caveats -- always state units; note data lag and limitations

Example output structure:

## Oil Rents as % of GDP -- Major Producers (2021)

| Country       | Oil Rents (% GDP) |
|---------------|-------------------|
| Iraq          | 42.79             |
| Saudi Arabia  | 23.69             |
| UAE           | 15.67             |
| Russia        | 9.67              |
| Norway        | 6.06              |
| Canada        | 2.83              |
| United States | 0.61              |
| China         | 0.31              |

**Summary:** Iraq derives the highest share of GDP from oil rents at 42.8% (2021),
followed by Saudi Arabia at 23.7%. The US, despite being the world's largest
crude producer, shows only 0.6% oil rent/GDP due to its highly diversified
economy. Oil rents dropped sharply across all producers in 2020 (COVID demand
shock) before rebounding in 2021. Data for 2022 is not yet available for this
indicator. Units are oil rents as defined by the World Bank: the difference
between the value of crude oil production at world prices and total costs of
production, expressed as a share of GDP.

Pagination

If meta["pages"] > 1, paginate:

import json, urllib.request

all_records = []
page = 1
while page <= total_pages:
    url = f"...&page={page}&per_page=1000"
    with urllib.request.urlopen(url) as resp:
        data = json.loads(resp.read())
    meta = data[0]
    total_pages = meta["pages"]
    all_records.extend(data[1] or [])
    page += 1

For country/all queries, expect ~266 records per year (countries + aggregates). A 10-year range for all countries produces ~2660 records across ~3 pages.

Error Handling

API error response (HTTP 200 with error body):

[{"message": [{"id": "175", "key": "Invalid format", "value": "The indicator was not found."}]}]

Always check if data[0] contains a "message" key before accessing data[1].

Archived Indicators

These indicators are frequently referenced but no longer available in the live WDI (Source 2). They were moved to Source 57 (WDI Database Archives) and do not return data:

Data Quality and Caveats

• Annual resolution only -- no monthly, weekly, or daily data available. For high-frequency energy data, use the EIA skill instead.
• 1-2 year data lag -- most energy indicators report through 2022 as of 2026. Resource rent indicators often lag an additional year (latest: 2021).
• Null values are common -- many developing countries have gaps in energy data. Always filter nulls before ranking or computing averages.
• Aggregate codes in rankings -- when querying all countries, the response includes regional aggregates (World, OECD, Sub-Saharan Africa, etc.) alongside individual countries. Filter by ISO3 code length and alpha-only characters.
• Methodology changes -- WDI definitions can change between releases. Check indicator.sourceNote in the indicator metadata for current methodology.
• Source organizations vary -- electricity data comes from IEA, rent data from World Bank estimates, trade data from COMTRADE. Methodological differences may cause slight inconsistencies across indicators.

Implementation Notes

• Use python3 (stdlib only) for all API calls and data processing
• Use urllib.request and json -- no external dependencies needed
• Python client -- see references/python_example.py for a complete stdlib-only client with WorldBankClient, QueryParams, ranking helpers, and formatted table output
• Response parsing -- always access data[0] for pagination metadata and data[1] for records; check for "message" key in data[0] for errors
• Filtering aggregates -- when building country rankings, exclude records where countryiso3code contains digits or is not exactly 3 alpha characters
• Rate limiting -- add 100ms delay between paginated requests; no hard limit published but the API is shared infrastructure