EIA Scraper — US & Global Energy Data (Petroleum, Gas, Electricity, Coal, Grid Ops)

Scrape official U.S. Energy Information Administration (EIA) open data — energy prices, production, consumption, stocks, imports, grid operations, and outlook forecasts across petroleum, natural gas, electricity, coal, nuclear, total energy, international energy, and more, broken down by US state, country, and time period. No API key, no login, no proxy required.

What this actor does

• 12 energy categories: Natural Gas, Petroleum, Coal, Electricity, Total Energy, Nuclear Outages, Short-Term Energy Outlook, State Energy Data System, International Energy, Petroleum Imports, Annual Energy Outlook, Electricity Grid Operations
• Filter by keyword, exact series ID, frequency (including hourly grid data), US state, and year range
• Flat, analysis-ready rows: one row per (series, time period) data point
• Empty fields are omitted — no null clutter in your dataset

Output per data point

• category — energy category label (e.g. Petroleum)
• seriesId — EIA series identifier (e.g. PET.RWTC.D)
• name, description — human-readable series description
• units — unit of measure (e.g. Dollars per Gallon, Thousand Barrels per Day, Megawatthours)
• frequency — Annual / Quarterly / Monthly / Weekly / Daily / Hourly (UTC) / Hourly (Local Time) / 4-Week Average
• geography — EIA geography code (e.g. USA-TX for a US state, ARM for Armenia, WLD for World) when the series is state/country-scoped
• geographyDestination — for Petroleum Imports, the US destination state/port (e.g. USA-MS) when geography holds the origin country
• latitude, longitude — decimal coordinates of the import terminal, populated only for Petroleum Imports series that publish them
• period — raw EIA period string (e.g. 2024, 2024Q1, 202401, 20240115, 20260717T06)
• periodYear — the 4-digit year extracted from period
• value — the numeric data value
• dataSource — the underlying data provider EIA credits for this series (e.g. Thomson-Reuters for WTI spot prices, EIA, U.S. Energy Information Administration for most others), when published
• lastUpdated — when EIA last refreshed this series
• sourceUrl — link to EIA's public query-browser page for this series
• recordType: "energyDataPoint", scrapedAt

Input

Field	Type	Default	Description
category	select	naturalGas	Which EIA dataset to query
keyword	string	–	Free-text match against series name/description/ID
seriesId	string	–	Exact EIA series ID lookup (auto-detects category)
frequency	select	any	annual / quarterly / monthly / weekly / daily / hourly / hourlyLocal / fourWeekAvg
region	select	US	Restrict to one US state (or US for no filter); for Petroleum Imports, matches the US destination state
startYear	int	–	Only include data from this year onward
endYear	int	–	Only include data up to this year
maxItems	int	100	Hard cap on emitted rows (1–5000)

Example: WTI crude oil daily spot price

{
  "category": "petroleum",
  "seriesId": "PET.RWTC.D",
  "maxItems": 500
}

Example: Weekly natural gas storage, keyword search

{
  "category": "naturalGas",
  "keyword": "working underground storage",
  "frequency": "weekly",
  "maxItems": 200
}

Example: California electricity retail sales, 2020–2024

{
  "category": "electricity",
  "keyword": "retail sales",
  "region": "CA",
  "startYear": 2020,
  "endYear": 2024
}

Example: US state-level total energy prices

{
  "category": "stateEnergyData",
  "keyword": "average price",
  "region": "TX",
  "frequency": "annual"
}

Example: International crude oil production by country

{
  "category": "internationalEnergy",
  "keyword": "Armenia",
  "maxItems": 100
}

Example: Crude oil imports into a US state, by origin country

{
  "category": "petroleumImports",
  "region": "MS",
  "startYear": 2024
}

Example: Long-term US electricity price outlook

{
  "category": "annualEnergyOutlook",
  "keyword": "electricity",
  "maxItems": 200
}

Example: Hourly grid generation by fuel type

{
  "category": "electricityGridOperations",
  "keyword": "solar",
  "frequency": "hourly",
  "maxItems": 500
}

Use cases

