It is important that the correct utility and tariff are used 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 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,400 utilities across the US, UK, and Australia. The utilities include investor-owned utilities, municipals, and cooperatives. Every utility has multiple tariff rate plans.

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

When you create a new account, we will determine the mostly likely utility and tariff for your customer based on the Account’s address and the customer class. We can do this from as little as a zip code or postcode and a country code, as well as the 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.

PUT /rest/v1/accounts
{
    "providerAccountId":"{providerAccountId}",
    "accountName": "{accountName}",
    "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": "{accountId}",
      "providerAccountId": "{providerAccountId}",
      "accountName": "{accountName}",
      "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": 57.35
        },
        "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": 57.35,
          "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, there is only one utility (in the APIs we call this a “load serving entity” or “LSE”) that provides power in their area. 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 Entity 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?addressString=20480 Chapel Drive, Monte Rio, CA 95462&residentialServiceTypes=ELECTRICITY
GET /rest/public/lses?zipCode=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": "",
      "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

Below is an example on how to confirm or change a customer’s LSE on their account (in this case changing it to the CCA “Sonoma Clean Power”). You can use the lseId field in the results to set the lseId property on the account.

PUT /rest/v1/accounts/pid/{providerAccountId}/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.

Pick the Right 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

You will use the Account Tariff endpoint to see what tariffs 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, make one of the following calls:

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

The endpoint will return a list of tariffs:

{
  "status": "success",
  "count": 18,
  "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 18 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 2 or 3 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/example_account/properties
{
    "keyName":"masterTariffId",
    "dataValue":"3200682"
}

Skipping 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

When you are running On-demand Cost Calculations which do not require accounts, you will use the Tariff endpoint to search for a set of tariffs.

To retrieve a list of tariffs, you will include the following parameters:

  • addressString or zipCode and country code for the list of tariffs available for your customer
  • customerClasses (RESIDENTIAL, GENERAL, or SPECIAL_USE) so you only get back tariffs for a specific customer class
  • tariffType (DEFAULT, ALTERNATIVE, etc.) to indicate which tariff types to include
  • serviceTypes (ELECTRICITY or SOLAR_PV) so you only get back tariffs for a specific service
  • effectiveOn so only tariffs effective on the specified date are retrieved
  • openOn to filter for tariffs that are not closed to new customers on the specified date
  • lseId (if known) so only tariffs of a specific LSE are retrieved
  • sortOn and sortOrder to sort by the most likely tariff

Here are two sample requests:

GET /rest/public/tariffs?addressString=20480 Chapel Drive, Monte Rio, CA 95462&customerClasses=RESIDENTIAL&tariffType=DEFAULT, ALTERNATIVE&serviceTypes=ELECTRICITY&effectiveOn=2017-01-01&openOn=2017-01-01&lseId=100747&sortOn=customerLikelihood, tariffType&sortOrder=DESC, ASC
GET /rest/public/tariffs?zipCode=95462&customerClasses=RESIDENTIAL&tariffType=DEFAULT, ALTERNATIVE&serviceTypes=ELECTRICITY&effectiveOn=2017-01-01&openOn=2017-01-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

The majority of residential customers are on the basic Residential tariff of a utility. Therefore, we set the tariff type for the most likely Residential tariff as DEFAULT and other Residential and C&I tariffs have a tariff type of ALTERNATIVE.

If your residential customer is not on the basic Residential tariff or you are selecting a tariff for a C&I customer, there are other criteria that you can use to find the right tariff.

Using the Tariff Code from the Bill or Statement

The most reliable method of selecting the right tariff is by matching the tariff code on a customer’s bill to the tariff code in our Tariff endpoint. 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?zipCode=94105&customerClasses=GENERAL&effectiveOn=2017-01-01&openOn=2017-01-01&serviceTypes=ELECTRICITY&populateProperties=true&search=E-20&searchOn=tariffCode

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 typically 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 parameters.

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

GET /rest/public/tariffs?zipCode=94105&customerClasses=GENERAL&effectiveOn=2017-01-01&openOn=2017-01-01&serviceTypes=ELECTRICITY&populateProperties=true&demand=550

The response will return information on the tariff’s demand limits in the properties section. Here is a snippet from PG&E’s E-19-TOU, which has a minimum demand of 500 kW and a maximum demand of 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 Tariffs that have additional Eligibility Requirements

Some Residential and C&I customers are eligible for tariff options such as Direct Access. You can filter for specific tariffs such as Direct Access by using the hasContractedRates parameter.

Here is a sample request for eligible tariffs which filters for Direct Access tariffs:

GET /rest/public/tariffs?zipCode=94105&customerClasses=GENERAL&effectiveOn=2017-01-01&openOn=2017-01-01&serviceTypes=ELECTRICITY&hasContractedRates=true

The response will return a list of Direct Access tariffs where "hasContractedRates": true.

You can learn more in our Tariff API documentation.

Some utilities require customers to switch to a different tariff when they go solar. 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 the solarPvEligible property set to true.

Here is a sample request to retrieve a list of PG&E tariffs:

GET /rest/public/tariffs?zipCode=94105&customerClasses=RESIDENTIAL&tariffTypes=DEFAULT,ALTERNATIVE&effectiveOn=2017-01-01&openOn=2017-01-01&populateProperties=true

The response will return a solarPvEligible property in the properties section with either a value of true or false. If the tariff is eligible for solar, the value will be true.