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
- Retrieve account tariffs with
populateProperties=true. - Check whether the tariff has a
territoryIdproperty withpropertyTypesofRATE_CRITERIA. - Retrieve territory options with
usageType=TARIFF. - Compare the defaulted
territoryIdagainst the customer’s bill or selected region. - Update the account’s
territoryIdif the default is wrong.
Check whether a tariff has baseline regions
Each tariff in our database includes a list of tariff properties, which can be found in the properties list in the JSON. You can ask for these properties to be returned in the results of the Account Tariffs API endpoint by including populateProperties=true in your request. If you find a territoryId property in the returned list with propertyTypes of RATE_CRITERIA, at least one rate on the tariff varies according to the customer’s location within the utility's service area. It has a baseline region.
GET /rest/v1/accounts/{accountId}/tariffs?populateProperties=true
GET /rest/v1/accounts/pid/{providerAccountId}/tariffs?populateProperties=trueMost account endpoints support both Arcadia-generated accountId paths and your providerAccountId paths. The remaining examples use providerAccountId for readability.
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
You can retrieve a list of territories for a customer by using the Territories API. Use this example to retrieve territories for Southern California Edison (lseId: 1228) with the zip code 92407. We are asking for only the baseline region territories by including the request parameter usageType with a value of TARIFF. Tariff types denote baseline regions, as opposed to service areas, utility climate zones, and other types of territories.
Use this template to retrieve baseline-region territory options:
GET /rest/public/territories?lseId={lseId}&zipCode={zipCode}&country={country}&usageType=TARIFF| Parameter | Required | Description |
|---|---|---|
lseId | Yes | Utility or LSE ID. |
zipCode | Yes | Customer ZIP code used to find matching territory options. |
country | Recommended | ISO country code. |
usageType | Yes | Use TARIFF to return baseline-region territories. |
For example:
GET /rest/public/territories?lseId=1228&zipCode=92407&country=US&usageType=TARIFFThe 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
}
},
In the case above, two territories are returned. If you have a bill for your customer, you can often find the baseline region denoted on it.
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}/tariffsHere 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
territoryIdrate 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.
If you would like to update the territory for a customer who resides in San Bernardino, CA 92407 from Baseline Region 10 (territoryId: 5) to Baseline Region 16 (territoryId: 9), update the territoryId under the Account 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:
Updated 5 days ago