It is important to use correct utility and tariff in cost calculations and savings analyses as costs can vary considerably between tariffs and utilities. This How-To explains how to select the correct utility and tariff rate plan for a given customer. It denotes the similarities and differences that are a result either from using Accounts for Account Cost Calculations and Savings Analyses, or from running On-Demand Cost Calculations.

About Utilities and Tariffs

We collect data for over 1,600 utilities across the US, Canada, Mexico, Australia, South Korea, United Kingdom, France and Netherlands. The utilities include investor-owned utilities, municipals, and cooperatives. Every utility has at least two tariff rate plans per class of customer, and often many more.

Since we maintain data on which utilities operate in which locations (using Territories that define utility service areas) and we track all the tariff rate plans that a utility has, including how many customers are on that plan and if it’s the default option or not, we can usually make a good guess as to the most likely utility and tariff for your customer. So let’s start there…

How we default the most likely Utility & Tariff on an Account

For Switch and Conduct customers, when you create a new Account, we will set the mostly likely utility and tariff for your customer. We do this based on the Account’s address and its customer class. For example, if you create an account for a residential customer in the 95462 zip code using the call below, we will automatically set the utility to Pacific Gas & Electric (who services the San Francisco Bay Area) and the Tariff to “E-1 Residential”, which is the most common tariff for homes. Most likely utility is based on the total number of customers that each possible utility serves, and most likely tariff is based on the number of customers on that particular tariff.

PUT /rest/v1/accounts
{
    "providerAccountId":"how-to-select-utility-01",
    "accountName": "How To Select the Right Utility",
    "address": {
        "addressString": "20480 Chapel Drive, Monte Rio, CA 95462"
    },
    "properties": {
        "customerClass": {
            "keyName":"customerClass",
            "dataValue":"1"
        }
    }
}

Here’s what you’ll get back:

{
    "status": "success",
    "count": 1,
    "type": "Account",
    "results": [
        {
            "accountId": "f6f7642c-fb71-42f8-a813-366ab1fb7ff1",
            "providerAccountId": "how-to-select-utility-01",
            "accountName": "How To Select the Right Utility",
            "customerOrgId": null,
            "customerOrgName": null,
            "address": {
                "addressString": "20480 Chapel Drive, Monte Rio, CA 95462",
                "address1": "20480 Chapel Dr",
                "city": "Monte Rio",
                "state": "CA",
                "zip": "95462",
                "country": "US",
                "lon": -123.011239,
                "lat": 38.469375
            },
            "status": "ACTIVE",
            "type": null,
            "accountManager": null,
            "assignee": null,
            "contacts": null,
            "properties": {
                "customerClass": {
                    "keyName": "customerClass",
                    "dataType": "CHOICE",
                    "dataValue": "1"
                },
                "lseId": {
                    "keyName": "lseId",
                    "displayName": "Pacific Gas & Electric Co",
                    "dataType": "INTEGER",
                    "dataValue": "734",
                    "accuracy": 56.85
                },
                "territoryId": {
                    "keyName": "territoryId",
                    "dataType": "INTEGER",
                    "dataValue": "3541",
                    "accuracy": 100
                }
            },
            "tariffs": [
                {
                    "masterTariffId": 522,
                    "tariffCode": "E-1",
                    "tariffName": "Residential",
                    "lseId": 734,
                    "lseName": "Pacific Gas & Electric Co",
                    "customerClass": null,
                    "customerLikelihood": 56.85,
                    "endDate": null,
                    "timeZone": "US/Pacific",
                    "billingPeriod": "MONTHLY",
                    "currency": "USD"
                }
            ],
            "projects": null
        }
    ]
}

You can tell from the response that we have defaulted to the most likely utility and tariff due to the "accuracy" value listed under "lseId" and the "customerLikelihood" listed under "tariffs". At this point you can start running Account Cost Calculations and Savings Analyses and we’ll use the most likely tariff. This is particularly useful for marketing situations where you don’t have a specific lead, or you don’t want to ask more detailed questions yet.

Sometimes a particular zip code is serviced by several different utilities, or sometimes we got the right utility but your customer is not on the most popular tariff. In these cases, there is still some work to be done in setting up the tariff on the account.

Choose the Correct Utility (LSE)

For many customers, their zip/postcode is only serviced by one utility (in the APIs we call a utility a “load serving entity” or “LSE” for short). However, our users are often surprised to find out that a large number of zip codes or postcodes are actually serviced by more than one utility. The most common reasons for this are:

  • They live close to the boundary of 2 or more utility service areas (which aren’t neatly defined by a postcode or zip code). This typically happens where a smaller municipal power company serves next to a larger Investor Owned Utility (IOU)
  • They live in a deregulated market such as Texas, or the UK, where they have a choice of which supplier to purchase from
  • Their area has a Community Choice Aggregation (CCA) program

For these customers residing in a territory with more than one utility, we’ll use the Load Serving Entities endpoint to pick the right one.

Search for Utilities via LSE endpoint

The easiest way to see what utilities are available for your customer is to search by address or zip code.

GET /rest/public/lses?zipCode=95462&country=US&residentialServiceTypes=ELECTRICITY

