US Energy Information Administration

What You're Getting

EIA Open Data provides comprehensive US energy data: petroleum production/supply/stocks, natural gas, electricity generation and capacity by source and state, coal, nuclear, renewables, and energy prices. Key series: weekly petroleum status, monthly electric power, annual energy review. Data organized by series ID (e.g. TOTAL.PAPRPUS2.A for US petroleum production). Also covers international energy data.

Ingestion Strategy

EIA API v2 is the preferred interface — free key, well-structured, returns JSON. Organize queries by route (e.g. /petroleum/sum/sndw for weekly supply and disposition). For bulk loads, EIA also offers bulk download files at eia.gov/opendata/bulkfiles.php — zipped JSON files for entire datasets.

import requests

API_KEY = "your_key"
# Weekly US crude oil production
url = "https://api.eia.gov/v2/petroleum/sum/sndw/data/"
params = {
    "api_key": API_KEY,
    "frequency": "weekly",
    "data[0]": "value",
    "facets[series][]": "WCRFPUS2",
    "sort[0][column]": "period",
    "sort[0][direction]": "desc",
    "length": 52
}
r = requests.get(url, params=params)
data = r.json()["response"]["data"]

Rate Limits & API Details

• Free API key at eia.gov/opendata — no published request limit for reasonable use
• Bulk files: eia.gov/opendata/bulkfiles.php — updated with each release, gzipped JSON
• API v2 base: api.eia.gov/v2
• Data routes browsable at api.eia.gov/v2 (returns available routes)

Schema Stability

EIA v2 API (2023) replaced the legacy v1 API — routes and field names changed. Series IDs in v1 format no longer work directly; map to v2 routes. Series codes within v2 are stable. Frequency codes: annual, monthly, weekly, hourly. Units vary by series — always pull the units field from the response.

Data Quality Gotchas

• API v1 vs v2: v1 series IDs (dot-notation) don't work in v2; check EIA's migration guide
• Weekly vs monthly: weekly petroleum data has a different series from monthly — they don't perfectly reconcile
• State-level data: not all series have state breakdowns; check facet availability before building state-level pipelines
• EIA estimates: recent months are often estimates that get revised; store revision timestamps

Tool Compatibility

• Python: eia-python or direct API calls; bulk files easily loaded with json + pandas
• R: direct API calls
• Airbyte: no official connector; community scripts
• Bulk JSON files load cleanly into BigQuery / Snowflake via standard JSON parsing

Benchmarking Approach

US crude oil production (weekly): should be ~12–13 million barrels/day for 2023–2024. Total electricity generation: ~4,000 TWh/year for US. After each weekly petroleum release (Wednesday, 10:30 AM ET), verify new data appears within 2 hours. Cross-check annual natural gas production against EIA Annual Energy Review published figure. Alert if weekly series gaps more than 10 days.