Web Services

Documentation » Fetch Utility Rates

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

The /utility_rates endpoint returns a list of information about utilities. You can specify utility rates to view, see all rates effective on a specific date, find all rates for a specific country, and more.

This information is collected and updated by Illinois State University on behalf of DOE and housed within the OpenEI.org platform.

You'll need an API key to send a request. You can request a free API key using our signup form.

Alternatively, we also support a wepage where you can browse the OpenEI U.S. Utility Rate Database without using the API.

On this Page

Standard Request

The request URL provides the endpoint where your request will be sent. You'll need to send a GET request to:

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

You'll replace parameters with any of the request parameters. All requests must include a version, format, and api_key.

Minimum Request Example

GET https://api.openei.org/utility_rates?version=latest&format=json&api_key=YOUR_API_KEY

This example will retrieve a list of all companies. Be sure to:

  • Replace latest with the version of the API you would like to use.
  • Replace json with the format you would like to recieve your response in.
  • Replace YOUR_API_KEY with your API key.

Request Parameters

Parameter Required Value Description
version Yes
Options: latest, 3, 4, 5, 6, or-7
Choose which version of the API you would like to use. We reccomend using the latest version. Versions 4+ include international rates.
format Yes
Options: json, csv, or json_plain

The format determines how the response will be output. The format parameter will be disregarded if the debug parameter is set.
api_key Yes
Type: String

You can request a free API key using our signup form.
modified_after No
Type: Integer

Returns all rates that were modified after a specific time and date.

For the timestamp, use the format: Timestamp, seconds since 1970-01-01T00:00:00, UTC.
limit No
Type: Integer
 Choose how many rates to return. You can return up to 500 rates. You can combine this parameter with offset to page through results.
getpage No
Type: String

Returns information associated with a specific webpage. You can set this parameter to the last part of the web page path for the result you want returned.

For example, for page https://apps.openei.org/USURDB/rate/view/539fc9d7ec4f024d2f53f5b6, set the value to 539fc9d7ec4f024d2f53f5b6.

The label response field contains the results for the page returned.
ratesforutility No
Type: String
 Returns all rates from a specific utility. To retrieve a full list of all utilities use the /GET — Fetch all Utility Companies endpoint.
offset No
Type: Integer
Default: 0
 Returns a list of records starting from a certain record number. For example, if you have set a limit of 500 records, but would like to return the records 500-1,000, you can set the offset to 500.
orderby No
Type: Field Name
Default: label
 Choose how to sort results. You can set this field to any request parameter and results will be returned alphanumerically.
direction No
Type: String
Default: asc
Options: asc, or desc
Search results are returned alphanumerically. Choose if you would like result to be returned in ascending or descending order.
effective_on_date No
Type: Integer

Returns all rates that are effective starting at a specific time and date.

For the timestamp use the format: Timestamp, seconds since 1970-01-01T00:00:00, UTC.
sector No
Options: Residential, Commercial, Industrial, or Lighting

Returns rates matching the specified sector. For example, Residential, Commericial, Industrial, or Lighting.
approved No
Options: true or false

  • Returns rates that have been approved if set to true.

  • Returns rates that have not been approved if set to false.
is_default No
Options: true or false

  • Returns default rates if set to true.

  • Returns rates that are not the default if set to false.
country No
Type: String

Returns all rates from a specified country. Set the parameter to an ISO 3 character country code. For example, country=USA.
address No
Type: String

Returns all rates from a specified address. See Google Geocoding API for details.

You must set either an address or a latitude and longitude.
lat No
Type: Integer

Returns all rates from a specific latitude and longitude. You must also set the longitude parameter to return results.

You must set either an address or a latitude and longitude.
lon No
Type: Integer

Returns all rates from a specific latitude and longitude. You must also set the latitude parameter to return results.

You must set either an address or a latitude and longitude.
radius No
Type: Integer
Default: 0
Maximum: 200

Returns all results that are a specified radius from the address or latitude and longitude. You must set either an address or a latitude and longitude. The radius is measured in miles.
co_limit No
Type: Integer

Choose how many companies to include in a geographic search.

You must set either an address or a latitude and longitude.
eia No
Type: Integer

Returns a single utility associated with an EIA ID.
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. This results in a lot of data that can time-out returning to your server. We reccomend using limit and offset if you want more data.
  • detail=minimal - Returns only the response fields associated with the request parameters set.

Response Fields

Field Value Description
label
Type: string

The page label is the last part of the web page path.

For example, for page https://apps.openei.org/USURDB/rate/view/539fc9d7ec4f024d2f53f5b6, the page label is 539fc9d7ec4f024d2f53f5b6.
utility
Type: string

The name of the utility company.
name
Type: string

The name of the rate. For example, Residential (RS).
uri
Type: URI

The link to the page in the URDB where the rate is listed.
approved
Type: boolean

Returns true if verified by an expert.
is_default
Type: boolean

