Electricity

Retail Rate Database

Changed on

This 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.

get/electricity/retail-rates

Request

  • Base URL
    https://apis.wattbuy.com/v3
  • Auth
    API key in header x-api-key

Query parameters

utilityIDinteger required

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.

statestring required

Required. Two-character US state code (e.g. "fl") or Canadian province/territory code (e.g. "bc", "qc").

baseline_zonestring

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.

verified_frominteger

Optional, Epoch time, default 2 years ago, example: 1664514205

pagenumber

Non negative page number, default 1

Response

OK

countnumber

Number of rates available for given query

nextboolean

Whether there is at least one more page of data available

Changes

    • breaking

      query request parameter utilityID list-of-types was narrowed by removing types string

    • breaking

      for the query request parameter utilityID, the type changed from no type to integer

    • info

      added the non-success response with the status

    1 more change in this revision