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
Versions 4+ include international rates.
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!
modified_after No
Type: Integer
Timestamp, seconds since 1970-01-01T00:00:00, UTC.
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.
effective_on_date No
Type: Integer
Timestamp, seconds since 1970-01-01T00:00:00, UTC.
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.
is_default No
Options: true or false

Shows only those rates whose "Is Default" 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.
radius No
Type: Integer
Default: 0
Maximum: 200

Radius to include surrounding search result, in miles.
co_limit No
Type: Integer

Maximum number of companies to include in a geographic search (using lat/lon, or address).
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
is_default
Type: boolean

Is the most common rate for the given time period, sector and service type for the utility.
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

GET https://api.openei.org/utility_rates?version=5&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=5&format=csv&limit=3&api_key=EXAMPLE_API_KEY 
  1
  2
  3
  4

PageName
5374efea9bef51471a6965d0
5374efea9bef51471a6965d2
5374efea9bef51471a6965d4

Errors

Returns a description of the error