HomeGuidesAPI ReferenceChangelog
Log In
Guides
Start typing to search…

When the List of Tariffs is Longer

Learn advanced methods to refine and filter longer lists of tariffs returned by the API using sorting parameters and tariff code searches.

When the list of tariffs is longer

Most of the time for residential cases, the basic methods allow you to retrieve a manageable list of tariffs. However, this section demonstrates more advanced techniques to further refine the tariff lists 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 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. Generally, it's a good practice to sort by the customerLikelihood field, which ensures that the most relevant customers for your use case appear at the top of the results list. However, this may not always align with your specific needs.

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.

Using the 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:

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

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

Sending this request returns the following response:

{  
    "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 successfully filtered the response down to our desired result! The filtering methods we've examined so far apply to all customer classes: residential, general, and special use. However, some filters are more applicable to the general customer class.

Updated 13 days ago

What’s Next