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.
GET /api/utility_rates/v3.format?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. |
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) |
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). |
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
}
}
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>
Standard rate limits apply. No more than 1,000 requests may be made in any hour
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. |