Territory

Territories define geographic areas in the Arcadia 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.

Territory Item

The TerritoryItem object has the following data structure.

Territory LSE

A territory LSE has the following data structure.

The list of Territory LSEs is only populated 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):

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:

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 utilty's 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.

{
    "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 tariff's service area. These are sometimes called "baseline regions". Tariffs like this are common in California, for instance. Arcadia 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 postcode, 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:

{
    "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

{
    "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 endpoint 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:

Example 1 - Simple Case

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

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

{
    "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 (sometimes called Retail Energy Providers) for AEP Texas North service area.

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

{
    "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
            }
        }
    ]
}