Web Services

Documentation » Get Utility Rates

https://api.openei.org/utility_rates?params

Access complex utility rate structure information (across all sectors) for most U.S. utility companies from the U.S. Utility Rate Database. This information is collected and quality controlled on a continual basis by Illinois State University on behalf of DOE and housed within the OpenEI.org platform. To browse available data, see the OpenEI U.S. Utility Rate Database page.

Request URL

GET https://api.openei.org/utility_rates?parameters

Request Parameters

Parameter Required Value Description
version Yes
Options: latest, 3, 4 or 5
Versions 4 and 5 include international rates. Note that the label values for U.S. rates in the IURDB do not match labels in the USURDB.
format Yes
Options: json, csv, or json_plain

The format parameter will be disregarded if the debug parameter is set

api_key Yes
Type: String

Register for a key here, it's free!

limit No
Type: Integer
Maximum record count 500.
getpage No
Type: String
Get a specific page name, i.e. getpage=535aeca39bef511109580ee1. This is referred to as "label" in the results.
ratesforutility No
Type: String
Get rates for a specific utility page name, i.e. ratesforutility=Detroit Edison Co. This value can be re-used from the "label" value in the utility_companies results.
offset No
Type: Integer
Default: 0
The offset from which to start retrieving records.
orderby No
Type: Field Name
Default: label
Field to use to sort results.
direction No
Type: String
Default: asc
Options: asc, or desc
Direction to order results, ascending or descending.
sector No
Options: Residential, Commercial, Industrial, or Lighting

Shows only those rates matching the given sector.

approved No
Options: true or false

Shows only those rates whose approval status matches the given value.

country No
Type: String

ISO 3 character country code, i.e. country=USA.

address No
Type: String

Address for rate, see Google Geocoding API for details. Address or lat/lon may be used, but not both.

lat No
Type: Integer

Latitude for rate. If set, lon must also be set and address must not.

lon No
Type: Integer

Longitude for rate. If set, lat must also be set and address must not.

eia No
Type: Integer

EIA Id to look up.

callback No
Type: String
callback=<mycallback> - set mycallback as the json callback.
detail No
Type: String
Default: minimal
Options: full or minimal"
  • detail=full - returns every variable. Since this results in a lot of data that can time-out returning to your server, use a limit=500 and set an offset (e.g. 501) if you want more data.
  • Compare to detail=minimal, which is the default.

Response Fields

Field Value Description
label
Type: string

Page label.

utility
Type: string

Utility company name.

name
Type: string

Rate name.

uri
Type: URI

Full page URI.

approved
Type: boolean

Expert has verified

startdate
Type: integer

Effective Date timestamp

enddate
Type: integer

End Date timestamp

supercedes
Type: string

Label of the rate this rate supercedes.

sector
Type: enumeration

Sector, one of "Residential", "Commercial", "Industrial", or "Lighting"

servicetype
Type: enumeration

Service type, one of "Bundled", "Energy", "Delivery", or "Delivery with Standard Offer"

description
Type: string

Description

source
Type: string

Source or reference.

sourceparent
Type: URI

Source Parent

basicinformationcomments
Type: string

Basic Comments

peakkwcapacitymin
Type: decimal

Demand Minimum (kW)

peakkwcapacitymax
Type: decimal

Demand Maximum (kW)

demandunits
Type: enumeration

Demand applicability units, one of "kW", "hp", "kVA", "kW daily", "hp daily","kVA daily"

peakkwcapacityhistory
Type: decimal

Demand History (months)

peakkwhusagemin
Type: decimal

Energy Minimum (kW)

peakkwhusagemax
Type: decimal

Energy Maximum (kW)

peakkwhusagehistory
Type: decimal

Energy History (months)

voltageminimum
Type: decimal

Service Voltage Minimum

voltagemaximum
Type: decimal

Service Voltage Maximum

voltagecategory
Type: enumeration

Voltage category, one of "Primary", "Secondary", or "Transmission"

phasewiring
Type: enumeration

Phase wiring, one of "Single Phase","3-Phase", or "Single and 3-Phase"

flatdemandunit
Type: enumeration

Seasonal/Monthly Rate Units, one of "kW", "hp", "kVA", "kW daily", "hp daily","kVA daily"

flatdemandstructure
Type: array

Seasonal/Monthly Demand Charge Structure. Each element in the top-level array corresponds to one period (see flatdemandmonths) and each array element within a period corresponds to one tier. Indices are zero-based and correspond with flatdemandmonths entries: [[{"max":(Decimal),"rate":(Decimal),"adj":(Decimal)},...],...]

Note that in the downloadable csv the flatdemandstructure is flattened into the following format for backward compatibility, where period_number and tier_number are zero-indexed:

  • flatdemandstructure/period<period_number>/tier<tier_number>max
  • flatdemandstructure/period<period_number>/tier<tier_number>rate
  • flatdemandstructure/period<period_number>/tier<tier_number>adj

flatdemandmonths
Type: array

Seasonal/Monthly Demand Charge Structure. Array of 12 integers, one per month, where each corresponds to the index of a period in flatdemandstructure.

Note that in the downloadable csv each month has its own column header of the form flatdemandmonth<month_number> with month_numbers 1-12.

demandrateunit
Type: enumeration

Time of Use Rate Units, one of "kW", "hp", "kVA", "kW daily", "hp daily", "kVA daily"

demandratestructure
Type: array

Time of Use Demand Charge Structure. Each element in the top-level array corresponds to one period (see demandweekdayschedule and demandweekendschedule) and each array element within a period corresponds to one tier. Indices are zero-based and correspond with demandweekdayschedule and/or demandweekendschedule entries: [[{"max":(Decimal),"rate":(Decimal),"adj":(Decimal),"sell":(Decimal)},...],...]

