Electricity Bill Estimate From The Utility Rate (JSON body)

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…
Body Params

Same fields as the GET query; a body field wins over the same query field. estimation is a JSON array.

string
string
string
string
estimation
array of numbers
length between 12 and 12
estimation
string
string
boolean
Defaults to false
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