Microproduct data guideintermediate

EIA Weekly Petroleum Status

Weekly U.S. petroleum stocks and related series for building fuel-inventory monitors and energy-market dashboards.

Start the guide Open official source

At a glance

Difficulty
Intermediate — some data preparation helps
Size
Medium · ≤1 GB
Formats
JSON, CSV
Access
API or Download
API key
Required
Provider
U.S. Energy Information Administration
Updates
Weekly
Data terms
U.S. Public Domain with EIA source acknowledgment

From source to product signal

Test a product idea in four steps

EIA's petroleum weekly stocks route returns inventory series used in the Weekly Petroleum Status Report. Start with U.S. crude stocks and a short length. These are inventory statistics, not retail pump prices, unless you choose a price route.

1

Check the setup

  • Python 3.10 or newer
  • A notebook environment such as Jupyter or Google Colab
  • A free EIA API key saved in the EIA_API_KEY environment variable
2

Access the data

  1. 1.Register for a free key on the EIA Open Data site, or reuse an existing EIA_API_KEY.
  2. 2.Confirm the petroleum weekly stocks route and available facets.
  3. 3.Request a bounded weekly sample for U.S. crude oil stocks.
Open official source
3

Run the Python example

Install the packages, then run the notebook cell.

python -m pip install pandas requests

import os
import pandas as pd
import requests

response = requests.get(
    "https://api.eia.gov/v2/petroleum/stoc/wstk/data/",
    params={
        "api_key": os.environ["EIA_API_KEY"],
        "frequency": "weekly",
        "data[0]": "value",
        "facets[duoarea][]": "NUS",
        "facets[product][]": "EPC0",
        "length": 20,
    },
    timeout=30,
)
response.raise_for_status()
stocks = pd.DataFrame(response.json()["response"]["data"])
stocks["period"] = pd.to_datetime(stocks["period"])
stocks["value"] = pd.to_numeric(stocks["value"], errors="coerce")
stocks["retrieved_at_utc"] = pd.Timestamp.now(tz="UTC")
print(stocks[["period", "duoarea", "product-name", "value", "units"]].head())
4

Test a useful signal

Track U.S. crude oil weekly stocks

Test whether a short crude-stocks window can power an inventory-change alert.

  1. 01Sort by period and compute week-to-week stock changes.
  2. 02Flag the largest builds and draws in the extract.
  3. 03Explain that weekly stocks are not retail gasoline prices and that series can be revised after publication.

Dataset details

U.S. Energy Information Administration is a government source. Last verified 2026-08-17. Temporal coverage: weekly petroleum series with history varying by product.

Theme

Markets & Economics

Domains

EnergyCommoditiesMacroeconomics

Data types

Time SeriesTabular

Tasks

Market MonitoringTrend AnalysisForecast Evaluation

Geography

United States

Formats

JSONCSV

Provider

U.S. Energy Information Administration

Data terms

U.S. Public Domain with EIA source acknowledgment