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.

Name	Type	Fields	Description
territoryId	Integer	M	Unique Arcadia 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	Description
territoryItemId	Integer	Unique Arcadia 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	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 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):

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 postcode, plus a country. Use this if you do not have the address parsed out in your app. If you do, it's 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 utility'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, searching and sorting parameters, and the required 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 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
            }
        }
    ]
}