---
title: "Retail Rate Database"
method: GET
path: "/electricity/retail-rates"
tags: ["Electricity"]
---

# Retail Rate Database

`GET /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.

## Query parameters

- `utilityID` union, required
  - integer
  - string
- `state` string, required
- `baseline_zone` string
- `verified_from` integer
- `page` number

## Response `200`

OK

- object
  - `count` number — Number of rates available for given query
  - `next` boolean — Whether there is at least one more page of data available
  - `data` object[] — One page of available rates for this query
    - `_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` object[] — 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)
      - `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` object[] — Information about the times, days, and seasons this particular rate object is available
        - `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` number[] — 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
      - `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` object[] — Array for calculating cost during the time defined by availability above. Each item in the array represents a tier of usage.
        - `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, in cents per unit. For deregulated utilities, this value represents the combined delivery + generation price (i.e. the full cost per kWh).
        - `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` string[] — A list of source URLs where adjustment data can be found
    - `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
      - `rate` string — URL where the actual rate document can be found
      - `rate_parent` string — URL where general rate information for this utility 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
      - `amount` number — The minimum bill amount, in cents
      - `frequency` string — How often the minimum bill is charged, when necessary
    - `customer_charge` object — The charge that a customer must pay, in addition to their usage costs, per defined frequency
      - `frequency` string — How often the customer charge is billed
      - `amount` number — The customer charge amount, in cents
    - `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.

## Other responses

- `204` — No Content for given utilityID
- `500` — Internal server error

---

[API](https://skmtc.net/wattbuy/apis/wattbuy-apis.md) · [All operations](https://skmtc.net/wattbuy/apis/wattbuy-apis/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/wattbuy/wattbuy-apis/revisions/97771153b652/schema)