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
- Usage:
estimationif sent. Otherwise usage is estimated fromaddress/zipexactly as/electricity/estimationdoes. - Rate:
rate_idif 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. - Zone (baseline-zoned rates only, e.g. PG&E, SCE, SDG&E):
baseline_zoneif sent. Otherwise the zone is resolved from the location. - Location is used for usage estimation, the default rate, the zone and the hourly usage profile. When both
rate_idand a location are sent, the location is not checked against the rate's utility.
| Sent | Usage from | Rate from |
|---|---|---|
| zip/address | estimated | default for location |
| zip/address + estimation | estimation | default for location |
| zip/address + rate_id | estimated | rate_id |
| estimation + rate_id | estimation | rate_id (a rate that needs an hourly profile or a zone returns 422 unless baseline_zone covers the zone) |
| zip/address + estimation + rate_id | estimation | rate_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=truecurrently adds nothing and returnstax_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).
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
