This How-To covers a very common issue in the solar world: how do you do a savings analysis when you have less than a year of bills? Normally, this situation can lead to wildly inaccurate results, but when you’re using Genability’s API, this isn’t a problem. With the Genability’s Typical Baseline service, you can turn three (or two, or one) bills into twelve with just two calls and a little bit of code. This tutorial will show you how to do that.


Before you can get started with this How-To, you’ll need to have created an Account. Since you’re going to be uploading a usage profile, you’ll need an account to add it to.

Problem: Not Enough Data

As a solar installer, it’s very common to run into potential customers who don’t know how much electricity they use. Sometimes, these customers have access to their utility’s online bill service or they have good bill records, and you can use that data to develop a usage profile for them. Other times, this isn’t possible. Maybe your customer’s utility has an online service that isn’t very good, or maybe the customer throws out their electricity bills as soon as they pay them. Either way, this can be a major impediment to doing an accurate savings analysis. Fortunately, the Genability API has the right tool for the job: typical baselines.

Solution: Typical Baselines

The typical baseline service is a collection of customer usage profiles from around the country, organized by location, customer type, and building type. They’ve been developed using the data from thousands of analyses that have been done with the Genability API. Using these profiles, we can turn any number of bills into a full year of data for a savings analysis. Here’s an outline of how we’re going to do it:

  1. Get a baseline profile that is appropriate for your area, customer class, and building type.
  2. Using the data that you do have, develop a set of annual profiles.
  3. Choose the best profile and use that for your analysis.

Get a Baseline

The first step is to get a typical baseline profile for the customer. Let’s assume the following scenario: a residential customer living in San Francisco, with ZIP code 94123. We can get a baseline for this person with the following request:

GET /rest/v1/typicals/baselines/best?addressString=94123&buildingType=singleFamilyAttached&excludeMeasures=false&groupBy=MONTH&measureUnit=proportion

This request returns a baseline profile with a couple of special options. First, we’ve grouped the result by month. You can also choose to group by hour, but month is good enough for this scenario. We’ve also specified that we want the results to be returned as proportion rather than monthly consumption. This will make the scaling of our usage data a little more straightforward.

Among other things, this request will return a series of measurements:

"measures": [
    "i": 1,
    "v": 8.84306292
    "i": 2,
    "v": 7.72489182
    "i": 3,
    "v": 8.47541736
    "i": 4,
    "v": 8.01065365

/* edited for length */

    "i": 12,
    "v": 8.81430209

Each measurement is indexed by the month of the year that it corresponds to, with 1 representing January, 2 representing February, and so on. Since we chose to have the results returned as proportions, each value represents the proportion of a typical customer’s annual usage that is used in that month. So, in this example, a typical customer in ZIP code 94123 uses 8.84% of their annual total in January.

Match the Baseline to Existing Data

The next step is to combine the baseline data with our existing data in order to create a usage profile for the full year.

Let’s say that our San Francisco resident gave us two bills:

  1. In March, they used 678 kWh
  2. In April, they used 725 kWh

We’ll use these two bills to create a pair of annual consumption profiles. Then we’ll choose the best one.

Create the Test Profiles

For each bill, we’ll use the energy consumption from that bill to scale our baseline profile up or down to match it. We’ll do this by multiplying the usage for the month that we do have by the ratio of that month’s typical usage to the target month’s typical usage: target_month_estimated_usage = actual_month_usage * (target_month_typical_proportion / actual_month_typical_proportion). For example, using the March bill, we would scale the whole year like this:

# assume we have a variable called "baseline"
# that contains the data from above
march_usage = 678
march_proportion = 8.47541736
scaled_baseline = []

# loop through each month and scale it according
# to the march bill's usage
for each month in baseline:
    month_proportion = month.v
    scaled_month = march_usage * (month_proportion / march_proportion)

The result of which would be a set of monthly kWh values that are scaled based on the actual bill for the month of March. When we actually do the calculations, the results look like this:

# scaled based on the actual usage for
# march
scaled_baseline = [

After doing the same thing for April, we now have a pair of annual usage profiles. How do we choose?

Choose the Best Profile

We’re going to choose our profile by determining which one is closest to our actual data. That begs the question, “How do we determine which profile is closer?”. For this example, we’ll calculate the root-mean-square error (RMSE) for each profile and then choose the one with the smallest error. The RMSE tells us how far away our estimated data is from our actual data.

Again using the March profile as an example, the calculation of its RMSE would look like this:

# zero-indexed arrays
march_estimate = 678 # exactly the real usage, because we scaled it against itself
april_estimate = 641

march_diff = (march_usage - march_estimate)^2 # 0, since it's the actual number
april_diff = (april_usage - april_estimate)^2 # 7086

rmse = sqrt((march_diff + april_diff)/2) # 59.5

After we do this for both profiles, it turns out that the profile that used March as its basis has a smaller error than the one that used April – 59.5 versus 63.0. We’ll use the March profile when we actually upload to the Genability API.

Substitute Your Actual Data

Before we send back the estimated data, though, we should make sure to substitute our data from April back in. Since actual data is almost always better than estimated data, there’s no reason to use the April estimate when we have the real number. Our final profile looks like this:

   "profileName":"Residential TOU Profile",
   "description":"Residential Electricity TOU Profile",
         // actual data for march 
         // actual data for april 

We can upload this profile to our account with the following call:

PUT /rest/v1/profiles