Retail Rate Database
Changed onThis endpoint returns the tariffs (structures) and rates (costs) to purchase electricity from electrical utilities in the United States. The bulk of our retail rates are for residential customers (though there may be some overlap with small commercial or other electricity users). We include all types of utilities, including investor owned utilities, municipal utilities, and coops. Our data includes component charges, the source of the data, and the recency.
We include time-varying rates, also known as “time of use” rates, and provide the structure of peak versus non-peak
Our Retail Rate Database contains electricity rates for 95% of US customers (over 1700 utility companies).
Our database uses a human-augmented machine learning approach to pull the latest rates whenever they become available and we are continually feeding in new rates as well as updating existing rates.
Users can employ this data to estimate the cost of electricity based on a set usage. It can also be used to determine based on changes in electricity usage, for instance from energy efficiency upgrades. This data can be combined with the electricity usage estimate (link) to estimate the cost of electricity for nearly any home in the US.
Canadian rates are also available. Pass the Canadian utility's numeric id (124000001+) with its province code — ?utilityID=124000005&state=bc. Canadian records carry country: "ca" and currency: "CAD"; US records default to country: "us" and currency: "USD". Price-to-compare is a US deregulated-market concept and is not returned for Canadian provinces.
Request
- Base URLhttps://apis.wattbuy.com/v3
- AuthAPI key in header x-api-key
Query parameters
Required, and always numeric. US utilities use the EIA utility id (listing: https://www.eia.gov/electricity/data/eia861/). Non-US utilities use a WattBuy-reserved numeric block that cannot collide with an EIA id — Canada is 124000001+ (e.g. BC Hydro is 124000005).
A non-numeric value returns 400. Canadian utilities were previously identified by a short string such as bchydro; those identifiers are no longer accepted.
Required. Two-character US state code (e.g. "fl") or Canadian province/territory code (e.g. "bc", "qc").
Optional, baseline allocation zone if applicable. This is assigned to most customers in CA based on where they live, and can be found on the bill.
Optional, Epoch time, default 2 years ago, example: 1664514205
Non negative page number, default 1
Response
OK
Changes
- breaking
queryrequest parameterutilityIDlist-of-types was narrowed by removing typesstring - breaking
for the
queryrequest parameterutilityID, the type changed from no type tointeger - info
added the non-success response with the status
1 more change in this revision
- breaking