EIA US Energy Data Search
EIA US energy data gives you electricity retail prices, natural gas spot prices, petroleum costs, and state energy consumption profiles — all from a single actor run. Built for energy analysts, site-selection teams, commodity researchers, and policy professionals who need structured, up-to-date US energy market data without manual downloads from the EIA website.
Maintenance Pulse
90/100Cost Estimate
How many results do you need?
Pricing
Pay Per Event model. You only pay for what you use.
| Event | Description | Price |
|---|---|---|
| result-returned | Charged per result returned. Includes data transformation and structured output. | $0.03 |
Example: 100 events = $3.00 · 1,000 events = $30.00
Documentation
EIA US energy data gives you electricity retail prices, natural gas spot prices, petroleum costs, and state energy consumption profiles — all from a single actor run. Built for energy analysts, site-selection teams, commodity researchers, and policy professionals who need structured, up-to-date US energy market data without manual downloads from the EIA website.
This actor queries the US Energy Information Administration Open Data API v2 across four authoritative datasets: electricity retail sales (electricity/retail-sales), natural gas price summaries (natural-gas/pri/sum), petroleum retail prices (petroleum/pri/gnd), and the State Energy Data System (seds). It handles pagination automatically, applies 500ms inter-request delays to stay within EIA rate limits, and assembles every dataset into a single structured JSON report with a computed market insight score. No code required — the actor runs entirely in the browser console.
What data can you extract?
| Data Point | Source | Example |
|---|---|---|
| 📊 Electricity retail price | EIA electricity/retail-sales | 28.52 cents/kWh (CA, residential) |
| 💵 Electricity revenue | EIA electricity/retail-sales | $4,521.5 million (CA, 2025-12) |
| ⚡ Electricity sales volume | EIA electricity/retail-sales | 24,680.3 million kWh |
| 👤 Customer count | EIA electricity/retail-sales | 14,200,000 (CA residential) |
| 🔥 Natural gas spot price | EIA natural-gas/pri/sum | $3.42/MMBtu (Henry Hub) |
| ⛽ Gasoline retail price | EIA petroleum/pri/gnd | $3.24/gallon (regular, national) |
| 🛢️ Premium fuel price | EIA petroleum/pri/gnd | $4.08/gallon (premium, national) |
| 🏭 State total energy consumption | EIA SEDS (seds) | 13,642,800 billion Btu (TX, 2023) |
| 📈 Market insight score | Computed (0–100) | 40 — Moderate |
| 🏆 Top expensive states | Computed from electricity | CA: 28.52, NY: 24.18 cents/kWh |
| 💡 Average residential price | Computed from electricity | 22.05 cents/kWh (national avg) |
| 🏗️ Average industrial price | Computed from electricity | 7.82 cents/kWh (national avg) |
Why use EIA US Energy Data Search?
Downloading energy data manually from the EIA website means navigating multiple portals, exporting separate CSVs for each dataset, and reformatting everything before analysis. A data analyst doing this by hand typically spends 2–4 hours to assemble what this actor produces in under 2 minutes.
This actor combines four EIA datasets into one structured report in a single run. The output is immediately usable in spreadsheets, dashboards, or downstream analysis pipelines — no parsing, no reformatting.
- Scheduling — run weekly, monthly, or on any custom interval to track energy price trends over time without revisiting the EIA portal
- API access — trigger runs from Python, JavaScript, or any HTTP client to integrate EIA data into your own applications
- Proxy rotation — not required for the EIA API, but Apify's infrastructure handles retry logic and rate-limit backoff automatically
- Monitoring — get Slack or email alerts when runs fail or return unexpected results, so you never miss a data refresh
- Integrations — connect output directly to Zapier, Make, Google Sheets, HubSpot, or webhooks for automated downstream workflows
Features
- Four-dataset assembly in one run — queries electricity retail sales, natural gas prices, petroleum prices, and SEDS state profiles in a single execution, staggered by 1–3 seconds to respect EIA rate limits
- Paginated data fetching — automatically pages through results using
lengthandoffsetparameters against the EIA v2 API, up to 5,000 records per dataset per run - Exponential backoff retry — up to 4 attempts with exponential delay (2^attempt × 1000ms) on HTTP errors; handles 429 rate-limit responses with 2^attempt × 2000ms wait
- Sector filtering — restrict results to a single energy sector (
electricity,natural-gas,petroleum,coal) or fetch all sectors simultaneously - State-level filtering — pass any two-letter state code to scope results to a single state across all datasets simultaneously
- Date range filtering —
dateFromanddateToaccept YYYY-MM format for monthly data and YYYY for annual data, passed directly as EIAstart/endparameters - Electricity summary statistics — computes national average residential, commercial, and industrial prices; ranks states by most and least expensive residential electricity for the latest period
- Market insight scoring — a 0–100 score based on residential price thresholds (>20 cents = −15, >15 cents = −5, <10 cents = +10) and industrial price thresholds (>12 cents = −10, <6 cents = +8); levels are Favorable (65+), Moderate (45–64), Elevated (25–44), High Cost (<25)
- Dry-run mode — returns realistic sample data without consuming API quota; automatically activates when no API key is provided
- EIA API key validation — detects 401/403 responses and logs a direct registration link rather than failing silently
- Configurable result limits —
maxResultscontrols records per dataset from 1 to 5,000; petroleum data is additionally capped at 500 records to match EIA weekly series depth
Use cases for EIA energy data
Site selection and facility planning
Corporate real estate teams and operations managers comparing electricity costs across candidate states need granular, current price-by-sector data. Pull residential, commercial, and industrial rates for five target states in a single run, then compare directly in a spreadsheet. The market insight score adds an instant condition signal — a score below 25 flags a high-cost state worth deprioritizing before deeper analysis.
Energy market research and commodity trading
Commodity analysts tracking natural gas spot prices and gasoline retail trends need a reliable, structured data feed with historical depth. This actor pulls Henry Hub spot prices and weekly retail gasoline/diesel prices with configurable date ranges, delivering up to 5,000 records per dataset per run for time-series analysis.
Policy research and energy affordability studies
Policy researchers and think tanks studying energy burden by state need state-level electricity prices broken out by residential, commercial, and industrial sectors. Filter to a single state and enable SEDS state profiles to get total energy consumption figures alongside retail price data in one structured output.
Utility benchmarking
Utility analysts and regulatory consultants benchmarking rates against regional and national averages can run this actor monthly on a schedule, storing outputs in a dataset for trend analysis. The electricity summary section ranks the top 10 most and least expensive states for residential electricity in the latest reporting period.
Business intelligence and energy cost monitoring
Finance teams at energy-intensive businesses (manufacturing, data centers, cold storage) tracking input costs over time can schedule monthly runs and pipe results to a Google Sheet via Zapier. A sudden shift in the market insight score signals a meaningful change in energy cost conditions worth investigating.
Academic and journalistic research
Researchers and journalists covering energy markets, inflation, or regional economic conditions can use this actor to pull current and historical EIA data programmatically without navigating the EIA portal. The structured JSON output is directly importable into R, Python, or Jupyter notebooks for analysis.
How to search EIA US energy data
- Get a free EIA API key — Register at https://www.eia.gov/opendata/register.php. The key is emailed instantly, requires no payment, and grants access to the full EIA Open Data API v2.
- Configure your query — Enter your API key, choose a sector (or leave as "All Sectors"), optionally enter a two-letter state code like
TXorCA, and set a date range if you need a specific period. - Run the actor — Click "Start" and wait approximately 30–90 seconds. All four datasets are fetched in parallel with staggered starts; runtime scales with result count.
- Download results — Open the Dataset tab, then export as JSON, CSV, or Excel. Each run produces one report record containing all datasets and the market insight score.
Input parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
apiKey | string | No | — | Your EIA API key. Register free at eia.gov/opendata. Omitting triggers dry-run mode. |
dryRun | boolean | No | true | Return sample data without calling the API. Auto-activates when no API key is provided. |
sector | string | No | "all" | Energy sector: all, electricity, natural-gas, petroleum, coal |
state | string | No | — | Two-letter state abbreviation to filter all datasets (e.g. TX, CA, NY) |
frequency | string | No | "monthly" | Data frequency: weekly, monthly, quarterly, annual |
dateFrom | string | No | — | Start date in YYYY-MM (monthly) or YYYY (annual) format |
dateTo | string | No | — | End date in YYYY-MM (monthly) or YYYY (annual) format |
includeElectricity | boolean | No | true | Fetch electricity retail sales and prices by state and sector |
includeNaturalGas | boolean | No | true | Fetch natural gas price summaries (including Henry Hub spot price) |
includePetroleum | boolean | No | true | Fetch petroleum and gasoline retail price data (weekly) |
includeStateProfiles | boolean | No | false | Fetch SEDS state-level energy consumption data (annual, MSN: TETCB) |
maxResults | integer | No | 500 | Maximum records per dataset, from 1 to 5,000 |
Input examples
National snapshot — all sectors, most recent 12 months:
{
"apiKey": "YOUR_EIA_API_KEY",
"dryRun": false,
"sector": "all",
"frequency": "monthly",
"dateFrom": "2024-01",
"dateTo": "2025-01",
"includeElectricity": true,
"includeNaturalGas": true,
"includePetroleum": true,
"includeStateProfiles": false,
"maxResults": 500
}
State-level energy cost study — Texas with SEDS profiles:
{
"apiKey": "YOUR_EIA_API_KEY",
"dryRun": false,
"sector": "all",
"state": "TX",
"frequency": "monthly",
"includeElectricity": true,
"includeNaturalGas": true,
"includePetroleum": true,
"includeStateProfiles": true,
"maxResults": 1000
}
Electricity-only run for site selection — no API key (dry run):
{
"dryRun": true,
"sector": "electricity",
"frequency": "monthly",
"maxResults": 100
}
Input tips
- Register for a free API key first — the EIA key is free, instant, and required for real data. Without it, the actor returns sample data only.
- Start with defaults — leaving all boolean toggles at their defaults returns electricity, natural gas, and petroleum data in one run, which covers the most common analysis needs.
- Use state filtering for faster runs — filtering to a single state dramatically reduces result counts and execution time, especially for the electricity dataset.
- Enable state profiles separately —
includeStateProfilesis off by default because SEDS data is annual and high-volume. Enable it only when you need total consumption figures. - Match date format to frequency —
dateFrom/dateTomust be YYYY-MM for monthly/weekly data and YYYY for annual data. Mismatches return no results from the EIA API silently.
Output example
{
"reportType": "comprehensive",
"generatedAt": "2025-12-15T14:32:07.841Z",
"filters": {
"state": null,
"frequency": "monthly",
"dateFrom": "2025-01",
"dateTo": "2025-12"
},
"electricity": {
"records": [
{
"period": "2025-12",
"state": "CA",
"stateDescription": "California",
"sector": "RES",
"sectorName": "residential",
"revenue": 4521.5,
"sales": 24680.3,
"price": 28.52,
"customers": 14200000,
"revenueUnits": "million dollars",
"salesUnits": "million kilowatt hours",
"priceUnits": "cents per kilowatt-hour"
},
{
"period": "2025-12",
"state": "TX",
"stateDescription": "Texas",
"sector": "IND",
"sectorName": "industrial",
"revenue": 1245.3,
"sales": 18920.4,
"price": 7.82,
"customers": 42500,
"revenueUnits": "million dollars",
"salesUnits": "million kilowatt hours",
"priceUnits": "cents per kilowatt-hour"
}
],
"summary": {
"totalRecords": 4,
"latestPeriod": "2025-12",
"avgResidentialPrice": 22.05,
"avgCommercialPrice": 18.43,
"avgIndustrialPrice": 7.82,
"topExpensiveStates": [
{ "state": "CA", "price": 28.52 },
{ "state": "NY", "price": 24.18 },
{ "state": "MA", "price": 23.91 }
],
"topCheapStates": [
{ "state": "WY", "price": 9.14 },
{ "state": "ND", "price": 9.88 },
{ "state": "TX", "price": 13.45 }
]
}
},
"naturalGas": {
"records": [
{
"period": "2025-11",
"seriesId": "N3010US3",
"description": "Henry Hub Natural Gas Spot Price",
"state": "US",
"stateDescription": "United States",
"value": 3.42,
"unit": "Dollars per Million Btu",
"process": "Spot Price"
}
],
"latestPeriod": "2025-11",
"recordCount": 24
},
"petroleum": {
"records": [
{
"period": "2025-12-08",
"seriesId": "EMM_EPMR_PTE_NUS_DPG",
"description": "Weekly US Regular Gasoline Retail Price",
"area": "NUS",
"areaDescription": "US National Average",
"product": "EPMR",
"productDescription": "Regular Gasoline",
"value": 3.24,
"unit": "Dollars per Gallon"
},
{
"period": "2025-12-08",
"seriesId": "EMM_EPMP_PTE_NUS_DPG",
"description": "Weekly US Premium Gasoline Retail Price",
"area": "NUS",
"areaDescription": "US National Average",
"product": "EPMP",
"productDescription": "Premium Gasoline",
"value": 4.08,
"unit": "Dollars per Gallon"
}
],
"latestPeriod": "2025-12-08",
"recordCount": 52
},
"marketInsight": {
"score": 40,
"level": "Moderate",
"factors": [
"High avg residential electricity: 22.05 cents/kWh (-15)",
"Low avg industrial electricity: 7.82 cents/kWh (+8)",
"Total electricity sales tracked: 93,281 million kWh"
]
}
}
Output fields
| Field | Type | Description |
|---|---|---|
reportType | string | "comprehensive" or the specific sector name when filtered |
generatedAt | string | ISO 8601 timestamp of when the report was assembled |
filters.state | string | null | State abbreviation applied, or null for national data |
filters.frequency | string | Data frequency used for the run |
filters.dateFrom | string | null | Start date filter applied, or null |
filters.dateTo | string | null | End date filter applied, or null |
electricity.records[].period | string | Reporting period (e.g. 2025-12) |
electricity.records[].state | string | Two-letter state code |
electricity.records[].stateDescription | string | Full state name |
electricity.records[].sector | string | Sector code: RES, COM, IND, OTH, ALL |
electricity.records[].sectorName | string | Human-readable sector name |
electricity.records[].revenue | number | null | Revenue in million dollars |
electricity.records[].sales | number | null | Sales volume in million kWh |
electricity.records[].price | number | null | Retail price in cents per kWh |
electricity.records[].customers | number | null | Number of customers |
electricity.summary.latestPeriod | string | null | Most recent period in the electricity dataset |
electricity.summary.avgResidentialPrice | number | null | National average residential price in cents/kWh |
electricity.summary.avgCommercialPrice | number | null | National average commercial price in cents/kWh |
electricity.summary.avgIndustrialPrice | number | null | National average industrial price in cents/kWh |
electricity.summary.topExpensiveStates | array | Top 10 states by residential price, descending |
electricity.summary.topCheapStates | array | Top 10 states by residential price, ascending |
naturalGas.records[].period | string | Reporting period |
naturalGas.records[].seriesId | string | EIA series identifier |
naturalGas.records[].description | string | Series description (e.g. Henry Hub spot price) |
naturalGas.records[].state | string | State or area code |
naturalGas.records[].value | number | null | Price value |
naturalGas.records[].unit | string | Unit of measure (e.g. Dollars per Million Btu) |
naturalGas.records[].process | string | Process type (e.g. Spot Price, Wellhead) |
naturalGas.latestPeriod | string | null | Most recent period in the natural gas dataset |
naturalGas.recordCount | number | Total natural gas records returned |
petroleum.records[].period | string | Week ending date |
petroleum.records[].seriesId | string | EIA petroleum series identifier |
petroleum.records[].description | string | Series description |
petroleum.records[].area | string | Area or region code |
petroleum.records[].areaDescription | string | Area description (e.g. US National Average) |
petroleum.records[].product | string | Product code (e.g. EPMR for regular gasoline) |
petroleum.records[].productDescription | string | Product name |
petroleum.records[].value | number | null | Price in dollars per gallon |
petroleum.records[].unit | string | Unit of measure |
petroleum.latestPeriod | string | null | Most recent period in the petroleum dataset |
petroleum.recordCount | number | Total petroleum records returned |
stateProfiles.records[].period | string | Year (annual data) |
stateProfiles.records[].seriesId | string | EIA SEDS series identifier (e.g. TETCB) |
stateProfiles.records[].description | string | Series description |
stateProfiles.records[].state | string | Two-letter state code |
stateProfiles.records[].value | number | null | Consumption value |
stateProfiles.records[].unit | string | Unit of measure (Billion Btu) |
stateProfiles.latestPeriod | string | null | Most recent year in the SEDS dataset |
stateProfiles.recordCount | number | Total SEDS records returned |
marketInsight.score | number | Market condition score from 0 to 100 |
marketInsight.level | string | Favorable (65+), Moderate (45–64), Elevated (25–44), High Cost (<25) |
marketInsight.factors | array | List of scoring factors with point adjustments |
How much does it cost to search EIA energy data?
EIA US Energy Data Search uses pay-per-result pricing — you pay $0.003 per record returned. Platform compute costs are included.
| Scenario | Records | Cost per record | Total cost |
|---|---|---|---|
| Quick test (dry run) | 0 | $0.000 | Free |
| Small pull (single sector) | 100 | $0.003 | $0.30 |
| Standard run (all sectors) | 500 | $0.003 | $1.50 |
| Deep history pull | 2,000 | $0.003 | $6.00 |
| Maximum batch | 5,000 | $0.003 | $15.00 |
You can set a maximum spending limit per run to control costs. The actor stops when your budget is reached.
The EIA API itself is free — you only pay Apify platform costs for processing and storage. Compare this to Bloomberg Terminal energy data feeds at $2,000+/month or Wood Mackenzie subscriptions at $10,000+/year. Most users pulling monthly energy snapshots spend under $5/month.
EIA energy data search using the API
Python
from apify_client import ApifyClient
client = ApifyClient("YOUR_API_TOKEN")
run = client.actor("ryanclinton/eia-energy-data").call(run_input={
"apiKey": "YOUR_EIA_API_KEY",
"dryRun": False,
"sector": "all",
"frequency": "monthly",
"dateFrom": "2024-01",
"dateTo": "2025-01",
"includeElectricity": True,
"includeNaturalGas": True,
"includePetroleum": True,
"maxResults": 500,
})
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
if item.get("electricity") and item["electricity"].get("summary"):
summary = item["electricity"]["summary"]
print(f"Latest period: {summary['latestPeriod']}")
print(f"Avg residential price: {summary['avgResidentialPrice']} cents/kWh")
for s in summary.get("topExpensiveStates", [])[:5]:
print(f" {s['state']}: {s['price']} cents/kWh")
if item.get("marketInsight"):
mi = item["marketInsight"]
print(f"Market: {mi['level']} (score: {mi['score']})")
JavaScript
import { ApifyClient } from "apify-client";
const client = new ApifyClient({ token: "YOUR_API_TOKEN" });
const run = await client.actor("ryanclinton/eia-energy-data").call({
apiKey: "YOUR_EIA_API_KEY",
dryRun: false,
sector: "all",
frequency: "monthly",
dateFrom: "2024-01",
dateTo: "2025-01",
includeElectricity: true,
includeNaturalGas: true,
includePetroleum: true,
maxResults: 500,
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
for (const item of items) {
const { electricity, naturalGas, petroleum, marketInsight } = item;
if (electricity?.summary) {
const { avgResidentialPrice, latestPeriod, topExpensiveStates } = electricity.summary;
console.log(`Period: ${latestPeriod}, Avg residential: ${avgResidentialPrice} cents/kWh`);
topExpensiveStates?.slice(0, 3).forEach(s =>
console.log(` ${s.state}: ${s.price} cents/kWh`)
);
}
if (petroleum?.records?.length) {
const latest = petroleum.records[0];
console.log(`Gasoline (${latest.productDescription}): $${latest.value}/gal`);
}
console.log(`Market insight: ${marketInsight?.level} (${marketInsight?.score})`);
}
cURL
# Start the actor run
curl -X POST "https://api.apify.com/v2/acts/ryanclinton~eia-energy-data/runs?token=YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"apiKey": "YOUR_EIA_API_KEY",
"dryRun": false,
"sector": "all",
"frequency": "monthly",
"dateFrom": "2024-01",
"dateTo": "2025-01",
"includeElectricity": true,
"includeNaturalGas": true,
"includePetroleum": true,
"maxResults": 500
}'
# Fetch results (replace DATASET_ID from the run response above)
curl "https://api.apify.com/v2/datasets/DATASET_ID/items?token=YOUR_API_TOKEN&format=json"
How EIA US Energy Data Search works
Phase 1: Input validation and dataset selection
The actor reads your input and determines which of the four EIA datasets to query based on the sector flag and the four include* boolean toggles. If no API key is present and dryRun is not explicitly set to false, it exits immediately with realistic sample data rather than returning an error. When an API key is provided, the actor validates it on the first request — a 401 or 403 response logs the EIA registration URL and terminates cleanly.
Phase 2: Staggered parallel fetching with pagination
Each dataset fetch is launched as a Promise with a deliberate stagger: electricity starts immediately, natural gas after 1 second, petroleum after 2 seconds, and SEDS state profiles after 3 seconds. This prevents simultaneous rate-limit pressure on the EIA API. All promises run concurrently via Promise.allSettled, so a failure in one dataset does not block the others.
Within each dataset, the fetchData function pages through results in chunks up to 5,000 records per page using the EIA v2 API's length and offset parameters. A 500ms delay is applied between page requests. On HTTP errors, up to 4 retry attempts use exponential backoff: wait time is 2^attempt × 1000ms for general errors and 2^attempt × 2000ms for 429 rate-limit responses.
Petroleum data is additionally capped at 500 records regardless of maxResults, reflecting the practical depth of the EIA weekly retail price series (approximately one year of weekly national and regional readings).
Phase 3: Data transformation and normalization
Raw EIA API responses use inconsistent field naming across datasets — stateid vs stateId, series-id vs seriesId, value-units vs unit. Each dataset has a dedicated transform function (transformElectricity, transformNaturalGas, transformPetroleum, transformStateEnergy) that normalizes these field names into consistent TypeScript interfaces. Numeric values pass through a toNum() guard that handles empty strings, null, and non-numeric API responses, returning null rather than NaN.
Phase 4: Summary computation and market insight scoring
After electricity records are transformed, buildElectricitySummary computes national averages for residential, commercial, and industrial prices using only the most recent reporting period. It ranks all states by residential price, returning the top 10 most and least expensive.
The assessMarket function applies a rule-based scoring model starting at 50, with five threshold adjustments derived from the electricity summary: residential price above 20 cents/kWh deducts 15 points; below 10 cents/kWh adds 10 points; industrial price above 12 cents/kWh deducts 10 points; below 6 cents/kWh adds 8 points. The final score is clamped to 0–100 and mapped to one of four named levels.
Tips for best results
-
Register for your EIA API key before your first real run. The key is free and arrives by email in under a minute from eia.gov/opendata/register.php. Without it, the actor produces sample data only.
-
Use dry-run mode to preview the output structure. Set
dryRun: true(or omit the API key) to see the full output schema with realistic sample values before committing to a paid run. -
Filter by state when you only need regional data. Passing
state: "CA"reduces electricity records from thousands (all 50 states × sectors × periods) to a focused subset, cutting both execution time and cost. -
Match your
frequencyto the data you need. The electricity and natural gas datasets support monthly data; petroleum data is always weekly regardless of yourfrequencysetting. SEDS state profiles are annual only. -
Schedule monthly runs for trend tracking. Use Apify's scheduler to run this actor on the first of each month and store outputs in a persistent dataset. You build a growing time-series without any manual intervention.
-
Combine with Company Deep Research for site selection analysis. Pair state electricity price data from this actor with business environment research on target states to build a comprehensive location-scoring model.
-
Use
maxResults: 100for quick spot checks. For a current-snapshot run — checking today's gasoline prices and latest electricity averages — 100 records per dataset is sufficient and returns in under 20 seconds.
Combine with other Apify actors
| Actor | How to combine |
|---|---|
| Company Deep Research | Add state electricity and energy cost data to location analysis reports for site selection decisions |
| B2B Lead Qualifier | Score energy-intensive business prospects by pairing with their state's industrial electricity rates from this actor |
| Website Content to Markdown | Convert EIA report pages and energy policy documents to markdown for LLM-powered analysis |
| HubSpot Lead Pusher | Push energy market intelligence reports into HubSpot as deal or company property updates |
| Website Change Monitor | Monitor EIA announcement pages for methodology changes or new dataset releases that may affect your data pipeline |
| Trustpilot Review Analyzer | Supplement energy cost analysis with utility company customer sentiment data for a fuller market picture |
Limitations
- EIA API key required for real data. The actor returns sample data without an API key. Free registration takes under one minute, but it is a required manual step.
- EIA data has publication lag. Electricity retail data typically lags 4–6 weeks behind the current month. Natural gas spot prices lag 1–2 weeks. SEDS state profiles are released annually with an 18-month lag. Do not rely on this actor for real-time prices.
- SEDS dataset queries the
TETCBseries only. State profiles are scoped to total energy consumption (MSN codeTETCB). Production, expenditure, and per-capita series available in the full SEDS database are not included in this version. - Petroleum data is capped at 500 records. The actor limits petroleum results to 500 records regardless of
maxResults. This reflects the practical depth of the weekly retail gasoline series. - No coal data is returned. The
coalsector option in the input is valid but currently returns no records — EIA coal endpoint paths differ from the v2 pattern used by this actor. - No regional electricity data. The electricity dataset is filtered at the state level only. Sub-state regional or utility-level data available in the EIA API is not surfaced.
- Date format must match frequency. Passing a YYYY-MM date with
frequency: "annual"returns no results from the EIA API without an error message. Always use YYYY for annual queries. - One report record per run. The actor outputs a single JSON object containing all datasets. It does not output one record per data point. Post-process the arrays in your downstream tool if you need flat row-per-record format.
Integrations
- Zapier — trigger a monthly energy data pull and push market insight scores to a Zapier workflow that alerts your team when the score drops below a threshold
- Make — build a scenario that runs this actor, parses the electricity summary, and updates a Google Sheets dashboard with latest state pricing data
- Google Sheets — export monthly electricity price snapshots to a persistent sheet for year-over-year trend charts
- Apify API — integrate EIA energy data programmatically into energy management dashboards, BI tools, or internal research portals
- Webhooks — receive a POST notification when each run completes, enabling downstream systems to immediately process fresh energy data
- LangChain / LlamaIndex — feed structured energy market reports into LLM pipelines for automated market commentary or briefing generation
Troubleshooting
-
Run completes but all datasets are empty. This almost always means the EIA API key is invalid or expired. Check the run log for a 401 or 403 error message. Re-register at eia.gov/opendata/register.php if needed. New keys can take up to 24 hours to activate after registration.
-
Output shows sample data even though I provided an API key. The actor auto-activates dry-run mode when
dryRunis not explicitly set tofalse. Make sure your input includes"dryRun": falsealongside yourapiKey. Providing the key alone is not sufficient. -
Date range returns no records. Verify your date format matches the frequency: use
YYYY-MMfor monthly data (e.g.2024-01) andYYYYfor annual data (e.g.2023). The EIA API silently returns zero records for mismatched formats rather than returning an error. -
Natural gas or petroleum records are missing. These datasets are fetched with a 1–2 second stagger after the electricity dataset. If the run times out before they complete, they will be absent from the report. Increase the actor memory allocation to 512MB and ensure your timeout setting is at least 120 seconds for full multi-dataset runs.
-
Market insight score seems lower than expected. The score starts at 50 and is adjusted only by residential and industrial electricity price thresholds. If electricity data is absent (e.g. you ran with
sector: "natural-gas"only), the score stays at 50 with no factors listed — this is expected behavior, not a bug.
Responsible use
- This actor accesses only publicly available data published by the US Energy Information Administration under the EIA Open Data API.
- The EIA API terms of service permit commercial use with proper attribution. Review terms at eia.gov/opendata.
- EIA data is produced by a US federal agency and is in the public domain. No copyright restrictions apply to the underlying data.
- Do not use this actor to circumvent EIA API rate limits by running large numbers of parallel instances simultaneously.
- For guidance on web scraping and API usage legality, see Apify's guide.
FAQ
How do I get an EIA API key for this actor? Register for free at https://www.eia.gov/opendata/register.php. Fill in your name, email, and organization. Your key is emailed within minutes. No payment or credit card is required. The key grants unlimited access to the EIA Open Data API v2 at no cost.
How current is the EIA energy data returned by this actor? Currency depends on the dataset. Petroleum retail prices (gasoline, diesel) are updated weekly, typically within 3–5 days of the reference week. Electricity retail data lags 4–6 weeks behind the current month. Natural gas price summaries lag 1–4 weeks. SEDS state energy profiles are released annually, covering data from approximately 18 months prior.
How many records can I retrieve in one EIA energy data run?
Up to 5,000 records per dataset per run. With all four datasets enabled, a single run can return up to 20,000 records total. Petroleum data is capped at 500 records to match the practical depth of the weekly series. Use maxResults to control the per-dataset limit.
Can I filter EIA energy data by state?
Yes. Pass a two-letter state abbreviation in the state field (e.g. TX, CA, NY). The filter applies to all datasets simultaneously — electricity, natural gas, and SEDS profiles are all scoped to the specified state. The petroleum dataset does not support state filtering in the current version and always returns national data.
Can I retrieve historical EIA energy data going back multiple years?
Yes. Set dateFrom and dateTo to cover your desired range and increase maxResults to 5,000. EIA data availability varies by series: electricity retail data goes back to 1990 in the API; Henry Hub natural gas prices go back to 1997; petroleum weekly prices go back to the 1990s. SEDS annual state data typically extends back to 1960.
What is the market insight score and how is it calculated? The market insight score is a 0–100 index computed from electricity price thresholds. It starts at 50, then adds or subtracts points based on: average residential price above 20 cents/kWh (−15), above 15 cents/kWh (−5), below 10 cents/kWh (+10); average industrial price above 12 cents/kWh (−10), below 6 cents/kWh (+8). The score is clamped to 0–100 and mapped to Favorable (65+), Moderate (45–64), Elevated (25–44), or High Cost (<25).
How is this actor different from downloading data directly from the EIA website? The EIA website requires manual navigation across multiple tools, separate downloads for each dataset, and reformatting before analysis. This actor queries all four datasets via the EIA v2 API in a single run and delivers a unified, structured JSON report with pre-computed summary statistics and a market insight score — ready for spreadsheets, databases, or downstream code without any manual steps.
Can I schedule this actor to track EIA energy price trends over time? Yes. Use Apify's built-in scheduler to run on any cron interval. Each run produces a new dataset record. You can accumulate months or years of structured EIA snapshots in a single Apify dataset and export the full history as CSV or JSON at any time.
Is it legal to use the EIA Open Data API through this actor? Yes. The EIA Open Data API is published by the US federal government under an open data policy. The data is in the public domain with no copyright restrictions. The API terms of service permit commercial and research use. See eia.gov/opendata for the full terms.
What happens if the EIA API is unavailable during a run?
The actor retries each failed request up to 4 times with exponential backoff. If all retries fail for a dataset, that dataset is omitted from the report and the others proceed normally via Promise.allSettled. The run completes with whatever data was successfully retrieved rather than failing the entire run.
Does this actor support natural gas spot prices like Henry Hub?
Yes. The natural gas dataset queries the EIA natural-gas/pri/sum endpoint, which includes the Henry Hub Natural Gas Spot Price series (series ID N3010US3) along with wellhead prices, city gate prices, and consumer prices by sector and state.
Can I use EIA energy data with Make or Zapier to automate workflows? Yes. Use Apify's native Make and Zapier integrations to trigger this actor on a schedule and route outputs to any connected app — Google Sheets, Slack, HubSpot, Airtable, or custom webhooks. The structured JSON output maps cleanly to spreadsheet rows or CRM fields with no custom parsing required.
Help us improve
If you encounter issues, you can help us debug faster by enabling run sharing in your Apify account:
- Go to Account Settings > Privacy
- Enable Share runs with public Actor creators
This lets us see your run details when something goes wrong, so we can fix issues faster. Your data is only visible to the actor developer, not publicly.
Support
Found a bug or have a feature request? Open an issue in the Issues tab on this actor's page. For custom solutions or enterprise integrations, reach out through the Apify platform.
How it works
Configure
Set your parameters in the Apify Console or pass them via API.
Run
Click Start, trigger via API, webhook, or set up a schedule.
Get results
Download as JSON, CSV, or Excel. Integrate with 1,000+ apps.
Use cases
Sales Teams
Build targeted lead lists with verified contact data.
Marketing
Research competitors and identify outreach opportunities.
Data Teams
Automate data collection pipelines with scheduled runs.
Developers
Integrate via REST API or use as an MCP tool in AI workflows.
Related actors
GitHub Repository Search
Search GitHub repositories by keyword, language, topic, stars, forks. Sort by stars, forks, or recently updated. Returns metadata, topics, license, owner info, URLs. Free API, optional token for higher limits.
Website Content to Markdown
Convert any website to clean Markdown for RAG pipelines, LLM training, and AI apps. Crawls pages, strips boilerplate, preserves headings, tables, and code blocks. GFM support.
Weather Forecast Search
Get weather forecasts for any location worldwide using the free Open-Meteo API. Returns current conditions, daily and hourly forecasts with temperature, precipitation, wind, UV index, and more. No API key needed.
EUIPO EU Trademark Search
Search EU trademarks via official EUIPO database. Find registered and pending trademarks by name, Nice class, applicant, or status. Returns full trademark details and filing history.
Ready to try EIA US Energy Data Search?
Start for free on Apify. No credit card required.
Open on Apify Store