• Energy market research — track historical crude oil, gasoline, diesel, and natural gas prices
• Utility & grid analytics — electricity generation, sales, and customer counts by US state
• ESG / sustainability reporting — total-energy consumption trends by sector
• Academic & policy research — bulk time-series export for econometric modeling
• Trading & forecasting — Short-Term Energy Outlook (STEO) and Annual Energy Outlook (AEO) forward-looking series
• Nuclear reliability monitoring — reactor-level outage and capacity data
• Global energy comparisons — country-level production/consumption for 200+ countries and regions
• Trade-flow analysis — crude oil import volumes by origin country and US port/refinery
• Grid & renewables monitoring — hourly demand, generation-by-fuel, and interchange for every US balancing authority

Data Source

This actor reads EIA's free, keyless bulk-download files (published at eia.gov/opendata/bulkfiles.php) rather than EIA's api.eia.gov v2 REST API. Here's why:

• api.eia.gov/v2/... hard-requires a registered api_key query parameter. A request with no key, or an empty key, returns HTTP 403 {"error":{"code":"API_KEY_MISSING", ...}}. Free self-serve registration exists, but per this project's zero-cost policy an actor must not require end users to obtain and paste in their own API key.
• The API is hosted on the API Umbrella gateway shared with api.data.gov (confirmed via response headers), so its documented shared testing credential DEMO_KEY does work — but it is capped at a very low shared rate limit (observed X-Ratelimit-Limit: 10 per window, shared globally across every consumer of every federal API on that gateway). That's unusable for a reliable production scraper and isn't something EIA documents as intended for this purpose, so this actor does not hardcode it.
• EIA's bulk ZIP files (NG.zip, PET.zip, COAL.zip, ELEC.zip, TOTAL.zip, NUC_STATUS.zip, STEO.zip, SEDS.zip, INTL.zip, PET_IMPORTS.zip, AEO2026.zip, EBA.zip) require zero credentials, are served directly from eia.gov with no anti-bot gate, and contain the exact same underlying series data (in fact the same series_id/data[period, value] records) that the v2 API would return. This actor downloads the relevant bulk file per request and filters it in-memory to match your query.

The trade-off: the electricityGridOperations and electricity categories' bulk files are large (~660 MB and ~240 MB compressed respectively), so queries against them take noticeably longer than other categories. All other categories are small (a few MB to ~60 MB) and resolve quickly.

FAQ

Do I need an EIA API key? No. This actor uses EIA's public bulk-download files, which require no registration, login, or key.

How current is the data? EIA refreshes its bulk files on the same cadence as the source surveys — daily for petroleum/natural gas prices, weekly for storage, monthly/quarterly/annual for most other series. Each record's lastUpdated field reflects EIA's own refresh timestamp.

What's a "series"? EIA organizes data into time series — a single measured quantity over time (e.g. "Cushing, OK WTI Spot Price FOB, Daily"). Each series has a unique seriesId. This actor flattens each series' historical points into individual rows.

How do I find a series ID? Set keyword to a descriptive term (e.g. "WTI spot price", "retail gasoline", "natural gas storage") and browse the returned seriesId values, or browse EIA's own Open Data query browser.

Why is geography sometimes missing? Not every EIA category is geography-scoped. National/aggregate series (Short-Term Energy Outlook country-level forecasts, most Natural Gas series) omit it; state-level categories (Electricity, State Energy Data System, some Petroleum PADD series) populate it.

Why do the electricity and electricityGridOperations categories take longer to run? Their bulk files are the largest EIA publishes (~240 MB and ~660 MB respectively). All other categories are much smaller and typically finish in well under a minute.

Can I filter by PADD region (petroleum)? PADD regions aren't exposed as a dedicated dropdown (EIA encodes them inside series descriptions, e.g. "Gulf Coast (PADD 3)"), but keyword: "PADD 3" or keyword: "Gulf Coast" reliably finds them.

Can I filter International Energy data by country? Country isn't a separate dropdown (EIA covers 200+ countries and regions), but every series name embeds the country (e.g. "Petroleum and other liquids production, Armenia, Quarterly"), so keyword: "Armenia" reliably finds it.

What's the difference between geography and geographyDestination on Petroleum Imports rows? geography is the crude oil's origin (a country code, or WLD for "World"); geographyDestination is the receiving US state. Use the region filter to restrict by destination state.

Which Annual Energy Outlook edition does this actor use? The latest published edition (AEO2026), which projects US energy trends through 2050.

Is this official EIA data? Yes — every record comes directly from EIA's own published bulk files, unmodified beyond flattening and field renaming for consistency.