Territory

  • signal
  • explorer
Switch product users. Your developer documentation has moved over to the switchsolar.io website.

Territories define geographic areas in the Genability database. They can represent the service area for a Load Serving Entity, the “Baseline Region” for a particular tariff, or an ASHRAE climate zone.

A territory is defined as a set of territory items, each of which represents some geographic region. These items can specified at four different levels of granularity:

  • State – The territory covers the entire state of California.
  • County – The territory covers Orange, Los Angeles, and San Bernardino counties.
  • City – The territory covers San Francisco and Oakland.
  • ZIP Code – The territory covers ZIP codes 94100 - 94105.

The territory itself will also be one of four different types:

  • SERVICE – defines the areas where this LSE provides service
  • TARIFF – defines the areas where a particular tariff rate applies to. These types of territories are typically defined by the LSE. An example of this is “Baseline Region X” in PG&E territory. This how-to has more.
  • CLIMATE_ZONE – The set of ASHRAE climate zones for the United States
  • UTILITY_CLIMATE_ZONE – The intersection of an ASHRAE climate zone and a utility’s service area. For example, both PG&E and SCE have territory that is in climate zone 3C, so they will both have a corresponding UTILITY_CLIMATE_ZONE.

Each LSE will have at least one service territory for each state where it provides coverage. It will also have at least one utility climate zone (UCZ). The itemTypes attribute (defined below) specifies how this area is defined, either at the state, county, city, or ZIP code level.

Data Definitions

Territory

A territory has the following data structure.

Name Type Fields Description
territoryId Integer M Unique Genability ID (primary key) for each territory
territoryName String M The name of the territory (i.e. ‘Service Area for CA’ or ‘Baseline Region H’).
lseId Integer M The ID of the LSE this Territory belongs to
lseName String M The name of the LSE (utility) that this territory belongs to.
parentTerritoryId Integer   The ID of the parent territory (null if it does not have a parent). Typically this will be on a tariff territory that ties it back to the service territory.
usageType String   The type of territory this defines, one of SERVICE, TARIFF, CLIMATE_ZONE, or UTILITY_CLIMATE_ZONE.
itemTypes String   The type of the items that define the physical area of coverage of this territory. Possible values are: STATE, COUNTY, CITY, and ZIPCODE.
items List of Territory Items   The list of Territory Items that define the area covered by this territory.
territoryLses Paginated List of Territory LSE   The list of LSEs that offer service (retail) to customers in this territory. Applies to deregulated markets.
deregRes Boolean   Whether the residential electricity market in this territory is deregulated.
deregCandi Boolean   Whether the commercial and industrial electricity market in this territory is deregulated.
centerPoint Coordinate   The latitude and longitude of the centerpoint of this territory.

Territory Item

The TerritoryItem object has the following data structure.

Name Type Fields Description
territoryItemId Integer   Unique Genability ID (primary key) for each territory Item
territoryType String   The type of this territory item. Possible values are: STATE, COUNTY, CITY, and ZIPCODE.
value String   The name of the territory item (i.e. ‘Kirkwood’ or ‘94115’).
exclude Boolean   If true, this territory item is not included as part of the coverage area of the parent territory.
partial Boolean   If true, then only a partial area of this territory item is covered by this LSE.

Territory LSE

A territory LSE has the following data structure.

Name Type Fields Description
territoryId Integer   The territoryId this Territory LSE belongs to
lseId Integer   The lseId of the LSE offering service in this Territory
lseName String   The name of the LSE
distribution Boolean   true or false indicating whether this LSE is a distribution LSE
supplierResidential Boolean   true or false indicating whether this LSE supplies service to residential customers
supplierGeneral Boolean   true or false indicating whether this LSE supplies service to general (commercial and industrial) customers
residentialCoverage Decimal   Percentage of residential customers this LSE supplies service to
generalCoverage Decimal   Percentage of general (commercial and industrial) customers this LSE supplies service to

The list of Territory LSEs is only populate on the Get One Territory, and only when optionally requesting them. When they are populated, the list is wrapped in the following fields (see the example below too):

Name Type Description
totalCount Integer The total number of Territory LSEs for the Service Area.
pageCount Integer The number of Territory LSEs returned per page.
pageStart Integer The item index where the current page begins.
list List The list of Territory LSEs returned for the current page.

Get a List of Territories

This returns a list of territories for a given search criteria, such as for a given LSE. The result set is a list of territory objects in the standard response format.

Resource URI

