Select the Right Utility and Tariff

About Utilities and Tariffs

We collect utility and tariff data across the USA, Canada, and Mexico. 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.

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 customers, when you create a new Account, we will set the most 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][account-cost-calculation-api-ref] and [Savings Analyses][sa-api-ref] 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 [email protected] for our Support team to investigate.

Confirm the Right Utility on an Account

Once the correct Utility has been selected, Switch customers should set it on the Account. Below is an example of 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 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][account-tariff-api-ref] 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.

Further Refining the List of Tariffs

Most of the time 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, which is particularly useful when the utility has a long list of tariffs.

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/v1/accounts/pid/{providerAccountId}/tariffs?search=EVA&searchOn=tariffCode&effectiveOn=2017-10-01&sortOn=customerLikelihood,tariffType&sortOrder=DESC,ASC

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

You can learn more in our documentation on how to Account Tariffs and how to use the Searching and Sorting parameters.

Filtering out Tariffs that are closed to new enrollment

Sometimes utilities retire tariff rate plans. We flag these with the date they were closed. 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/v1/accounts/pid/{providerAccountId}/tariffs?effectiveOn=2017-10-01&openOn=2017-10-01

Filtering Tariffs based on Rate characteristics of the Tariff

Occasionally 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:

Here is an example request for currently effective and open California C&I tariffs with a Direct Access component:

GET /rest/v1/accounts/pid/{providerAccountId}/tariffs?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 [Account Tariffs API][tariff-api-ref-get-n] 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. Arcadia 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 requires 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 [email protected] for details.