HomeGuidesAPI ReferenceChangelog
Log In
Guides

When the List of Tariffs is Longer

Suggest Edits

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:

{  
    "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 if 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 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 depends on the entity being searched for.

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

Applying the search and searchOnparameters to this practical example result 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:

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

Updated 4 months ago