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-7
OpenEI retired the version 1 API on January 2nd, 2014. Version 2 was released on May 4th, 2013, and version 3 was released on June 16th, 2014, at which point version 2 database updates ceased, with all updates now appearing only in version 3 or greater. Please contact the if you have any questions or concerns.
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.
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"
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)
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
usenetmetering
Type: boolean

Assume net metering (buy = sell)
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.
energyattrs
Type: array

Other Energy Attributes in a key/value format.
energycomments
Type: string

Energy Comments
fixedmonthlycharge
Type: decimal

Fixed monthly charge ($)
minmonthlycharge
Type: decimal

Minimum monthly charge ($)
annualmincharge
Type: decimal

Annual minimum charge ($)
fixedattrs
Type: array

Other Fixed Charge Attributes in a key/value format.

Examples

JSON Output Format

GET https://api.openei.org/utility_rates?version=3&format=json&limit=3&api_key=EXAMPLE_API_KEY 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
 
{"items": [
          {"label": "5374efea9bef51471a6965d0",
           "uri":"https://apps.openei.org/USURDB/rate/view/5374efea9bef51471a6965d0",
           "type":"Utility_Rates"},
          {"label": "5374efea9bef51471a6965d2",
             "uri":"https://apps.openei.org/USURDB/rate/view/5374efea9bef51471a6965d2",
             "type":"Utility_Rates"},
          {"label": "5374efea9bef51471a6965d4",
           "uri":"https://apps.openei.org/USURDB/rate/view/5374efea9bef51471a6965d4",
           "type":"Utility_Rates"}]
}

CSV Output Format

GET https://api.openei.org/utility_rates?version=3&format=csv&limit=3&api_key=EXAMPLE_API_KEY 
  1
  2
  3
  4

PageName
5374efea9bef51471a6965d0
5374efea9bef51471a6965d2
5374efea9bef51471a6965d4

Errors

Returns a description of the error