Attention Developers: Our Documentation Is Moving!
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.

Which When the list of tariffs is longer

When the list of tariffs is longer

Most of the time, for residential cases, the above methods allow you to get a list of tariffs that is not too long to parse through. However, this section shows you some of the more advanced ways you can further refine the list of tariffs returned by our API.

GET /rest/public/tariffs?zipCode=28201&country=US&customerClasses=RESIDENTIAL&tariffTypes=DEFAULT,ALTERNATIVE&serviceTypes=ELECTRICITY&effectiveOn=2017-10-01&sortOn=customerLikelihood,tariffType&sortOrder=DESC,ASC&fields=ext

This request returns a somewhat longer response, consisting of 8 tariffs:

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
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217

{
    "status": "success",
    "count": 8,
    "type": "Tariff",
    "results": [
        {
            "tariffId": 3271771,
            "masterTariffId": 302,
            "tariffCode": "RS (NC)",
            "tariffName": "Residential",
            "lseId": 2416,
            "lseName": "Duke Energy Carolinas, LLC",
            "priorTariffId": 3271771,
            "tariffType": "DEFAULT",
            "customerClass": "RESIDENTIAL",
            "customerCount": 1280949,
            "customerLikelihood": 80.7000,
            "territoryId": 2711,
            "effectiveDate": "2017-01-01",
            "endDate": "2018-08-01",
            "timeZone": "US/Eastern",
            "billingPeriod": "MONTHLY",
            "currency": "USD",
            "chargeTypes": "FIXED_PRICE,CONSUMPTION_BASED,MINIMUM",
            "chargePeriod": "MONTHLY",
            "hasTimeOfUseRates": false,
            "hasTieredRates": false,
            "hasContractedRates": false,
            "hasRateApplicability": false,
            "isActive": false
        },
        {
            "tariffId": 3271764,
            "masterTariffId": 305,
            "tariffCode": "ES (NC)",
            "tariffName": "Residential - Energy Star, Electric Heat",
            "lseId": 2416,
            "lseName": "Duke Energy Carolinas, LLC",
            "priorTariffId": 3271764,
            "tariffType": "ALTERNATIVE",
            "customerClass": "RESIDENTIAL",
            "customerCount": 119047,
            "customerLikelihood": 7.5000,
            "territoryId": 2711,
            "effectiveDate": "2017-01-01",
            "endDate": "2018-08-01",
            "timeZone": "US/Eastern",
            "billingPeriod": "MONTHLY",
            "currency": "USD",
            "chargeTypes": "FIXED_PRICE,CONSUMPTION_BASED,MINIMUM",
            "chargePeriod": "MONTHLY",
            "hasTimeOfUseRates": false,
            "hasTieredRates": true,
            "hasContractedRates": false,
            "hasRateApplicability": false,
            "isActive": false
        },
        {
            "tariffId": 3271772,
            "masterTariffId": 303,
            "tariffCode": "RE (NC)",
            "tariffName": "Residential - Water Heating, Electric Heat",
            "lseId": 2416,
            "lseName": "Duke Energy Carolinas, LLC",
            "priorTariffId": 3271772,
            "tariffType": "ALTERNATIVE",
            "customerClass": "RESIDENTIAL",
            "customerCount": 119047,
            "customerLikelihood": 7.5000,
            "territoryId": 2711,
            "effectiveDate": "2017-01-01",
            "endDate": "2018-08-01",
            "timeZone": "US/Eastern",
            "billingPeriod": "MONTHLY",
            "currency": "USD",
            "chargeTypes": "FIXED_PRICE,CONSUMPTION_BASED,MINIMUM",
            "chargePeriod": "MONTHLY",
            "hasTimeOfUseRates": false,
            "hasTieredRates": true,
            "hasContractedRates": false,
            "hasRateApplicability": false,
            "isActive": false
        },
        {
            "tariffId": 3239073,
            "masterTariffId": 3219364,
            "tariffCode": "RST (NC)",
            "tariffName": "Residential - Time of Use, Pilot",
            "lseId": 2416,
            "lseName": "Duke Energy Carolinas, LLC",
            "priorTariffId": 3237008,
            "tariffType": "ALTERNATIVE",
            "customerClass": "RESIDENTIAL",
            "customerCount": 21163,
            "customerLikelihood": 1.3300,
            "territoryId": 2711,
            "effectiveDate": "2015-09-25",
            "endDate": null,
            "timeZone": "US/Eastern",
            "billingPeriod": "MONTHLY",
            "currency": "USD",
            "chargeTypes": "FIXED_PRICE,CONSUMPTION_BASED,DEMAND_BASED,MINIMUM",
            "chargePeriod": "MONTHLY",
            "hasTimeOfUseRates": true,
            "hasTieredRates": false,
            "hasContractedRates": false,
            "hasRateApplicability": false,
            "isActive": true
        },
        {
            "tariffId": 3271767,
            "masterTariffId": 306,
            "tariffCode": "RT (NC)",
            "tariffName": "Residential - Time of Use",
            "lseId": 2416,
            "lseName": "Duke Energy Carolinas, LLC",
            "priorTariffId": 3271767,
            "tariffType": "ALTERNATIVE",
            "customerClass": "RESIDENTIAL",
            "customerCount": 21163,
            "customerLikelihood": 1.3300,
            "territoryId": 2711,
            "effectiveDate": "2017-01-01",
            "endDate": "2018-08-01",
            "timeZone": "US/Eastern",
            "billingPeriod": "MONTHLY",
            "currency": "USD",
            "chargeTypes": "FIXED_PRICE,CONSUMPTION_BASED,DEMAND_BASED,MINIMUM",
            "chargePeriod": "MONTHLY",
            "hasTimeOfUseRates": true,
            "hasTieredRates": false,
            "hasContractedRates": false,
            "hasRateApplicability": false,
            "isActive": false
        },
        {
            "tariffId": 3239075,
            "masterTariffId": 3219362,
            "tariffCode": "RET (NC)",
            "tariffName": "Residential - All-Electric, Time of Use, Pilot",
            "lseId": 2416,
            "lseName": "Duke Energy Carolinas, LLC",
            "priorTariffId": 3237006,
            "tariffType": "ALTERNATIVE",
            "customerClass": "RESIDENTIAL",
            "customerCount": 21163,
            "customerLikelihood": 1.3300,
            "territoryId": 2711,
            "effectiveDate": "2015-09-25",
            "endDate": null,
            "timeZone": "US/Eastern",
            "billingPeriod": "MONTHLY",
            "currency": "USD",
            "chargeTypes": "FIXED_PRICE,CONSUMPTION_BASED,DEMAND_BASED,MINIMUM",
            "chargePeriod": "MONTHLY",
            "hasTimeOfUseRates": true,
            "hasTieredRates": false,
            "hasContractedRates": false,
            "hasRateApplicability": false,
            "isActive": true
        },
        {
            "tariffId": 3273615,
            "masterTariffId": 3219363,
            "tariffCode": "WC (NC)",
            "tariffName": "Residential - Water Heating, Controlled/Sub-metered",
            "lseId": 2416,
            "lseName": "Duke Energy Carolinas, LLC",
            "priorTariffId": 3246651,
            "tariffType": "ALTERNATIVE",
            "customerClass": "RESIDENTIAL",
            "customerCount": 2381,
            "customerLikelihood": 0.1500,
            "territoryId": 2711,
            "effectiveDate": "2017-01-01",
            "endDate": null,
            "timeZone": "US/Eastern",
            "billingPeriod": "MONTHLY",
            "currency": "USD",
            "chargeTypes": "FIXED_PRICE,CONSUMPTION_BASED",
            "chargePeriod": "MONTHLY",
            "hasTimeOfUseRates": false,
            "hasTieredRates": false,
            "hasContractedRates": false,
            "hasRateApplicability": false,
            "isActive": true
        },
        {
            "tariffId": 3271770,
            "masterTariffId": 304,
            "tariffCode": "ES (NC)",
            "tariffName": "Residential - Energy Star",
            "lseId": 2416,
            "lseName": "Duke Energy Carolinas, LLC",
            "priorTariffId": 3271770,
            "tariffType": "ALTERNATIVE",
            "customerClass": "RESIDENTIAL",
            "customerCount": 2381,
            "customerLikelihood": 0.1500,
            "territoryId": 2711,
            "effectiveDate": "2017-01-01",
            "endDate": "2018-08-01",
            "timeZone": "US/Eastern",
            "billingPeriod": "MONTHLY",
            "currency": "USD",
            "chargeTypes": "FIXED_PRICE,CONSUMPTION_BASED,MINIMUM",
            "chargePeriod": "MONTHLY",
            "hasTimeOfUseRates": false,
            "hasTieredRates": true,
            "hasContractedRates": false,
            "hasRateApplicability": false,
            "isActive": false
        }
    ],
    "pageCount": 25,
    "pageStart": 0
}

