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. 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