Territory

Overview

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.
  • 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 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

Operations

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
addressString String Filters by the specified address. For example, 221 Main St, San Francisco, CA 92704
address String Alias for addressString
lat Decimal Latitude. Use in conjunction with lng. Filters the result to include only territories that contain the coordinates.
lng Decimal Longitude. Use in conjunction with lat. Filters the result to include only territories that contain the specified coordinates.
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 Filters the result set to only include territories of the specified usageType. Possible values are: "SERVICE", "TARIFF". (Optional)
populateLses Boolean If true, this returns a list of territory LSEs which are all the LSEs providing service in this territory. (Optional)

Example

GET /rest/public/territories?lseId=734&populateItems=false
{
   "status":"success",
   "count":11,
   "type":"Territory",
   "results":[
      {
         "territoryId":807,
         "lseId":734,
         "lseName":"Pacific Gas & Electric Co",
         "parentTerritoryId":null,
         "territoryName":"Service area for CA",
         "usageType":"SERVICE",
         "itemTypes":"COUNTY",
         "items":null,
         "deregRes":false,
         "deregCandi":false
      },

      /* edited for length */

      {
         "territoryId":3535,
         "lseId":734,
         "lseName":"Pacific Gas & Electric Co",
         "parentTerritoryId":807,
         "territoryName":"Baseline Region Q",
         "usageType":"TARIFF",
         "itemTypes":"ZIPCODE",
         "items":null,
         "deregRes":false,
         "deregCandi":false
      },
   ]
}

The Price and Calculate methods will sometimes require a territory ID. This is required when the LSE offers different rates based on where the consumer resides. This is common in California. If you know the consumer's ZIP code, the LSE ID and master tariff ID, you can get the territory ID using the following call:

GET /rest/public/territories?lseId=734&masterTariffId=522&zipCode=94115

This results in:

{
    "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.307749678160924,
            "longitude": -122.13079052298848
        }
    }],
    "pageCount": 25,
    "pageStart": 0
}

Get One Territory

This allows you to retrieve one territory.

Resource URI

GET /rest/public/territories/{territoryId}

Request Parameters

Along with the required security parameters, the following parameter 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

GET /rest/public/territories/3539
{
    "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.68747233333334,
            "longitude": -124.05964887500001
        }
    }]
}

History

  • 3/10/2015 - Formatting update
  • 11/07/2013 - Capitalized enums for usageType
  • 2/21/2013 - Corrected error on populageLses param
  • 12/14/2012 - Added field view definitions
  • Initial Release - 4/22/2011 - Territories