Developer Network NREL NREL Developer Network

Utility Rates by Census Region (GET /api/census_rate/v3)

Given a location and Census Bureau region level (block, blockgroup, tract), return the Census Bureau ID, utility rate and company information.

Request URL

GET /api/census_rate/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.

id Yes
Type: integer
Default: None
Identifiying number provided by requester.
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.
region No
Type: string
Default: block
Options: block, blockgroup, tract
The Census Bureau region level to return.

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.
census_region Type: string The Census Bureau ID.
residential Type: decimal The residential electricity rate.
commercial Type: decimal The commercial electricity rate.
industrial Type: decimal The industrial electricity rate.
partial_match Type: boolean A value of true indicates that the geocoder was not able to find an exact match on the original address. (only returned for address-based requests)
geocoded_address Type: string The actual (possibly corrected) address used by the geocoder to determine lat/lon. (only returned for address-based requests)

Examples

JSON Output Format

GET /api/census_rate/v3.json?api_key=DEMO_KEY&region=tract&id=101&lat=37&lon=-92
{
  "inputs" : {
    "region" : "tract",
    "id" : "101",
    "lat" : "35.45",
    "lon" : "-82.98"
  },
  "errors" : [ ],
  "warnings" : [ ],
  "outputs" : {
    "id" : 101,
    "uid" : "179f89b3-5fc2-4fc9-9993-926d71486b70",
    "census_region" : "921200",
    "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" : 9.77,
    "industrial" : 8.62,
    "residential" : 12.3
  },
  "version" : "3.1.0",
  "metadata" : {
    "sources" : [ "Ventyx Research (2012)" ]
  }
}

XML Output Format

GET /api/census_rate/v3.xml?api_key=DEMO_KEY&region=tract&id=101&lat=37&lon=-92
<?xml version="1.0" encoding="UTF-8"?>
<response>
  <inputs>
    <region>tract</region>
    <id>101</id>
    <lat>35.45</lat>
    <lon>-82.98</lon>
  </inputs>
  <errors type="array"/>
  <warnings type="array"/>
  <outputs>
    <id type="integer">101</id>
    <uid>c310bc56-ebbf-496c-8925-74bdf55d57a8</uid>
    <census-region>921200</census-region>
    <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">9.77</commercial>
    <industrial type="float">8.62</industrial>
    <residential type="float">12.3</residential>
  </outputs>
  <version>3.1.0</version>
  <metadata>
    <sources type="array">
      <source>Ventyx Research (2012)</source>
    </sources>
  </metadata>
</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