Step 2 - Confirm the Utility & Electricity Tariff
In step 1, you created a new account for a residential customer. In step 2, you’ll make sure that the account that you created has a) the correct utility, b) the correct tariff, and c) optionally the correct electives and other components needed to accurately calculate the account’s costs.
How we default a Utility and Tariff
When an account is created, the Genability API will try to guess the best tariff for your customer based on the address and customerClass. If either of these aren’t set, or are an invalid value (such as a bad address), we won’t be able to set the defaults.
For the address we are using in this tutorial, the tariff was automatically set to Pacific Gas & Electric’s E-1 Residential tariff, since that is the most common tariff for a residential customers in the 95462 US ZIP code (Pacific Gas & Electric is lseId 734 and E-1 is masterTariffId 522). You know that an account’s lseId property is a “likely” one rather than a confirmed one when you can see an accuracy value for it that’s less than 100. In our example, the lseId account property has "accuracy": 55.31. Similarly, notice the tariffs list has a tariff set on it that has "customerLikelihood": 55.31, which means that the tariff was also set to the most likely and has not yet been confirmed or changed.
If you were to run calculations against this account in this state, this is the tariff that would be used. However, sometimes your customer is not on the most popular tariff, or sometimes a particular ZIP code is serviced from several different utilities. In these cases, there’s still some work to be done in setting up the tariff on the account. It’s important to make sure that an account has the correct tariff set on it because the tariff determines how much money the customer pays to their utility for the energy they use. That, in turn, determines the amount of money they could save by going solar.
To pick the correct tariff when the default doesn’t work, most of our customer have the following user experience:
- Use the customer’s address information to filter the list of utilities to those for that zip/post code.
- Based on that utility selected, then pick the right tariff from a list of suitable tariffs available for that utility.
Get a list of Utilities
For many customers, there is only one utility that provides power in their area (in the APIs we call this a “load serving entity” or “LSE”). Some addresses, like the one we are using for this tutorial, will have more than one. This is either because their zip/post code is on the border of two or more utility service areas (this is more common than many people initially assume), or because the customer has some form of electricity supplier choice. We’ll use the Load Serving Entity endpoint to get a list of utilities, and then set the right one on the account.
The easiest way to see what utilities are available for your customer is to search by address or ZIP code.
GET /rest/public/lses?postCode=95462&country=US&residentialServiceTypes=ELECTRICITY&sortOn=totalCustomers&sortOrder=DESC
Or if you don’t have the zip/post code available, you can use the full address string:
GET /rest/public/lses?addressString=20480 Chapel Drive, Monte Rio 95462 US&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 electricity power to residential customers. Otherwise, the results you would get back would include solar providers and other (non-electricity) LSEs in our database. You could also use the commercialServiceTypes and industrialServiceTypes parameters for commercial and industrial customers, respectively. We always recommend you pass in the country set to your corresponding ISO Country Code.
The response should look like this:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
"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 (see the count property with a value of 2). The zip code provided maps to two electricity service area territories. We work hard to make sure that our zip/post code to utility mapping is accurate and up-to-date.
Set the Correct Utility
For this tutorial, we are assuming the customer’s Utility (LSE) is “Sonoma Clean Power”. To set this on the customers Account, we grab the lseId field in the results, and pass it in using the Account Property API like this:
PUT /rest/v1/accounts/pid/gdn-fst-eg-01/properties
1
2
3
4
5
{
"keyName":"lseId",
"dataValue":"100747",
"accuracy":100
}
The accuracy value is optional as it is assumed to be 100% if omitted. Once you have made this call, if you query a fresh copy of the account you will see that the lseId property is now switched over to Sonoma Clean Power and its accuracy is 100%. You’ve confirmed the utility on the account!
Get a list of Tariffs
Now that you’ve created an account and confirmed your customer’s LSE, you’re ready to confirm your customer’s tariff. To get a list of suitable tariffs, we’ll use the Account Tariff endpoint. This endpoint uses the data that you’ve added to our account already in order to show a list of tariffs that are available it. For our example, it will filter out tariffs that aren’t the residential customerClass, and only return those that are for our zip code.
To see what tariffs are available, make the following call:
GET /rest/v1/accounts/pid/gdn-fst-eg-01/tariffs?serviceTypes=ELECTRICITY
This will return a list of electricity tariffs:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
{
"status": "success",
"count": 23,
"type": "Tariff",
"results": [
{
"tariffId": 3279203,
"masterTariffId": 3200682,
"tariffCode": "E-1",
"tariffName": "Residential",
"lseId": 100747,
"lseName": "Sonoma Clean Power",
"priorTariffId": 3260063,
"tariffType": "DEFAULT",
"customerClass": "RESIDENTIAL",
"customerCount": 50000,
"customerLikelihood": 76.57,
"territoryId": 7571,
"effectiveDate": "2017-03-01",
"endDate": null,
"timeZone": "US/Pacific",
"billingPeriod": "MONTHLY",
"currency": "USD",
"chargeTypes": "FIXED_PRICE,CONSUMPTION_BASED,MINIMUM",
"chargePeriod": "DAILY",
"hasTimeOfUseRates": false,
"hasTieredRates": true,
"hasContractedRates": false,
"hasRateApplicability": true,
"isActive": true,
}
/* we have removed tariff data from here to keep the page shorter */
],
"pageCount": 25,
"pageStart": 0
}
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! Luckily, Genability helps you choose. The tariffs that are returned from the account tariff endpoint are ordered by likelihood by default. 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. Most utilities don’t have 23 Tariffs so your list won’t always be this long.
Set the Right Tariff
Once you selected the correct tariff from the list, you can set the masterTariffId property on the account like we just did for lseId. Let’s assume that our customer is on RES-1:
PUT /rest/v1/accounts/pid/gdn-fst-eg-01/properties
1
2
3
4
5
{
"keyName":"masterTariffId",
"dataValue":"3200682",
"accuracy":100
}
A note on Tariff Versions (tariffId versus masterTariffId)
Why did we use masterTarffId to set our customer’s tariff instead of tariffId? It’s because tariff data changes periodically. E-1, for example, usually changes a few times per year. For each version, we put a new tariff into the database with a unique tariffId. Logically, however, each of these new tariffs is actually just a different version of a single “master” tariff. This family of tariffs is tied together with the masterTariffId property. Each version of the tariff will have a different tariffId, but they all have the same masterTariffId.
Alternative UX, 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 automatically confirmed too.
Optionally match a bill and set other properties to increase accuracy
This next section is for extra credit! At this point, it may make sense to run a calculation to match your customer’s bill to make sure the account is provisioned correctly. We’ve also written up a number of additional data points that you can choose to set (or not set) on the account. Many of our residential customer skip these in order to keep things simpler for their users. Genability will use smart defaults. Non-residential customer typically include them. We suggest you read though and understand their impacts to you before choosing which to set and which to skip or default.
Run a calculation to match a bill
You can run an On-Demand Cost Calculation to match your customer’s existing utility bill to confirm the account is provisioned with the correct properties.
We go over this in our How-To on Running a Calculation to Match a Bill.
The tariff has rates that vary by region
California is a popular solar market. And in California many residential customers’ rates vary by how much power they use (their rates are tiered) and in turn the size of these tiers are based on where the customer lives. For example, customers in temperate coastal regions have lower tier levels than those in hotter in-land regions. These are sometimes called “baseline regions”. Other markets have a similar concept where rates on the same tariff are different based on which “sub-region” of the “service area” the customer is in. Genability keeps track of these regions and will also default to the most likely one based on the account’s zip.
If you want to use the default baseline region, no further action is needed. However, if you want to explicitly set the customer’s baseline region, you just set its territoryId value on the account, rather like you would set any other account property.
How do you know the customer’s tariff has rates that vary by region? Look at the tariff properties on their tariff (you can retrieve them via the Get Tariff API with populateProperties = true). If there is a property with the keyName of territoryId and a propertyTypes including RATE_CRITERIA then this tariff has them. Note that most don’t. The list of choices in this property are all the regions across this rate plan. You can use it, but its better to present the user with a shorter list; see Example 2 of the Get Territories API Page for how to get a list tailored to the customer’s location.
This how-to on baseline regions goes into the details.
My Customer Has Third-Party Supply!
Some markets, such as a number of states in the Northeast of the US, Texas, and many EU countries, give the option to choose electric supply from a third-party provider (often called deregulated or retail energy supply markets). Customers have the choice to pick an alternative supplier, and when they do often then pay one portion of their electricity (the “transmission and delivery” costs) to their main utility, and the other portion (the “supply” costs) to a different company. For these customers, you can provide their third party supply rate in order to do a savings analysis .
We have a full Contracted Rates how-to on how to do this with the Genability API.
Including Local Utility Taxes
The Genability Tariff rate database only has rates that appear in utility tariff books. That means that we don’t automatically assign state, local, and other “utility taxes”. That doesn’t mean that you can’t include them in savings calculations, though.
We have a Utility Tax how-to that gives you the details of exactly how to make your calculations include tax.
Other Rate Criteria
Finally, sometimes tariff rate plans have rates that vary by additional criteria. Examples include things like a) whether the customer has enrolled in elective features like Smart Days, b) how their site connects to the grid (primary, secondary etc), or c) if they get an employee or low income discount. These vary by utility and rate plan. Genability keeps track of all of these, and we default to the most likely values when calculating costs. For many tariffs, costs and savings aren’t sensitive to these values, so many of our residential customers choose to go with our defaults. However, if you are calculating savings for non-residential systems, or if you would like to make sure you have all the electives modelled, then you have the ability to do so.
Read our Rate Criteria How-To to get more details.
Summary
In the last step you created an account, setting its address and customer class. Then in this step you confirmed the correct Utility (LSE) and Tariff. Any calculations you now run will use the correct rate plan.
Next is to use your customer’s bills to create an electricity usage profile.