Note that this API is deprecated. If you are a Switch customer, use the Account Cost Calculation API and if you are a Signal customer use the On-demand Cost Calculation API. Ask us if you have any questions.

The Place API allows you to retrieve regional averages for various metrics including:

  • average monthly consumption
  • average per kWh cost
  • average monthly cost

These metrics are provided across industrial, residential and commercial customers. While the Place API offers a quick way to get average numbers for a region, using the Tariff, the Price, the Account Calculator, or the On-demand Calculator give much more detailed and accurate data. The Place API is provided to solve two use cases:

  • when you need a quick answer to the question of ‘what is the average cost per kWh in zip code xxxxx?’
  • when Genability does not provide detailed coverage of a region. For example, if you call the get Tariffs method for zip code xxxxx and the result set is empty, then you should use Place API as Genability does not yet have accurate data for this region.

Data Definitions

Place

A Place object has the following data structure.

Name Type Description
placeKey PlaceKey Consisting of placeType (e.g. "zipCode") and placeValue (e.g. "94109"). Defines a unique key for the Place object
location Location Location object containing the geometric coordinates of the Place object.
address Address The Address object corresponding to the Place object.
facts Array of Place Facts Energy metrics corresponding to the place.

Place Facts

The Place Fact has the following data structure.

Name Type Description
electricity_typicals Map of String to Map A map of energy use metrics segmented into residential, commercial, and industrial groupings.
electricity_likelyTariff Map of String to Map The tariff most likely to be what customers in this zipcode are on. For residential customers this is the utility’s default tariff. The returned data is a map of the tariff and various properties related to it.

Operations

Get Metrics for a ZIP Code

This returns a place object and associated facts/metrics by ZIP code. The result set is a Place object in the standard response format.

Resource URI

GET /rest/places/zipcode/{zipcode}

Request Parameters

Along with the standard pagination parameters, searching and sorting parameters, and the required security parameters, the following parameters are available as part of the request:

Name Type Description
betaUseUnderscore Boolean By default the keys within the ‘facts’ map use dot notation in their names, e.g. electricity.typicals. Alternatively, you can use an underscore, e.g. electricity_typicals. (Optional)

Example

Here’s an example in JSON of a fully populated Place object with facts:

GET /rest/places/zipcode/32216?betaUseUnderscore=true
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
{
    "status": "success",
    "count": 1,
    "type": "Place",
    "results": [
        {
            "placeKey": {
                "placeType": "zipcode",
                "placeValue": "32210"
            },
            "name": "JACKSONVILLE,32210",
            "location": {
                "latitude": 30.274794,
                "longitude": -81.751056
            },
            "address": {
                "addressString": "JACKSONVILLE, FL - 32210",
                "state": "FL",
                "zip": "32210",
                "city": "JACKSONVILLE"
            },
            "facts": {
                "electricity_likelyTariff": {
                    "residential": {
                        "masterTariffId": 80760,
                        "tariffCode": "R",
                        "tariffName": "Residential Service",
                        "lseId": 2127,
                        "lseName": "Clay Electric Cooperative, Inc",
                        "likelihood": null,
                        "source": "Genability"
                    }
                },
                "electricity_typicals": {
                    "industrial": {
                        "avgMonthlyConsumption": 79719,
                        "avgRate": 8.85,
                        "avgMonthlyCost": 7058,
                        "source": "EIA EPM for FL"
                    },
                    "residential": {
                        "avgMonthlyConsumption": 1194,
                        "avgRate": 11.44,
                        "avgMonthlyCost": 136.61,
                        "source": "EIA EPM for FL"
                    },
                    "commercial": {
                        "avgMonthlyConsumption": 6773,
                        "avgRate": 9.76,
                        "avgMonthlyCost": 661.09,
                        "source": "EIA EPM for FL"
                    }
                }
            }
        }
    ]
}

History

  • Formatting updates - 3/10/2015
  • Initial Release - 3/9/2012 - Place
  • Added likelyTariff - 8/28/2012