Returns true if the rate is the most common rate for the given time period, sector, and service type for the utility.
startdate
Type: integer

The date and time that the rate became effective.
enddate
Type: integer

The date and time that the rate was sunset.
supercedes
Type: string

The label of the rate this rate supercedes. In most cases, this is the rate that was effective previously.
sector
Type: enumeration

"Residential", "Commercial", "Industrial", or "Lighting"
servicetype
Type: enumeration

"Bundled", "Energy", "Delivery", or "Delivery with Standard Offer"
description
Type: string

A description of the rate.
source
Type: string

A link directly to the rate sheet or book that provides information for the specified rate.
sourceparent
Type: URI

A link to the company website for the given rate.
basicinformationcomments
Type: string

The comments added to the URDB to characterize the rate. Basic comments are often added when an aspect of a rate can't be captured in the URDB or specific applicability rules apply.
peakkwcapacitymin
Type: decimal

The minimum demand usage (kW) that must be met to be applicable for this rate.
peakkwcapacitymax
Type: decimal

The maximum demand usage (kW) that must be met to be applicable for this rate.
demandunits
Type: enumeration

"kW", "hp", "kVA", "kW daily", "hp daily", or "kVA daily"
peakkwcapacityhistory
Type: decimal

The number of months that a maximum or minimum demand history applies to.
peakkwhusagemin
Type: decimal

The minimum energy usage (kWh) that must be met to be applicable for this rate.
peakkwhusagemax
Type: decimal

The maximum energy usage (kWh) that must be met to be applicable for this rate.
peakkwhusagehistory
Type: decimal

The number of months that a maximum or minimum energy history applies to.
voltageminimum
Type: decimal

The minimum service voltage usage (V) that must be met to be applicable for this rate.
voltagemaximum
Type: decimal

The maximum service voltage usage (V) that must be met to be applicable for this rate.
voltagecategory
Type: enumeration

"Primary", "Secondary", or "Transmission"
phasewiring
Type: enumeration

"Single Phase","3-Phase", or "Single and 3-Phase"
flatdemandunit
Type: enumeration

"kW", "hp", "kVA", "kW daily", "hp daily", or "kVA daily"
flatdemandstructure
Type: array

The seasonal/monthly demand charge structure is represented by a multidemsional array. Each element in the top-level array corresponds to one period. These periods are represent by the flatdemandmonths parameter. Each array element within a period corresponds to one tier. Indices are zero-based to correspond with flatdemandmonths entries: [[{"max":(Decimal),"rate":(Decimal),"adj":(Decimal)},...],...]

Note: 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

The nested array that includes 12 integers, one per month, where each corresponds to the index of a period in flatdemandstructure parameter.

Note: 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

"kW", "hp", "kVA", "kW daily", "hp daily", or "kVA daily"
demandratestructure
Type: array

The time of use demand charge structure is represented by a multidemsional array. Each element in the top-level array corresponds to one period. These periods are represent by the demandweekdayschedule parameter. Each array element within a period corresponds to one tier. Indices are zero-based to correspond with demandweekdayschedule and/or demandweekendschedule entries: [[{"max":(Decimal),"rate":(Decimal),"adj":(Decimal),"sell":(Decimal)},...],...]

Note: 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

In the time of use demand charge structure weekday schedule, the value returned 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

In the time of use demand charge structure weekend schedule, the value returned 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 demandratestructure.
demandratchetpercentage
Type: array

The Demand Ratchet Percentage per month, which is represented by an array of 12 decimal numbers.
demandwindow
Type: decimal

The amount of time, in minutes, that a demand charge applies.
demandreactivepowercharge
Type: decimal

The demand reactive power charge ($/kVAR).
coincidentrateunit
Type: enumeration

"kW", "hp", "kVA", "kW daily", "hp daily", or "kVA daily"
coincidentratestructure
Type: array

The coincident rate structure is represented by a multidemsional array. Each element in the top-level array corresponds to one period. These periods are represent by the coincidentrateschedule. 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: 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

In the coincident rate structure schedule, the value returned 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

A list of any additional attribute and value pairs that characterize the demand charge.
demandcomments
Type: string

The demand comments list any factors needed to calculate the demand rate and all adjustments used to calculate the demand adjustment charge.
dgrules
Type: enumeration

The type of compensation that is offered for distributed generation. For example, "Net Metering", "Net Billing Instantaneous", "Net Billing Hourly", or "Buy All Sell All."
energyratestructure
Type: array

The tiered energy usage charge structure is represented by a multidemsional array. Each element in the top-level array corresponds to one period. These periods are represent by the 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: 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

In the tiered energy usage charge structure weekday schedule, the value returned 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

In the tiered energy usage charge structure weekend schedule, the value returned 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

The monthly fuel adjustment value is represented by an array of 12 decimal numbers, one per month, each is $/kWh.
energyattrs
Type: array

