Retail Rate Database

get https://apis.wattbuy.com/v3/electricity/retail-rates

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.

Responses

Response body

object

count

number

Number of rates available for given query

boolean

Whether there is at least one more page of data available

data

array of objects

One page of available rates for this query

data

object

_id

string

The internal ID for this particular rate update. Note that this ID will change with every rate change, even if it is marketed as the same rate by the utility. For an ID that attempts to link rates with the same name, use the "rate_id"

utility_id

number

The EID of the utility where this rate is available

rate_name

string

The marketed name for this rate

rate_structure

array of objects

The structure and pricing details for the rate. A rate structure could have multiple objects that represent different combinations of seasons, days of the week, and hours of the day. Taken together, you can expect for each hour of the year to be represented by exactly one of these objects (i.e. there will be no gaps or overlaps)

rate_structure

object

name

string

The name of this particular rate object (eg "summer peak", "weekends", "full rate")

frequency

string

The granularity with which this price object is aggregated. This typically represents how often the user is billed and is usually monthly

availability

array of objects

Information about the times, days, and seasons this particular rate object is available

availability

object

start_date

number

The day of the start_month this object begins taking effect

start_month

number

The month of the year this object begins taking effect

start_time

number

The start of the time of day that this object represents, denoted as number of minutes past midnight.

start_time_string

string

The start of the time of day that this object represents, formatted as "HH:mm"

end_date

number

The day of the end_month this object begins taking effect

end_month

number

The month of the year this object begins taking effect

end_time

number

The end of the time of day that this object represents, denoted as number of minutes past midnight.

end_time_string

string

The end of the time of day that this object represents, formatted as "HH:mm"

days_of_week

array of numbers

An array of 7 numbers, where each item represents a day of the week starting with Sunday. 1s represent days where this object is applicable, 0s represent days where this object is not applicable

days_of_week

unit

string

Unit of electricity that applies to the following fields in price object. Typically kwh for classic usage-based rates, less commonly kw for demand-based charges.

price

array of objects

Array for calculating cost during the time defined by availability above. Each item in the array represents a tier of usage.

price

object

minimum_usage

number

The usage amount (in units defined above) where this price item begins to take effect.

maximum_usage

number

The usage amount (in units defined above) where the following price item begins to take effect. Note that if there is no upper limit, this will be null.

amount

number

The actual base cost for usage in this usage tier. This is represented as cents per unit, where unit is defined above.

adjustment

number

The total additional adjustment amounts that are applied on top of the amount above, in cents per unit. For most use cases, this number should be added to "amount" for a full look at the user's bill.

adjustment_types

string

An unstructured string that represents the types of adjustments that are represented above. This field exists where available but should not be relied on at all times.

adjustment_urls

array of strings

A list of source URLs where adjustment data can be found

adjustment_urls

utility_name

string

Name of utility that offers this rate

state

string

U.S. state where this rate is available

source

object

URLs where rate information can be found

structure

string

Enum for the type of rate this is. Possible values are "fixed" or "TOU"

minimum_bill

object

The minimum amount that a customer must pay regardless of usage, per defined frequency

customer_charge

object

The charge that a customer must pay, in addition to their usage costs, per defined frequency

is_default

boolean

Whether or not this is the standard rate that a customer is signed up for when starting service with the utility

effective_start_date

string

The earliest date that we are aware of this rate being available. Note that this rate is sometimes defined in rate docuemnts, but is otherwise set to the first date that WattBuy imported the rate.

retrieved_at

string

The date that WattBuy imported the rate for verification

verified_at

string

The date that WattBuy verified the rate. This is the same date the rate became available via API.

effective_end_date

string

The date on which this rate will no longer be available. If this is not known, this field will be null

tariff_code

string

The short tariff code provided by the utility (e.g. "E-1")

zone

string

The zone within a utility where this rate is available. If not applicable, this will be an empty string.

204

No Content for given utilityID

500

Internal server error

200OK