Note that in the downloadable csv the demandratestructure is flattened into the following format for backward compatibility, where period_number and tier_number are zero-indexed:

  • demandratestructure/period<period_number>/tier<tier_number>max
  • demandratestructure/period<period_number>/tier<tier_number>rate
  • demandratestructure/period<period_number>/tier<tier_number>adj

demandweekdayschedule
Type: array

Time of Use Demand Charge Structure Weekday Schedule. Value is an array of arrays. The 12 top-level arrays correspond to a month of the year. Each month array contains one integer per hour of the weekday from 12am to 11pm, and the integer corresponds to the index of a period in demandratestructure.

demandweekendschedule
Type: array

Time of Use Demand Charge Structure Weekend Schedule. Value is an array of arrays. The 12 top-level arrays correspond to a month of the year. Each month array contains one integer per hour of the weekday from 12am to 11pm, and the integer corresponds to the index of a period in demandratestructure.

demandratchetpercentage
Type: array

Array of 12 decimal numbers, one Demand Ratchet Percentage per month.

demandwindow
Type: decimal

Demand Window (minutes)

demandreactivepowercharge
Type: decimal

Demand Reactive Power Charge ($/kVAR)

coincidentrateunit
Type: enumeration

Coincident Rate Units, one of "kW", "hp", "kVA", "kW daily", "hp daily","kVA daily"

coincidentratestructure
Type: array

Coincident Rate Structure. Each element in the top-level array corresponds to one period (see coincidentschedule) and each array element within a period corresponds to one tier. Indices are zero-based to correspond with coincidentschedule entries: [[{"max":(Decimal),"rate":(Decimal),"adj":(Decimal),"sell":(Decimal)},...],...]

Note that in the downloadable csv the coincidentratestructure is flattened into the following format for backward compatibility, where period_number and tier_number are zero-indexed:

  • coincidentratestructure/period<period_number>/tier<tier_number>max
  • coincidentratestructure/period<period_number>/tier<tier_number>rate
  • coincidentratestructure/period<period_number>/tier<tier_number>adj

coincidentrateschedule
Type: array

Coincident Rate Structure Schedule. Value is an array of arrays. The 12 top-level arrays correspond to a month of the year. Each month array contains one integer per hour of the day from 12am to 11pm, and the integer corresponds to the index of a period in coincidentratestructure.

demandattrs
Type: array

Other Demand Attributes in a key/value format.

demandcomments
Type: string

Demand Comments

dgrules
Type: enumeration

Compensation for distributed generation, one of "Net Metering", "Net Billing Instantaneous", "Net Billing Hourly", or "Buy All Sell All"

energyratestructure
Type: array

Tiered Energy Usage Charge Structure. Each element in the top-level array corresponds to one period (see energyweekdayschedule and energyweekendschedule) and each array element within a period corresponds to one tier. Indices are zero-based to correspond with energyweekdayschedule and energyweekendschedule entries: [[{"max":(Decimal),"unit":(Enumeration),"rate":(Decimal),"adj":(Decimal),"sell":(Decimal)},...],...]

Note that in the downloadable csv the energyratestructure is flattened into the following format for backward compatibility, where period_number and tier_number are zero-indexed:

  • energyratestructure/period<period_number>/tier<tier_number>max
  • energyratestructure/period<period_number>/tier<tier_number>rate
  • energyratestructure/period<period_number>/tier<tier_number>adj
  • energyratestructure/period<period_number>/tier<tier_number>sell

energyweekdayschedule
Type: array

Tiered Energy Usage Charge Structure Weekday Schedule. Value is an array of arrays. The 12 top-level arrays correspond to a month of the year. Each month array contains one integer per hour of the weekday from 12am to 11pm, and the integer corresponds to the index of a period in energyratestructure.

energyweekendschedule
Type: array

Tiered Energy Usage Charge Structure Weekend Schedule. Value is an array of arrays. The 12 top-level arrays correspond to a month of the year. Each month array contains one integer per hour of the weekend from 12am to 11pm, and the integer corresponds to the index of a period in energyratestructure.

fueladjustmentsmonthly
Type: array

Array of 12 decimal numbers, one per month, each is $/kWh.

energyattrs
Type: array

Other Energy Attributes in a key/value format.

energycomments
Type: string

Energy Comments

fixedchargefirstmeter
Type: decimal

Fixed charge for first meter. See fixedchargeunits for units.

fixedchargeeaaddl
Type: decimal

Fixed charge for each additional meter. See fixedchargeunits for units.

fixedchargeunits
Type: enumeration

Units for fixedchargefirstmeter and fixedchargeeaaddl, one of "$/day", "$/month" or "$/year".

mincharge
Type: decimal

Minimum charge. See minchargeunits for units.

minchargeunits
Type: enumeration

Units for mincharge, one of "$/day", "$/month" or "$/year".

fixedattrs
Type: array

Other Fixed Charge Attributes in a key/value format.

Examples

JSON Output Format

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
{"items": [
          {"label": "5374efea9bef51471a6965d0",
           "uri":"https://openei.org/apps/USURDB/rate/view/5374efea9bef51471a6965d0",
           "type":"Utility_Rates"},
          {"label": "5374efea9bef51471a6965d2",
             "uri":"https://openei.org/apps/USURDB/rate/view/5374efea9bef51471a6965d2",
             "type":"Utility_Rates"},
          {"label": "5374efea9bef51471a6965d4",
           "uri":"https://openei.org/apps/USURDB/rate/view/5374efea9bef51471a6965d4",
           "type":"Utility_Rates"}]
}

CSV Output Format

  1
  2
  3
  4
PageName
5374efea9bef51471a6965d0
5374efea9bef51471a6965d2
5374efea9bef51471a6965d4

Errors

Returns a description of the error