GET /rest/public/territories

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
zipCode String Filters the result to include only territories that this ZIP code is a part of.
postCode String Alias for zipCode, you can use either.
country ISO Country Code Optional. Recommended when passing in zipCode or postCode. We default this to US when zipCode or postCode is populated.
addressString String An address of any kind (e.g. San Francisco, CA, 94105, USA). Ideally this will contain a zipcode or post code, plus a country. Use this if you do not have the address parsed out in your app. If you do, its better to use postCode and country (Optional)
address String Alias for addressString, you can use either.
lseId Integer Filters the result set to only include territories within this LSE ID (Optional).
populateItems Boolean If true, this returns a list of territory items for each territory in the result set. (Optional; defaults to false)
masterTariffId Integer For tariffs with prices varying by geographic location, this will return the list of those territories covered by this tariff. 3% of all tariffs have territory based pricing and those are typically in CA, NY and MA. For the 97% of tariffs that do not have territory based pricing, the result set will be empty. (Optional)
usageTypes String Result will include territories of the specified usageType. If not set the results will be limited to those of usage type "SERVICE" or "TARIFF".
populateLses Boolean If true, this returns a list of territory LSEs which are all the LSEs providing service in this territory. (Optional)
containsItemType String Filters by the type of the territory items in each territory and must appear with containsItemValue. Possible values are: STATE, COUNTY, CITY, and ZIPCODE.
containsItemValue String Filters by the value of the territory items in each territory and must appear with containsItemType.

Example 1 - All Territories for a Utility

The following call gets every usage type of territory for the given utility, by explicitly asking for them via the usageTypes request parameter. If this parameter is omitted, only those of type SERVICE and TARIFF are included.

GET /rest/public/territories?lseId=734&usageTypes=SERVICE,TARIFF,UTILITY_CLIMATE_ZONE

The results back include various usageType territories. Note that in this case, along with the utilties service area(s) (SERVCE) and their rate level baseline regions (TARIFF), the results include Utility Climate Zones too (UTILITY_CLIMATE_ZONE). Note some results have been removed from the response example to keep the page smaller.

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
58
59
60
61
62
63
64
65
66
67
68

{
    "status": "success",
    "count": 11,
    "type": "Territory",
    "results": [
        {
            "territoryId": 807,
            "territoryName": "Service area for CA",
            "lseId": 734,
            "lseName": "Pacific Gas & Electric Co",
            "usageType": "SERVICE",
            "itemTypes": "COUNTY",
            "deregRes": false,
            "deregCandi": false,
            "centerPoint": {
                "latitude": 37.825256018379214,
                "longitude": -121.35850650459477
            }
        },
        {
            "territoryId": 3534,
            "territoryName": "Baseline Region P",
            "lseId": 734,
            "lseName": "Pacific Gas & Electric Co",
            "parentTerritoryId": 807,
            "usageType": "TARIFF",
            "itemTypes": "ZIPCODE",
            "deregRes": false,
            "deregCandi": false,
            "centerPoint": {
                "latitude": 38.81323759210526,
                "longitude": -121.25965298684213
            }
        },
        {
            "territoryId": 3535,
            "territoryName": "Baseline Region Q",
            "lseId": 734,
            "lseName": "Pacific Gas & Electric Co",
            "parentTerritoryId": 807,
            "usageType": "TARIFF",
            "itemTypes": "ZIPCODE",
            "deregRes": false,
            "deregCandi": false,
            "centerPoint": {
                "latitude": 37.018478,
                "longitude": -121.92218766666667
            }
        },
        {
            "territoryId": 3858,
            "territoryName": "Pacific Gas & Electric Co - Baseline Region T - 3C",
            "lseId": 734,
            "lseName": "Pacific Gas & Electric Co",
            "parentTerritoryId": 3538,
            "usageType": "UTILITY_CLIMATE_ZONE",
            "itemTypes": "ZIPCODE",
            "deregRes": false,
            "deregCandi": false,
            "centerPoint": {
                "latitude": 37.22589772602739,
                "longitude": -122.04498898630153
            }
        }
    ],
    "pageCount": 25,
    "pageStart": 0
}

Example 2 - Baseline Region (Rate) Territories for a Location

A small number of tariffs have rates that vary by “sub-region” within the tariffs service area. These are sometimes called “baseline regions”. Tariffs like this are common in California, for instance. Genability defines each of these regions as a Territory with a usageType of TARIFF. We will default to the best territoryId when we run calculations, but if you know the customer’s post code, country code, and lseId, you can get a list of these baseline region territories using the following call:

GET /rest/public/territories?postCode=94105&country=US&lseId=734&usageType=TARIFF

For the above location there is only one, but sometimes a zip can have several:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

{
    "status": "success",
    "count": 1,
    "type": "Territory",
    "results": [
        {
            "territoryId": 3538,
            "territoryName": "Baseline Region T",
            "lseId": 734,
            "lseName": "Pacific Gas & Electric Co",
            "parentTerritoryId": 807,
            "usageType": "TARIFF",
            "itemTypes": "ZIPCODE",
            "deregRes": false,
            "deregCandi": false,
            "centerPoint": {
                "latitude": 37.268442714285754,
                "longitude": -122.0622513529413
            }
        }
    ],
    "pageCount": 25,
    "pageStart": 0
}

