Territories

Use Territories to retrieve geographic areas that define utility service coverage, tariff applicability, baseline regions, and climate zones.

Territories define geographic areas in the Arcadia database. They can represent the service area for a Load Serving Entity, the baseline region for a tariff, or an ASHRAE climate zone.

Use ZIP Codes with Territories when you need location metadata before finding service areas, tariff territories, baseline regions, or utility climate zones.

A territory is defined as a set of territory items, each of which represents a geographic region. Territory items can be specified at four 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 to 94105.

The territory itself has one of four usage types:

SERVICE: Areas where the LSE provides service.
TARIFF: Areas where a particular tariff rate applies. These territories are typically defined by the LSE. For example, PG&E baseline regions are tariff territories. See Baseline Regions / Tariff Territories for more.
CLIMATE_ZONE: 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 in climate zone 3C, so each can 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.

Get Territories

Find territories by location, LSE, tariff, usage type, or territory item.

Get One Territory

Retrieve one territory by territoryId.

ZIP Codes

Retrieve ZIP code metadata used in location-based territory and tariff discovery workflows.

Data Definitions

Territory

A Territory object 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 TerritoryLSE object 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 Get One Territory when you request it with populateLses=true. When populated, the list is wrapped in the following fields:

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 Territories

Retrieve territories that match search criteria, such as an LSE, location, tariff, or territory item. The result set is a list of Territory objects in the standard response format.

Resource URI

GET /rest/public/territories

Request parameters

Name	Type	Description
zipCode	String	Return territories that include this ZIP code. Optional.
postCode	String	Alias for `zipCode`. Optional.
country	ISO Country Code	ISO country code. Recommended when passing `zipCode` or `postCode`. Defaults to `US` when `zipCode` or `postCode` is populated. Optional.
addressString	String	Address to use for location-based filtering, such as `San Francisco, CA, 94105, USA`. Use this if your app does not have parsed address fields. If it does, use `postCode` and `country`. Optional.
address	String	Alias for `addressString`. Optional.
lseId	Integer	Return territories within this LSE ID. Optional.
populateItems	Boolean	When `true`, returns territory items for each territory in the result set. Defaults to `false`. Optional.
masterTariffId	Integer	Return territories covered by a tariff with territory-based pricing. About 3% of tariffs have territory-based pricing, typically in CA, NY, and MA. For tariffs without territory-based pricing, the result set is empty. Optional.
usageTypes	String	Return territories with the specified `usageType`. If omitted, results are limited to `"SERVICE"` and `"TARIFF"` territories. Optional.
populateLses	Boolean	When `true`, returns territory LSEs that provide 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 request gets every usage type of territory for the given utility by explicitly setting the usageTypes request parameter. If this parameter is omitted, only SERVICE and TARIFF territories are included.

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

The response includes multiple usageType territories. In this example, the results include the utility's service areas (SERVICE), rate-level baseline regions (TARIFF), and utility climate zones (UTILITY_CLIMATE_ZONE). Some results have been removed from the example to keep it shorter.

{
    "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 and are common in California. Arcadia defines each of these regions as a Territory with a usageType of TARIFF.

Arcadia defaults to the best territoryId during calculations. If you know the customer's postcode, country code, and lseId, you can retrieve candidate baseline-region territories with this request:

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

For this location, there is one matching territory. Some ZIP codes 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
}

For more detail, see Baseline Regions / Tariff Territories.

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

Filter territories by their territory items with containsItemType and containsItemValue. Both parameters are required for this filter.

In this example, Duke Energy Carolinas operates in both North Carolina and South Carolina, but the request filters to 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

Retrieve one territory by territoryId.

Resource URI

GET /rest/public/territories/{territoryId}

Request parameters

The Get One Territory endpoint optionally supports the same standard pagination parameters and searching and sorting parameters used by list endpoints. In this case, those parameters apply to the territoryLses list returned when populateLses=true.

Along with authentication, the following parameters are available:

Name	Type	Description
populateItems	Boolean	When `true`, returns territory items for the territory. Defaults to `false`. Optional.
populateLses	Boolean	When `true`, returns LSEs that supply service in this market. Defaults to `false`. Optional.

Example 1 - Simple Case

This example retrieves a territory by 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 with deregulated suppliers. In this case, the request returns the first five suppliers, sometimes called Retail Energy Providers, for the 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
            }
        }
    ]
}