… or if using an address string …

GET /rest/public/lses?addressString=20480 Chapel Drive, Monte Rio, CA 95462&residentialServiceTypes=ELECTRICITY

One important thing to note is the residentialServiceTypes=ELECTRICITY parameter on the end of the URL. This parameter makes sure you only get back LSEs that serve power to residential customers. Otherwise, you would get back solar providers and other non-electricity LSEs in the database. You could also use the commercialServiceTypes and industrialServiceTypes parameters for commercial and industrial customers, respectively. We also recommend you pass in the country code parameter and your corresponding ISO Country Code.

The response should look like this:

{
    "status": "success",
    "count": 2,
    "type": "LoadServingEntity",
    "results": [
        {
            "lseId": 734,
            "name": "Pacific Gas & Electric Co",
            "code": "14328",
            "websiteHome": "http://www.pge.com/"
        },
        {
            "lseId": 100747,
            "name": "Sonoma Clean Power",
            "code": "59126",
            "websiteHome": "https://sonomacleanpower.org"
        }
    ],
    "pageCount": 25,
    "pageStart": 0
}

In our example here the customer has two electricity providers to choose from. Each LSE will have at least one service territory for each state where it provides coverage. If the expected utility does not appear for your customer’s address, please reach out to support@genability.com for our Support team to investigate.

Confirm the Right Utility on an Account

Once the correct Utility has been selected, Switch and Conduct customers should set it on the Account. Below is an example on how to confirm or change the LSE on their account (in this case changing it to the CCA “Sonoma Clean Power”). You use the lseId property in the results to set is via the Account Property API.

PUT /rest/v1/accounts/pid/how-to-select-utility-01/properties
{
    "keyName":"lseId",
    "dataValue":100747
}

When you update the LSE on the account, we will re-run the likely tariff logic to make sure we are still reporting the most likely tariff given we now know the utility. For example, if you changed the utility from Pacific Gas & Electric (PG&E) to Sonoma Clean Power (SCP), the tariff on the account will default from PG&E’s Residential tariff to SCP’s Residential tariff.

Now that you have selected the right utility, you’re ready to confirm or change your customer’s tariff.

Get the Available Tariffs for an Account

Switch and Conduct customers will use the Account Tariff endpoint to see what tariff rate plans are available for your Account. This endpoint uses the data that you’ve added to our account already in order to show only the tariffs that make sense. For example, if you had set up our account as a commercial account, the Account Tariff endpoint would only have commercial tariffs available.

To see what tariffs are available for an account:

GET /rest/v1/accounts/pid/{providerAccountId}/tariffs

The endpoint will return a list of applicable tariffs:

{
  "status": "success",
  "count": 23,
  "type": "Tariff",
  "results": [
    {
      "tariffId": 3232934,
      "masterTariffId": 3200682,
      "tariffCode": "RES-1",
      "tariffName": "Residential",
 
        /* more tariff data */
    }]
}

You can see that, given the data we’ve provided so far, there are 23 tariffs to choose from. That’s a lot of tariffs! There are a number of utilities in the US that have a large range of options. Most, however, only have 3 or 4 for residential customers. For commercial and industrial customers as well as the few utilities that do have lots of residential options, there are ways to further filter the list, which we will return back to later in this How to (link). For now we take advantage of the fact that most customers are on 1 or 2 tariffs, so by default the tariffs that are returned from the Tariff endpoint and Account Tariff endpoint are ordered by likelihood. That is, the tariffs that are most likely to be the correct tariff for your customer are at the top, and the tariffs that are least likely are at the bottom.

Once you have selected the correct tariff from the list, you can set the masterTariffId property on an account just like we did for lseId earlier. Let’s assume that our customer is on RES-1:

PUT /rest/v1/accounts/pid/how-to-select-utility-01/properties
{
    "keyName":"masterTariffId",
    "dataValue":"3200682"
}

Skip setting the Utility

Above we first confirmed the utility and then separately confirmed the tariff rate plan. However, you don’t actually need to confirm the utility. When a utility is not yet set on the account, the Account Tariff endpoint will return all the tariffs for all the utilities for the account’s customer class and location. If you so wish, you can take advantage of this to streamline your UI or API calls. Also, when you confirm a tariff rate plan, the account’s utility will be confirmed too.

Search for Tariffs via Tariff endpoint

For Signal customers or when running On-demand Cost Calculations (i.e. cases that do not require an Account), you will use the Tariffs endpoint to search for a set of tariffs.

To retrieve a list of tariffs suitable for picking the sites current tariff, you will include the following parameters:

  • zipCode and country, or alternatively addressString, to filter to just tariffs available for your customers address
  • customerClasses, where you will state RESIDENTIAL for residential/domestic, and usually GENERAL for commercial and industrial. A third option is SPECIAL_USE for agriculture or other specialty tariffs
  • tariffType of DEFAULT,ALTERNATIVE which will exclude riders, but include all the tariffs that customers can enroll on
  • serviceTypes (ELECTRICITY or SOLAR_PV) so you only get back tariffs for a specific service
  • effectiveOn is important. Setting this makes sure only the version of the tariff for the specified date is retrieved. Use the start of the billing range.
  • lseId (if known) so only tariffs of a specific utility (LSE) are retrieved
  • sortOn and sortOrder to sort by the most likely tariff

