When the List of Tariffs is Longer

Use sorting and tariff-code search when a basic tariff request returns more options than you can confidently choose from.

Refine residential tariff results

Most of the time for residential cases, the basic methods return a manageable list of tariffs. When the API returns a longer list, use sorting and tariff code searches to narrow the results.

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 longer response consisting of 8 tariffs:

{  
    "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  
}

Notice the sorting methods applied to this request. In general, sort by customerLikelihood so the most relevant tariffs appear at the top of the results list. This may not always match your specific needs, so you can adjust the sort parameters.

Sorting is controlled by two parameters:

sortOn - A comma-separated list of fields to sort by. You can sort by multiple values. This parameter also accepts Array Inputs.
sortOrder - A comma-separated list of ordering values. Possible values are ASC and DESC.
- The default value is ASC.
- If your sortOn parameter contains multiple fields and you want to order each field individually, you can provide a comma-separated list or use Array Inputs.
- For example, if your sortOn parameter contains five fields and your sortOrder parameter contains ASC, DESC, DESC, these values will be applied to the first three fields in the sortOn parameter. The remaining two fields will default to ASC.

Search by tariff code from the bill or statement

A useful method for selecting the correct tariff is to match the code on the customer's bill with the tariffCode or tariffName returned by our APIs. The tariffCode represents the code that a Load Serving Entity (LSE) uses as an alternate name for the tariff. Utilities are more likely to use consistent tariff codes between their tariff documents and bills. We capture the tariff name to be descriptive, but the tariff name is more likely to differ from what appears on tariff documents and bills.

If a customer's bill includes a tariff code, you can search for the tariff using the search and searchOn parameters:

search - The text string to search for. This can also be a regular expression if you set the isRegex flag to true.
searchOn - A comma-separated list of fields to search within. When searchOn is specified, the text provided in the search field will be searched within these specified fields. The available fields depend on the entity being searched.

For a complete list of sorting parameters, refer to 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

To search for the tariff code "RS (NC)," we use these two parameters:

search=RS%20(NC)
searchOn=tariffCode

Note that we replaced the space character in "RS (NC)" with "%20" for URL encoding.

Sending this request returns one matching tariff:

{  
    "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 filtered the response down to the desired result. These filtering methods apply to all customer classes: residential, general, and special use. Some filters are more applicable to the general customer class.

Next steps

Searching for a General Tariff

Filter tariffs for commercial and industrial electricity users by consumption and demand size.

Advanced Tariff Filtering

Filter by eligibility requirements, rate characteristics, and enrollment availability.