Pay attention to the sorting methods we have applied to this request. Generally speaking, it is a good idea to sort on the customerLikelihood field, as this means the customers most relevant to you will appear at the top of the results list. However, this may not be what you want.

Sorting is handled by two fields:

  • sortOn - Comma separated list of fields to sort on. You can sort by multiple values. This can also be input via Array Inputs.
  • sortOrder - Comma separated list of ordering values. Possible values are ASC and DESC.
    • The default is ASC.
    • If your sortOn contains multiple fields and you would like to order fields individually, you can pass in a comma-separated list or use Array Inputs.
    • For example, if your sortOn parameter contained five fields, and your sortOrder argument contained ASC, DESC, DESC, these would be applied to the first three items in the sortOn field. The remaining two would default to ASC.

Using the Tariff Code from the Bill or Statement

A useful method to help select the right tariff is to match the code that is on the customer’s bill to the tariffCode or tariffName returned from our APIs. The tariffCode is the code that an LSE uses as an alternate name for the tariff. Utilities are more likely to match with the tariff code between their tariff documents and bills. We capture the tariff name to be descriptive, but the tariff name is more likely to be different than what is captured on a tariff’s document and bills.

If a customer’s bill has a tariff code, you can search for the tariff by using the search and searchOn parameters:

  • search - The string of text to search on. This can also be a regular expression, in which case you should set the isRegex flag to true.
  • searchOn - Comma separated list of fields to query on. When searchOn is specified, the text provided in the search string field will be searched within these fields. The list of fields to search on depends on the entity being searched for.