Here’s a common example where you retrieve the currently active residential electricity tariffs for a given utility and location, ordered by the most to the least likely. Note this is the equivalent call to the Account Tariff endpoint we demonstrated above:

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

Visit our documentation on how to Get a List of Tariffs and how to use the Searching and Sorting parameters.

Further Refining the List of Tariffs

Most of the time for residential cases, the above gets you a list of tariffs that is suitable. However, this section shows you some of the more advanced ways you can further refine the list of tariffs. These can be especially useful for C&I customers.

Searching for 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. Utilities are most consistent 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 between the utility’s tariff documents and bills.

For example, if a customer’s PG&E bill has a tariff code of “E-20”, you can search for the tariff by using the search and searchOn parameters:

GET /rest/public/tariffs?search=E-20&searchOn=tariffCode&zipCode=94105&country=US&customerClasses=GENERAL&tariffTypes=DEFAULT,ALTERNATIVE&serviceTypes=ELECTRICITY&effectiveOn=2017-10-01&sortOn=customerLikelihood,tariffType&sortOrder=DESC,ASC

The response will return a list of PG&E tariffs that have “E-20” in the tariffCode.

You can learn more in our documentations on how to Get a List of Tariffs and how to use the Searching and Sorting parameters.

Filtering Tariffs that have Consumption or Demand Limits

C&I tariffs can sometimes have consumption and demand limits. We include information on the consumption and demand limits in each tariff as a tariff property. When you are filtering for tariffs by the consumption and demand limits, you will use the populateProperties=true and the consumption and demand querystring parameters.

Here is a sample request for eligible tariffs for a customer with a monthly demand of 550 kW:

GET /rest/public/tariffs?zipCode=94105&country=US&customerClasses=GENERAL&tariffTypes=DEFAULT,ALTERNATIVE&serviceTypes=ELECTRICITY&effectiveOn=2017-10-01&demand=550

The response will only return tariffs that are eligible for customers with 550 kW demand. Note that the returned data includes information on each tariff’s demand limits, via the properties section. Here is a snippet from PG&E’s E-19-TOU, which shows the property is for demand and that its an APPLICABILITY property type, and it’s minimum demand is 500 kW and it’s maximum demand is 1000 kW:

/* edited for length */
        {
          "keyName": "demand",
          "quantityKey": null,
          "displayName": "Demand (kW)",
          "family": "load",
          "keyspace": "electricity",
          "description": "Quantity in kW of load that is used for a given period",
          "dataType": "DEMAND",
          "propertyTypes": "APPLICABILITY",
          "operator": "between",
          "propertyValue": "500,1000",
          "minValue": 500,
          "maxValue": 1000,
          "isDefault": true
        },
/* edited for length */

You can learn more about the consumption and demand parameters in our documentation on how to Get a List of Tariffs.

Filtering out Tariffs that are closed to new enrollment

Sometimes utilities retire tariff rate plans. We flag these with the date they were closed on. If you are presenting a list of tariffs the customer could change to, you’ll typically want to remove all closed tariffs. To do this pass in a date value in the openOn property, which will usually be the same date as you used for the effectiveOn property. Don’t filter on this property if your use case is to select or choose the existing tariff a custom is on, as they might be grandfathered into a closed tariff.

GET /rest/public/tariffs?zipCode=94105&country=US&customerClasses=RESIDENTIAL&tariffTypes=DEFAULT,ALTERNATIVE&serviceTypes=ELECTRICITY&effectiveOn=2017-10-01&openOn=2017-10-01

Filtering Tariffs based on Rate characteristics of the Tariff

Occationally you might want to present or 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 use to filter on:

Name Type Description
hasNetMetering Boolean Return tariffs which have or do not have any net metered tariff rates (Optional)
hasTimeOfUseRates Boolean Return tariffs which have or do not have any time-of-use rates (Optional)
hasTieredRates Boolean Return tariffs which have or do not have any tiered rates (Optional)
hasContractedRates Boolean Return tariffs which 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=2017-10-01&hasContractedRates=true&fields=ext

The response will return a list of Direct Access tariffs where "hasContractedRates": true. We’ve also included the fields=ext parameter in this request because "hasContractedRates": true is an extended field.

You can learn more in our Tariffs API documentation.

Filtering Tariffs that have additional Eligibility Requirements

Some utilities require customers to switch to a different tariff when they go solar, or have tariffs only open to customers with an electric vehicle, for instance. Genability captures this additional eligibility criteria in the tariffs properties collection. More specifically in properties with a propertyType of APPLICABILITY. You can use this to refine your list further.

For example, California NEM 2.0 require solar customers to move to a time of use tariff. To determine which tariffs you should make available as post-solar tariffs, we have flagged tariffs that are eligible for solar with an APPLICABILITY property with the keyName of solarPvEligible and a value set to true. If you would like to learn about data-driven ways to filter based on additional tariff applicability criteria, contact support@genability.com for details.