There is a how-to on Baseline Regions / Tariff Territories for those who want to know more.

Example 3 - Territories for a Specific Territory Item Type and Value

Territories can be filtered further by their territory items. You must specify both containsItemType and containsItemValuein order to filter in this way. In this example, Duke Energy Carolinas operates in both North Carolina and South Carolina. However, in this request we filter to find only one state’s territory.

GET /rest/public/territories?lseId=2416&containsItemType=STATE&containsItemValue=NC

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

{
    "status": "success",
    "count": 1,
    "type": "Territory",
    "results": [
        {
            "territoryId": 2711,
            "territoryName": "Service area for NC",
            "lseId": 2416,
            "lseName": "Duke Energy Carolinas, LLC",
            "usageType": "SERVICE",
            "itemTypes": "COUNTY",
            "deregRes": false,
            "deregCandi": false,
            "centerPoint": {
                "latitude": 35.70686471951216,
                "longitude": -80.52416623867603
            }
        }
    ],
    "pageCount": 25,
    "pageStart": 0
}

Get One Territory

This allows you to retrieve one territory.

Resource URI

GET /rest/public/territories/{territoryId}

Request Parameters

The Get One Territory enpoint is a little unusual in that, unlike most ‘Get One’ endpoints, it optionally supports the same standard pagination parameters and searching and sorting parameters that are typical of ‘Get Many’ endpoints. However, in this case those parameters are applied to the list of Territory LSEs that are returned in the territoryLses property when populateLses is set to true. Along with these and the required security parameters, the following parameters are available as part of the request:

Name Type Description
populateItems Boolean If true, this returns a list of territory items for the territory. (Optional; defaults to false)
populateLses Boolean For deregulated markets such as Texas. When true, this returns a list of LSEs (utilities) that supply this market. (Optional; defaults to false)

Example 1 - Simple Case

This example is a simple as it gets. Just get the Territory using its primary key, territoryId.

GET /rest/public/territories/3539?fields=ext

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

{
    "status": "success",
    "count": 1,
    "type": "Territory",
    "results": [
        {
            "territoryId": 3539,
            "territoryName": "Baseline Region V",
            "lseId": 734,
            "lseName": "Pacific Gas & Electric Co",
            "parentTerritoryId": 807,
            "usageType": "TARIFF",
            "itemTypes": "ZIPCODE",
            "deregRes": false,
            "deregCandi": false,
            "centerPoint": {
                "latitude": 40.690513440000004,
                "longitude": -124.06306692000003
            }
        }
    ]
}

Example 2 - With Territory LSEs

This example shows what is returned when populateLses=true for a service area that has deregulated Suppliers. In this case we are querying the first 5 suppliers (or sometimes called Retail Energy Providers) for AEP Texas North service area.

GET /rest/public/territories/1880?populateLses=true&pageStart=0&pageCount=5

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
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73

{
    "status": "success",
    "count": 1,
    "type": "Territory",
    "results": [
        {
            "territoryId": 1880,
            "territoryName": "Service area for TX",
            "lseId": 1683,
            "lseName": "AEP Texas North Company",
            "usageType": "SERVICE",
            "itemTypes": "COUNTY",
            "territoryLses": {
                "totalCount": 32,
                "pageCount": 5,
                "pageStart": 0,
                "list": [
                    {
                        "lseId": 1504,
                        "lseName": "TXU Energy Retail Company LLC",
                        "distribution": null,
                        "supplierResidential": null,
                        "supplierGeneral": null,
                        "residentialCoverage": 33.8,
                        "generalCoverage": 29
                    },
                    {
                        "lseId": 962,
                        "lseName": "Reliant Energy Retail Services LLC",
                        "distribution": null,
                        "supplierResidential": null,
                        "supplierGeneral": null,
                        "residentialCoverage": 24.4,
                        "generalCoverage": 24.1
                    },
                    {
                        "lseId": 2367,
                        "lseName": "Stream SPE Ltd",
                        "distribution": null,
                        "supplierResidential": null,
                        "supplierGeneral": null,
                        "residentialCoverage": 6.6,
                        "generalCoverage": 2
                    },
                    {
                        "lseId": 968,
                        "lseName": "Direct Energy LP",
                        "distribution": null,
                        "supplierResidential": null,
                        "supplierGeneral": null,
                        "residentialCoverage": 5.3,
                        "generalCoverage": 0.6
                    },
                    {
                        "lseId": 2818,
                        "lseName": "Green Mountain Energy Company",
                        "distribution": null,
                        "supplierResidential": null,
                        "supplierGeneral": null,
                        "residentialCoverage": 3.9,
                        "generalCoverage": 3.6
                    }
                ]
            },
            "deregRes": true,
            "deregCandi": true,
            "centerPoint": {
                "latitude": 32.11142894210524,
                "longitude": -100.38199182105262
            }
        }
    ]
}