HomeGuidesAPI ReferenceChangelog
Log In
Guides

Handle Baseline Regions

Identify tariffs with baseline regions, retrieve territory options, and update the defaulted territory on an account when needed.

Identify tariffs with baseline regions, retrieve territory options, and update the defaulted territory on an account when needed.

A baseline region is a utility-defined territory used by some tariffs to select location-specific rates or tier allowances. For example, customers in different climate regions may have different usage tier thresholds.

Baseline region workflow

  1. Retrieve account tariffs with populateProperties=true.
  2. Check whether the tariff has a territoryId property with propertyTypes of RATE_CRITERIA.
  3. Retrieve territory options with usageType=TARIFF.
  4. Compare the defaulted territoryId against the customer’s bill or selected region.
  5. Update the account’s territoryId if the default is wrong.

Check whether a tariff has baseline regions

Include populateProperties=true in your Account Tariffs request to retrieve tariff properties in the JSON properties list. Check for territoryId with propertyTypes of RATE_CRITERIA. This indicates a baseline region: at least 1 rate varies by the customer’s location within the utility’s service area.

GET /rest/v1/accounts/{accountId}/tariffs?populateProperties=true
GET /rest/v1/accounts/pid/{providerAccountId}/tariffs?populateProperties=true

Most account endpoints support both Arcadia-generated accountId paths and your providerAccountId paths. The remaining examples use providerAccountId for readability.

circle-info

You can learn more about other Rate Criteria types in Improving Calculation Accuracy with Rate Criteria Properties.

When the tariff includes this property, you can explicitly pass a territoryId to the calculator or let the calculator default it. If you are using Switch, a territoryId will be defaulted on the account, and you can override it if needed.

Retrieve available territories for a customer

Use the Territories API to retrieve territory options for a customer. This example retrieves territories for Southern California Edison (lseId of 1228) in ZIP code 92407. Set usageType to TARIFF to return only baseline regions, rather than service areas, utility climate zones, or other territory types.

Use this template to retrieve baseline-region territory options:

GET /rest/public/territories?lseId={lseId}&zipCode={zipCode}&country={country}&usageType=TARIFF
ParameterRequiredDescription
lseIdYesUtility or LSE ID.
zipCodeYesCustomer ZIP code used to find matching territory options.
countryRecommendedISO country code.
usageTypeYesUse TARIFF to return baseline-region territories.

For example:

GET /rest/public/territories?lseId=1228&zipCode=92407&country=US&usageType=TARIFF

The response returns Baseline Region 10 (territoryId: 5) and Baseline Region 16 (territoryId: 9). This response snippet has been shortened to show the matching territory records:

        {  
            "territoryId": 5,  
            "territoryName": "Baseline Region 10",  
            "lseId": 1228,  
            "lseName": "Southern California Edison Co",  
            "parentTerritoryId": 1362,  
            "usageType": "TARIFF",  
            "itemTypes": "CITY",  
            "deregRes": false,  
            "deregCandi": false,  
            "centerPoint": {  
                "latitude": 33.93300848031497,  
                "longitude": -117.3344177637795  
            }  
        },  
        {  
            "territoryId": 9,  
            "territoryName": "Baseline Region 16",  
            "lseId": 1228,  
            "lseName": "Southern California Edison Co",  
            "parentTerritoryId": 1362,  
            "usageType": "TARIFF",  
            "itemTypes": "CITY",  
            "deregRes": false,  
            "deregCandi": false,  
            "centerPoint": {  
                "latitude": 34.71016330481286,  
                "longitude": -117.95372556684482  
            }  
        },  

Compare the 2 returned territories with the baseline region shown on the customer’s bill, if available.

Check which territory was defaulted

When a calculation requires a territory to select the correct subset of rates, a default territory is picked. The territoryId used is returned in the assumptions of the calculation. If the territoryId assumption has an accuracy below 100, Switch selected a default rather than using a confirmed account value.

The account property is the value saved on the account. The calculation assumption is the value used in a specific calculation. If you update the account property, future calculations use that saved value unless you override it in the calculation request.

The territoryId set on the account is returned in the response when you retrieve a list of the Account Tariffs. Use this request to retrieve a list of an account’s available tariff rate plans:

GET /rest/v1/accounts/pid/{providerAccountId}/tariffs

Here is an example of the response where the territoryId has a propertyValue of "5", which represents Baseline Region 10. This response snippet has been shortened to show the territoryId property:

{  
                    "keyName": "territoryId",  
                    "quantityKey": null,  
                    "displayName": "Territory",  
                    "family": "billing",  
                    "keyspace": "electricity",  
                    "description": "Territory where tariff is operational",  
                    "dataType": "CHOICE",  
                    "propertyTypes": "RATE_CRITERIA",  
                    "operator": null,  
                    "propertyValue": "5",  
                    "choices": [  
                        {  
                            "displayValue": "Baseline Region 10",  
                            "value": "5",  
                            "dataValue": "5",  
                            "likelihood": null  
                        },  
                        {  
                            "displayValue": "Baseline Region 13",  
                            "value": "6",  
                            "dataValue": "6",  
                            "likelihood": null  
                        },  
                        {  
                            "displayValue": "Baseline Region 14",  
                            "value": "7",  
                            "dataValue": "7",  
                            "likelihood": null  
                        },  
                        {  
                            "displayValue": "Baseline Region 15",  
                            "value": "8",  
                            "dataValue": "8",  
                            "likelihood": null  
                        },  
                        {  
                            "displayValue": "Baseline Region 16",  
                            "value": "9",  
                            "dataValue": "9",  
                            "likelihood": null  
                        },  
                        {  
                            "displayValue": "Baseline Region 5",  
                            "value": "1",  
                            "dataValue": "1",  
                            "likelihood": null  
                        },  
                        {  
                            "displayValue": "Baseline Region 6",  
                            "value": "2",  
                            "dataValue": "2",  
                            "likelihood": null  
                        },  
                        {  
                            "displayValue": "Baseline Region 8",  
                            "value": "3",  
                            "dataValue": "3",  
                            "likelihood": null  
                        },  
                        {  
                            "displayValue": "Baseline Region 9",  
                            "value": "4",  
                            "dataValue": "4",  
                            "likelihood": null  
                        }  
                    ],  
                    "isDefault": true  
                }  

In this example, the territory for a customer who resides in San Bernardino, CA 92407 was defaulted to SCE’s Baseline Region 10 (territoryId: 5).

Change the defaulted territory

For CA ZIP codes that have multiple baseline regions, you can either have a separate drop-down to select the right territory or you can stick with the default.

You do not need to override territoryId if:

  • The tariff does not have a territoryId rate criteria property.
  • The customer’s bill matches the defaulted baseline region.
  • Your workflow does not collect baseline region information and you accept the default.

Override the defaulted territory when:

  • The customer’s bill shows a different baseline region.
  • The customer selected a different region in your UI.
  • Your address-to-territory lookup returns a more specific match than the default.

To change the San Bernardino customer’s territory from Baseline Region 10 (territoryId of 5) to Baseline Region 16 (territoryId of 9), update the account’s territoryId property:

PUT /rest/v1/accounts/pid/{providerAccountId}/properties
{  
    "keyName":"territoryId",  
    "dataValue":"9"  
}  

Read Update an Account Property for more information.

Next steps

After confirming the baseline region, you can:


Did this page help you?