EIA API v2: how to use it, its limits, and the OilPriceAPI mirror

Calling the EIA API v2 directly

Register for a key at eia.gov/opendata. Every request is a GET against https://api.eia.gov/v2/<route>/data/ with the key in the URL. The examples use the same routes and series IDs this site already reads for its supply-constraints dashboard.

# U.S. commercial crude stocks (WCESTUS1) and SPR (WCSSTUS1), weekly, newest first
curl "https://api.eia.gov/v2/petroleum/stoc/wstk/data/?api_key=YOUR_EIA_KEY\
&frequency=weekly&data[0]=value\
&facets[series][]=WCESTUS1&facets[series][]=WCSSTUS1\
&start=2025-01-01&sort[0][column]=period&sort[0][direction]=desc\
&offset=0&length=5000"

# Weekly natural gas storage route
curl "https://api.eia.gov/v2/natural-gas/stor/wkly/data/?api_key=YOUR_EIA_KEY\
&frequency=weekly&data[0]=value&sort[0][column]=period&sort[0][direction]=desc&length=5"

# Walk the tree: each node lists its child routes, facets and frequencies
curl "https://api.eia.gov/v2/petroleum?api_key=YOUR_EIA_KEY"
curl "https://api.eia.gov/v2/petroleum/stoc/wstk/facet/series?api_key=YOUR_EIA_KEY"

{
  "response": {
    "total": "…",
    "data": [
      { "period": "2026-09-05", "series": "WCESTUS1", "value": "…", "units": "MBBL" }
    ]
  },
  "request": { "command": "/v2/petroleum/stoc/wstk/data/", "params": { … } }
}

• Parameters. frequency, data[0]=value, facets[…][], start, end, sort[0][column], sort[0][direction], offset and length. Parameters other than api_key may also be sent in an X-Params HTTP header when URLs get too long.
• Output. JSON by default; add out=xml for XML. Row values arrive as strings.
• Row cap. 5,000 rows per JSON response. Above that you get a truncated result and a "parameter out of range" warning.
• Throttling. Exact rules are not published. EIA's guidance: under ~9,000 requests per hour sustained and under 5 per second burst. Exceeding it disables the key for seconds to minutes.

Source: EIA API technical documentation and EIA API FAQs, read 2026-09-15. EIA's data is public domain at the source; OilPriceAPI claims no rights in it.

The OilPriceAPI mirror

The headline EIA series under plain codes, one key, and the same JSON shape as WTI, Brent and gold. Cadence follows EIA's release calendar; every response carries the source period as its timestamp and a freshness verdict.

curl "https://api.oilpriceapi.com/v1/prices/latest?by_code=NATURAL_GAS_STORAGE,CUSHING_STORAGE,WTI_SPOT_USD,BRENT_SPOT_USD,GASOLINE_RETAIL_USD,DIESEL_RETAIL_USD" \
  -H "Authorization: Token YOUR_API_KEY"

# Not in the batched response today (api#8176) — fetched one code at a time:

curl "https://api.oilpriceapi.com/v1/prices/latest?by_code=NATURAL_GAS_STORAGE" \
  -H "Authorization: Token YOUR_API_KEY"

curl "https://api.oilpriceapi.com/v1/prices/latest?by_code=CUSHING_STORAGE" \
  -H "Authorization: Token YOUR_API_KEY"