Developer Network NREL NREL Developer Network
  1. Documentation
  2. Electricity
  3. Utility Rates

Utility Rates (GET /api/utility_rates/v3)

This service returns annual average utility rates ($/kWH) for residential, commercial and industrial sectors as well as the local utility name for a specific location. This service does not return complex rate information.

The data source is Ventyx Research Inc. and the Energy Information Agency (EIA), and was updated with 2012 numbers.

Version 3 is the current version of the utility rates API. Previous versions have been deprecated and its users are encouraged to migrate to this newly enhanced version.

Request URL

GET /api/utility_rates/v3.format?parameters

Request Parameters

Parameter Required Value Description
format Yes
Type: string
Default: None
Options: json, xml

The output response format.
api_key Yes
Type: string
Default: None

Your developer API key. See API keys for more information.
address Depends
Type: string
Default: None

The address to use (lat/lon returned by Google's geocoding service). Required if lat/lon not provided.
lat Depends
Type: decimal
Default: None
Range: -90 to 90
The latitude for the location to use. Required if address not given.
lon Depends
Type: decimal
Default: None
Range: -180 to 180
The longitude for the location to use. Required if address not given.

Response Fields

The response is composed of service-related informational fields and the results of the data query.

Field Value Description
inputs Type: collection The input parameters received in the request.
version Type: string The current version of the web service.
errors Type: array of strings Any error messages resulting from the request.
warnings Type: array of strings Any warning messages resulting from the request.
metadata Type: collection Any metadata associated with the request (sources, etc)
outputs Type: collection The data outputs from the request. (see output fields for more detail)

Output Fields

Field Value Description
utility_name Type: string The name of the utility company. If there are multiple utility companies serving the location, the names will be returned as a pipe-delimited string.
company_id Type: integer The ID of the utility company. If there are multiple utility companies serving the location, the IDs will be returned as a pipe-delimited string.
utility_info Type: collection An array of hashes containing the name(s) and ID(s) of the utility company or companies serving the location.
residential Type: decimal The residential electricity rate ($/kWh).
commercial Type: decimal The commercial electricity rate ($/kWh).
industrial Type: decimal The industrial electricity rate ($/kWh).

Examples

JSON Output Format

GET /api/utility_rates/v3.json?api_key=DEMO_KEY&lat=35.45&lon=-82.98
{
  "inputs" : {
    "lat" : "35.45",
    "lon" : "-82.98"
  },
  "errors" : [ ],
  "warnings" : [ ],
  "version" : "3.1.0",
  "metadata" : {
    "sources" : [ "Ventyx Research (2012)" ]
  },
  "outputs" : {
    "company_id" : "8333|18642",
    "utility_name" : "Haywood Electric Member Corp|Tennessee Valley Authority",
    "utility_info" : [ {
      "company_id" : "8333",
      "utility_name" : "Haywood Electric Member Corp"
    }, {
      "company_id" : "18642",
      "utility_name" : "Tennessee Valley Authority"
    } ],
    "commercial" : 0.0977,
    "industrial" : 0.0862,
    "residential" : 0.123
  }
}

XML Output Format

GET /api/utility_rates/v3.xml?api_key=DEMO_KEY&lat=35.45&lon=-82.98
<?xml version="1.0" encoding="UTF-8"?>
<response>
  <inputs>
    <lat>35.45</lat>
    <lon>-82.98</lon>
  </inputs>
  <errors type="array"/>
  <warnings type="array"/>
  <version>3.1.0</version>
  <metadata>
    <sources type="array">
      <source>Ventyx Research (2012)</source>
    </sources>
  </metadata>
  <outputs>
    <company-id>8333|18642</company-id>
    <utility-name>Haywood Electric Member Corp|Tennessee Valley Authority</utility-name>
    <utility-info type="array">
      <utility-info>
        <company-id>8333</company-id>
        <utility-name>Haywood Electric Member Corp</utility-name>
      </utility-info>
      <utility-info>
        <company-id>18642</company-id>
        <utility-name>Tennessee Valley Authority</utility-name>
      </utility-info>
    </utility-info>
    <commercial type="float">0.0977</commercial>
    <industrial type="float">0.0862</industrial>
    <residential type="float">0.123</residential>
  </outputs>
</response>

Rate Limits

Standard rate limits apply. No more than 1,000 requests may be made in any hour

Errors

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

HTTP Status Code Description
422 Unprocessable Entity - One or more parameters did not pass validation, or a parameter may be missing. Check the errors section of the response to see how the request should be modified to address the error.
Help Improve this Content