EIA API v2: check pagination, filters and units before exporting
A reproducible checklist for EIA energy-data downloads, including metadata routes, pagination and unit-aware exports.
Inspect metadata before rows
EIA API v2 exposes a hierarchy of routes and metadata describing available data, facets and frequencies. Choose a specific dataset and read its metadata before constructing the data request. EIA documents a 5,000-row JSON response limit; a successful response can therefore be only part of a download.
Make the export bounded
Write down the route, selected fields, facet filters, frequency, start and end period, ordering, length and offset. Use documented pagination to traverse the requested result. Keep the same filters while paging. If the provider updates data during the export, retain retrieval times and check duplicate/missing keys rather than assuming a consistent snapshot.
Validate the result
Compare the reported total with rows retained and unique dimension–period keys. Keep any warning or error in the export receipt. A synthetic 6,200-row result with batches of 5,000 and 1,200 reconciles; a lone 5,000-row file is incomplete. These counts are illustrative, not a live EIA download.
Do not drop unit columns
Carry the unit and all identifying dimensions into CSV or a database. A number without its measure, geography, period and unit cannot support a comparison. Do not add a rate to an amount or sum overlapping categories. State any conversion formula and retain the original value alongside it.
Keys and reproducibility
The documented API uses a registered key. Keep it outside public notebooks and posted URLs; redact it from any request example you share. A useful correction names the route, public parameters, expected count and observed count without credentials. Use the official documentation for key registration and current usage requirements.
Official sources
Improve this guide
Found an error or used a different dataset? Include the source, edition/date, what needs changing and why. Do not include credentials or personal records.
Propose a correction · Read open corrections · Open wiki topic