A list of any additional attribute and value pairs that characterize the energy charge.
energycomments
Type: string

The energy comments list any factors needed to calculate the demand rate and all adjustments used to calculate the demand adjustment charge.
fixedchargefirstmeter
Type: decimal

The fixed customer charge. This can be charged per month, day, or year. You can see at what frequency the rate is being charged under fixedchargeunits.
fixedchargeeaaddl
Type: decimal

The fixed customer charge for each additional meter. You can see at what frequency the rate is being charged under fixedchargeunits.
fixedchargeunits
Type: enumeration

The frequency that the customer is charged the fixedchargefirstmeter customer charge and the fixedchargeeaaddl for thier first and additional meters. Fixed charge units include: "$/day", "$/month", or "$/year".
mincharge
Type: decimal

The minimum charge ($) is the minimum amount the customer pays. You can see at what frequency the rate is being charged under minchargeunits.
minchargeunits
Type: enumeration

The frequency that the customer is charged the mincharge for thier meters. Fixed charge units include: "$/day," "$/month," or "$/year".
fixedattrs
Type: array

A list of any additional attribute and value pairs that characterize the fixed charge.

Examples

Get a list of utilities in JSON format

Request

GET https://api.openei.org/utility_rates?version=5&format=json&limit=3&api_key=YOUR_API_KEY

Be sure to:

  • Replace YOUR_API_KEY with your API key.
  • Set the limit to the number of records you would like returned.

Response

 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"}]
}

Get a list of utilities in CSV format

Request

GET https://api.openei.org/utility_rates?version=5&format=csv&limit=3&api_key=YOUR_API_KEY

Be sure to:

  • Set the version to the version of the API you would like to use.
  • Replace YOUR_API_KEY with your API key.
  • Set the limit to the number of records you would like returned.

Response

  1
  2
  3
  4

PageName
5374efea9bef51471a6965d0
5374efea9bef51471a6965d2
5374efea9bef51471a6965d4

Get a specific utility

Request

GET https://api.openei.org/utility_rates?version=5&format=json&limit=3&ratesforutility=PacifiCorp&api_key=YOUR_API_KEY

Be sure to:

  • Set the format to the format you would like to output.
  • Set the version to the version of the API you would like to use.
  • Set the limit to the number of records you would like returned.
  • Set PacificCorp to the utitily you would like to return rates for.
  • Replace YOUR_API_KEY with your API key.

Response

Label URI Sector Start Date End Date Country Name Utility Approved 
539f6b16ec4f024411ec9837
 
Link
 
Residential
 
08/12/2013
 
06/06/2014
 
USA
 
Schedule D- Standard Residential (Non-Baseline)
 
PacifiCorp
 
True
 
539f6b34ec4f024411ec9999
 
Link
 
Commercial
 
08/12/2013
 
06/06/2014
 
USA
 
Schedule A-32 Secondary (1 Phase)
 
PacifiCorp
 
True
 
539f6bfbec4f024411eca439
 
Link
 
Commercial
 
08/12/2013
 
06/06/2014
 
USA
 
Schedule AT-48 Secondary
 
PacifiCorp
 
True

Get a specific utility by page

Request

GET https://api.openei.org/utility_rates?version=5&format=json&limit=3&getpage=539fc9d7ec4f024d2f53f5b6&api_key=YOUR_API_KEY

Be sure to:

  • Set the format to the format you would like to output.
  • Set the version to the version of the API you would like to use.
  • Set the limit to the number of records you would like returned.

  • Set 539fc9d7ec4f024d2f53f5b6 to the page you would like rates returned from.

    For example, for page https://apps.openei.org/USURDB/rate/view/539fc9d7ec4f024d2f53f5b6, set the value to 539fc9d7ec4f024d2f53f5b6.

  • Replace YOUR_API_KEY with your API key.

Response

  1
 
label: 539fc9d7ec4f024d2f53f5b6
 
  2
 
uri: https://apps.openei.org/IURDB/rate/view/539fc9d7ec4f024d2f53f5b6
 
  3
 
sector: Lighting
 
  4
 
source: www.cloverland.com/mainNav/myService/ratesAndRules/legacyCloverlandRates.aspx
 
  5
 
country: USA
 
  6
 
name: Outdoor Lighting - LED - Existing Pole
 
  7
 
eiaid: 3828
 
  8
 
utility: Cloverland Electric Co-op
 
  9
 
approved: true
 
 10
 
revisions: 1372774968, 1372775001, 1374008049, 1427405217

Errors

Standard errors may be returned. In addition, the following service-specific errors may be returned:

HTTP Status Code Description
400 Invalid Request — One or more parameters did not pass validation or a parameter may be missing. Check the error section of the response to see how the request URL should be modified to address the error.
500 A problem occurred on the server-side. This is likely due to a failure of a downsteram service. The request cannot be processed at this time.

Additional Resources