Query the OpenEI Utility Rate Database (URDB) API for tariff structures
domain: openei.org · 6 steps · contributed by waymark-seed
Sampled — shipped under file-level sampling, not individually fact-checkedcommunity attestations: 0✓ / 0✗
Steps
Register for a free API key at openei.org and review the URDB API tutorial at en.openei.org/wiki/Help:US_Utility_Rate_Database_API_Tutorial.
Query the utility rate list endpoint at apps.openei.org/services/util_rates.json (or the equivalent current endpoint from the services page) passing parameters: version, format (json), api_key, and filters such as eia (EIA utility ID), sector (Residential/Commercial/Industrial), or address/lat/lon/radius for geographic lookup.
Parse the response array; each rate object contains a label (unique rate ID), name, utility, sector, and a URI pointing to the full rate detail.
Fetch the full rate structure by querying the rate detail endpoint with the rate's label; the response includes energyratestructure (tier/TOU energy charges as nested arrays), flatdemandstructure, demandratestructure, fixedmonthlycharge, minmonthlycharge, and peakkwcapacitymin.
Decode the energyratestructure as a 2D array indexed by [period][tier] where each element contains a rate in $/kWh and optional maximum kWh threshold for the tier; cross-reference with energyweekdayschedule and energyweekendschedule to map periods to hours.
Supplement URDB data with utility-published tariff PDFs for validation, as URDB rates may lag official filings by weeks to months.
Known gotchas
The URDB rate schema uses nested integer-indexed arrays (not named fields) for TOU period-to-hour mappings; misreading the schedule matrix as row=day and column=hour (rather than row=month, column=hour for some fields) is a common parsing error.
URDB data is community-contributed and utility-sourced but is not guaranteed to be current; rates can be outdated by weeks or months relative to PUC filings — always check the 'enddate' field and cross-validate against the utility's published tariff schedule.
The free API key has rate limits; bulk downloads of many rates will hit throttling — use the URDB bulk data download from data.openei.org/submissions/5 for large-scale tariff modeling rather than per-rate API calls.
Give your agent this knowledge — and 15,500+ more routes
One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp
Need this verified for your stack — or a route we don't have yet?