A full list of sorting parameters can be found on the Searching and Sorting section of our API reference guide.

Applying the search and searchOn parameters to this practical example results in the following residential request:

GET /rest/public/tariffs?search=RS%20(NC)&searchOn=tariffCode&zipCode=28201&country=US&customerClasses=RESIDENTIAL&tariffTypes=DEFAULT,ALTERNATIVE&serviceTypes=ELECTRICITY&effectiveOn=2017-10-01&sortOn=customerLikelihood,tariffType&sortOrder=DESC,ASC&fields=ext

We want to search for the request code string “RS (NC),” and we accomplish this with the two parameters:

  1. search=RS%20(NC)
  2. searchOn=tariffCode

Note that we replaced the space character in “RS (NC)” with “%20”.

Sending this request returns the following response:

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

{
    "status": "success",
    "count": 1,
    "type": "Tariff",
    "results": [
        {
            "tariffId": 3271771,
            "masterTariffId": 302,
            "tariffCode": "RS (NC)",
            "tariffName": "Residential",
            "tariffBookName": "Residential",
            "lseId": 2416,
            "lseName": "Duke Energy Carolinas, LLC",
            "lseCode": "DUKE",
            "serviceType": "ELECTRICITY",
            "priorTariffId": 3271771,
            "tariffType": "DEFAULT",
            "customerClass": "RESIDENTIAL",
            "privacy": "PUBLIC",
            "customerCount": 1280949,
            "customerLikelihood": 100.0000,
            "customerCountSource": "Genability Estimate",
            "territoryId": 2711,
            "effectiveDate": "2017-01-01",
            "endDate": "2018-08-01",
            "closedDate": null,
            "effectiveOnRule": "TARIFF_EFFECTIVE_DATE",
            "timeZone": "US/Eastern",
            "billingPeriod": "MONTHLY",
            "currency": "USD",
            "chargeTypes": "FIXED_PRICE,CONSUMPTION_BASED,MINIMUM",
            "chargePeriod": "MONTHLY",
            "minMonthlyConsumption": null,
            "maxMonthlyConsumption": null,
            "minMonthlyDemand": null,
            "maxMonthlyDemand": null,
            "hasTimeOfUseRates": false,
            "hasTieredRates": false,
            "hasContractedRates": false,
            "hasTariffApplicability": false,
            "hasRateApplicability": false,
            "hasNetMetering": true,
            "isActive": false
        }
    ],
    "pageCount": 25,
    "pageStart": 0
}

By using the tariff code, we were successfully able to filter the response down to our desired result! The filtering methods we have looked at so far apply to all customer classes, residential, general, and special use. However there are some filters that are more applicable to the general customer class.

Previous: Step 2 - Determine Eligible Tariffs

Next: Step 4 - Searching for a General Tariff