Electricity Bill Estimate From The Utility Rate

A 12-month electricity bill estimate priced on the utility's real distributor rate from our Retail Rate Database, not on a state average. Send an address or a zip (or 12 months of usage with a rate_id), and the response names the utility, rate and zone that were priced.

Precedence

  1. Usage: estimation if sent. Otherwise usage is estimated from address/zip exactly as /electricity/estimation does.
  2. Rate: rate_id if sent. Otherwise the default rate of the largest utility serving the location: its most recently verified, active default rate. When a utility has both a standard and an "All Electric" default, the standard one is used unless the estimated home heats with electricity.
  3. Zone (baseline-zoned rates only, e.g. PG&E, SCE, SDG&E): baseline_zone if sent. Otherwise the zone is resolved from the location.
  4. Location is used for usage estimation, the default rate, the zone and the hourly usage profile. When both rate_id and a location are sent, the location is not checked against the rate's utility.
SentUsage fromRate from
zip/addressestimateddefault for location
zip/address + estimationestimationdefault for location
zip/address + rate_idestimatedrate_id
estimation + rate_idestimationrate_id (a rate that needs an hourly profile or a zone returns 422 unless baseline_zone covers the zone)
zip/address + estimation + rate_idestimationrate_id

Supported rate shapes: fixed and tiered rates, time-of-use (TOU) windows, baseline zones, kW/kVA demand charges, daily and hourly blocks, and seasons that start or end mid-month. TOU, demand and partial-week rates are priced by spreading each month's usage over the hours using the nearest OpenEI hourly load profile. Utility holidays are priced with the rate's weekend windows.

Approximations

  • The demand charge uses the month's peak hourly average kW from the profile; a 15-minute metered peak would be higher.
  • kVA is priced as kW (power factor 1).
  • Rate windows are local clock time and the hourly profile is standard time; the daylight-saving hour is ignored.

Tax: whole-bill percentage taxes recorded on the rate (comprehensive taxes) are always part of the bill. include_tax=true adds the state residential electricity tax on top.

State tax is a work in progress: the state tax table is not populated yet, so include_tax=true currently adds nothing and returns tax_included: false.

Expired rates are still priced; is_active and expired in the response flag them.

There is no state-average fallback: when no rate can be priced the response is 404 or 422. Canadian rates (rate_id of a rate with country: "ca") require estimation; amounts are in the rate's currency (CAD).

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Query Params
string

Street address of the home. One of address or zip is required unless rate_id and estimation are both sent.

string

City, passed through to the address lookup.

string

Two-letter state code, passed through to the address lookup.

string

5-digit zip code. A zip alone is enough.

string

Optional. 12 monthly kWh values, Jan to Dec, comma-separated. Each ≥ 0 and the total must be above 0. When sent, usage is not estimated.

string

Optional. The _id of a rate from /electricity/retail-rates (24 hex characters). Inactive and unverified rates are priced as well.

string

Optional. Overrides the zone resolved from the location for baseline-zoned rates. Same values as baseline_zone on /electricity/retail-rates (e.g. P, 10, Coastal).

boolean
Defaults to false

Optional. Adds the state residential electricity tax on top of the bill. The rate's own comprehensive taxes are always included. The state tax table is not populated yet, see above.

Responses

Language
Credentials
Header
URL
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json