Explore the latest updates and features in our new Signal Product Documentation and Switch Product Documentation.
Please note, this site’s retirement date will be announced soon, so make sure to update your bookmarks.
Advanced Tariff Filtering
Advanced Tariff Filtering
Some markets, such as California, have a lot of tariffs to choose from. Customers in these markets should consider using their experience and expertise when faced with longer lists. We will cover some special use cases that require slightly more advanced filtering techniques.
Filtering Tariffs that have additional Eligibility Requirements
Some utilities require customers to switch to a different tariff when they move to solar or have tariffs only open to customers with an electric vehicle. Genability captures these additional eligibility criteria in the tariffs properties collection. More specifically, in properties with a propertyType of APPLICABILITY.
These are the three arguments you need to provide when using the Tariff endpoint in order to filter by eligibility:
populateProperties=true- makes sure the data needed to filter is consideredfilterByApplicability=true- applies a rule that results should also be filtered by applicability (i.e., additional eligibility properties).applicabilityFilters[solarPvEligible]=true- which is the specific applicability criteria to filter by
You can use this information to refine your list further.
GET /rest/public/tariffs?zipCode=94105&country=US&customerClasses=GENERAL&tariffTypes=DEFAULT,ALTERNATIVE&serviceTypes=ELECTRICITY&effectiveOn=2017-01-01&populateProperties=true&filterByApplicability=true&applicabilityFilters[solarPvEligible]=true
For an Electric Vehicle or EV case, you would supply the parameter hasElectricVehicle=true instead of solarPvEligible=true.
Filtering Tariffs based on Rate characteristics of the Tariff
Occasionally you might want to retrieve a list of tariffs that include rates with a specific characteristic, such as ones that vary by Time of Use. We support the following explicit parameters that you can filter on:
| Name | Type | Description |
| hasNetMetering | Boolean | Return tariffs that have or do not have any net-metered tariff rates (Optional) |
| hasTimeOfUseRates | Boolean | Return tariffs that have or do not have any time-of-use rates (Optional) |
| hasTieredRates | Boolean | Return tariffs that have or do not have any tiered rates (Optional) |
| hasContractedRates | Boolean | Return tariffs that have or do not have any contracted rates (Optional) |
Here is an example request for currently effective and open California C&I tariffs with a Direct Access component:
GET /rest/public/tariffs?zipCode=94105&country=US&customerClasses=GENERAL&tariffTypes=DEFAULT,ALTERNATIVE&serviceTypes=ELECTRICITY&effectiveOn=2020-10-01&hasContractedRates=true&fields=ext
The response will return a list of Direct Access tariffs where hasContractedRates is equal to true. We’ve also included the fields=ext parameter in this request because hasContractedRates is an extended field.
If you execute the same request, except this time adding populateProperties=true we will be able to explicitly see the Direct Access component:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
{
"status": "success",
"count": 54,
"type": "Tariff",
"results": [
{
"tariffId": 3372019,
"masterTariffId": 3154340,
"tariffCode": "A-1-DA",
"tariffName": "Small General - Direct Access",
"tariffBookName": "Small General - Direct Access",
"lseId": 734,
"lseName": "Pacific Gas & Electric Co",
"lseCode": "PGE",
"serviceType": "ELECTRICITY",
"priorTariffId": 3372019,
"tariffType": "ALTERNATIVE",
"customerClass": "GENERAL",
"privacy": "PUBLIC",
"customerCount": 1,
"customerLikelihood": 11.1100,
"customerCountSource": "FERC Form 1",
"territoryId": 807,
"effectiveDate": "2021-01-01",
"endDate": "2021-03-01",
"closedDate": null,
"effectiveOnRule": "TARIFF_EFFECTIVE_DATE",
"timeZone": "US/Pacific",
"billingPeriod": "MONTHLY",
"currency": "USD",
"chargeTypes": "FIXED_PRICE,CONSUMPTION_BASED,QUANTITY",
"chargePeriod": "DAILY",
"minMonthlyConsumption": null,
"maxMonthlyConsumption": 12500,
"minMonthlyDemand": null,
"maxMonthlyDemand": 75,
"hasTimeOfUseRates": false,
"hasTieredRates": false,
"hasContractedRates": true,
"hasTariffApplicability": true,
"hasRateApplicability": true,
"hasNetMetering": true,
"isActive": false,
"properties": [
{
"keyName": "isDirectAccessCustomer",
"quantityKey": null,
"displayName": "Direct Access Customer",
"family": "customerStatus",
"keyspace": "customer",
"description": "Direct Access (DA) Customers purchase energy from their non-utility provider and continue receiving delivery services their utility.",
"dataType": "BOOLEAN",
"propertyTypes": "APPLICABILITY",
"operator": "=",
"propertyValue": "true",
"isDefault": true
}
You can see from this snippet of the response returned that the property, keyName: isDirectAccessCustomer, has a propertyValue of true, meaning this indeed is a Direct Access customer!
You can learn more in our Tariffs API documentation.
Filtering out Tariffs that are closed to new enrollment
Sometimes utilities retire tariff rate plans. These retired tariff rate plans are flagged with the date they were closed on.
If you are presenting a list of tariffs that customers could change to, you’ll typically want to remove all closed tariffs. To accomplish this:
- pass in a date value to the
openOnproperty, which will usually be the same date used for theeffectiveOnproperty. - Don’t filter on this property if your use case is to select or choose the existing tariff a customer is on, as they might be grandfathered into a closed tariff.
Applying this information to a practical example results in the following request:
GET /rest/public/tariffs?zipCode=94105&country=US&customerClasses=RESIDENTIAL&tariffTypes=DEFAULT,ALTERNATIVE&serviceTypes=ELECTRICITY&effectiveOn=2021-01-01&openOn=2021-01-01
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
{
"status": "success",
"count": 67,
"type": "Tariff",
"results": [
{
"tariffId": 3369821,
"masterTariffId": 522,
"tariffCode": "E-1",
"tariffName": "Residential",
"lseId": 734,
"lseName": "Pacific Gas & Electric Co",
"priorTariffId": 3369821,
"tariffType": "DEFAULT",
"customerClass": "RESIDENTIAL",
"customerCount": 3321385,
"customerLikelihood": 55.3000,
"territoryId": 807,
"effectiveDate": "2021-01-01",
"endDate": "2021-03-01",
"timeZone": "US/Pacific",
"billingPeriod": "MONTHLY",
"currency": "USD",
"chargeTypes": "FIXED_PRICE,CONSUMPTION_BASED,MINIMUM",
"chargePeriod": "DAILY",
"hasTimeOfUseRates": false,
"hasTieredRates": true,
"hasContractedRates": false,
"hasRateApplicability": true,
"isActive": false
},
{
"tariffId": 3369822,
"masterTariffId": 3154331,
"tariffCode": "E-1-CARE",
"tariffName": "Residential - CARE",
"lseId": 734,
"lseName": "Pacific Gas & Electric Co",
"priorTariffId": 3369822,
"tariffType": "ALTERNATIVE",
"customerClass": "RESIDENTIAL",
"customerCount": 1213974,
"customerLikelihood": 20.2100,
"territoryId": 807,
"effectiveDate": "2021-01-01",
"endDate": "2021-03-01",
"timeZone": "US/Pacific",
"billingPeriod": "MONTHLY",
"currency": "USD",
"chargeTypes": "FIXED_PRICE,CONSUMPTION_BASED,MINIMUM",
"chargePeriod": "DAILY",
"hasTimeOfUseRates": false,
"hasTieredRates": true,
"hasContractedRates": false,
"hasRateApplicability": true,
"isActive": false
},
From analyzing all 67 tariffs that were returned, we learn a few things.
None of these tariffs have closedDate populated
This was our desired result, and we have successfully filtered out closed tariffs! closedDate is the date on which a tariff became closed to new customers, but still available for customers who were on it at the time. This can be null meaning that the tariff is not closed.
endDate is either not set or occurs after the effectiveDate we have specified
The endDate for each of the tariffs returned is either set to after 01/01/2021, or the endDate is null, meaning its end date is not yet known or ongoing until further notice.
Utility and Tariff data at your fingertips!
You can find more detailed information about each endpoint demonstrated in this tutorial on the API Reference guide. The reference guide will prove to be a useful resource when you need additional guidance. If there is another utility or particular tariff data you would like to retrieve but don’t see a method of doing so from this tutorial, check out our other tutorials and existing How-To guides.