Common Scenarios

Overview

This page is the "quick hits" for the Genability API. It contains answers to some of people's most frequently asked questions. It's divided into sections based on endpoint.

Accounts

The Account endpoint is one of the most important pieces of the Genability API. It stores all of the data for a particular customer. We have a whole how-to dedicated to creating and populating them, but some of the basics are below.

Create An Account

Create an account by doing a POST or PUT request to the account endpoint:

POST /rest/v1/accounts
PUT /rest/v1/accounts

Use the PUT version of the request if you want to set the providerAccountId on the account before you upload it. This is useful if you already have an ID for the account in your internal system.

Update An Account

The simplest way to update some part of an account to set the corresponding account property:

POST /rest/v1/accounts/{accountId}/properties
{
    "keyName":"masterTariffId",
    "dataValue":518
}

Add a Tax Rate to an Account

The Genability database only has rates that appear in utility tariff books. That means that it does not have state, local, and other tax rates. To incorporate a tax (say, a Utility User's Tax or UUT) into a calculation on your account, you can include in that account's tariffs:

PUT /rest/v1/accounts/{accountId}/tariffs
PUT /rest/v1/accounts/pid/{providerAccountId}/tariffs
{
   "masterTariffId":"522",
   "serviceType":"ELECTRICITY",
   "rates":[
      {
         "chargeType":"TAX",
         "rateName":"Utility Tax",
         "rateBands":[
            {
               "rateAmount":0.085,
               "rateUnit":"PERCENTAGE"
            }
         ]
      }
   ]
}

Find Available Tariffs

Once you've set up an account, you can use the Account Tariff endpoint to find tariffs that are available to it. You can do this by accountId or providerAccountId:

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

This request will list available tariffs in order of likelihood, with the most likely tariff at the top and the least likely at the bottom.

Load Serving Entities

Load Serving Entities (LSEs) are what utilities are called in the Genability API. They maintain local electrical grids and provide energy to their customers. You can read all of the details at the dedicated LSE page.

Find Local Utilities

You can filter LSEs by sending in a ZIP code:

GET /rest/public/lses?zipCode=94105

Or an address:

GET /rest/public/lses?addressString=221 Main St, San Francisco, CA 94105

You can also specify that you only want LSEs that serve residential customers:

GET /rest/public/lses?zipCode=94105&residentialServiceTypes=ELECTRICITY

Savings Analysis

The Savings Analysis endpoint is where you'll go when you want to figure out how much money your customer can save by going solar. You'll pass in an account, some usage data, and a solar profile and we'll send back detailed information about customer savings.

Switch Tariffs After Going Solar

Set the masterTariffId property on the after scenario:

{
    "scenarios" : "after",
    "keyName" : "masterTariffId",
    "dataValue" : "522"
}

Do a Quick "What-If?" with a Different System Size

Sometimes you want to know what will happen if your system is half (or twice) the size that it is now. With the dataFactor parameter, you can do this without having to create an entirely new solar profile:

{
    "scenarios" : "after,solar",
    "keyName" : "providerProfileId",
    "dataValue" : "{providerProfileId}",
    "dataFactor" "0.5"
}

This also works for consumption profiles.

Set A Solar Lease/PPA Price

Add an item to the rateInputs array and set its scenario to solar:

"rateInputs" : [ {
    "scenarios" : "solar",
    "chargeType" : "FIXED_PRICE",
    "rateBands" : [ {
      "rateAmount" : 137.05
    } ]
} ]

This example would set your first-year lease rate to $137.05 per month. These inputs are structured just like TariffRates.

Extend the Duration of the Savings Analysis Projection

The default duration of a savings analysis is 20 years. For some customers, you may want to go longer -- 25 years, for example. To do that, you can use the projectDuration property input parameter.

{
    "scenarios" : "before,solar,after",
    "keyName" : "projectDuration",
    "dataValue" : "25"
}

Do An Accurate Analysis With an Annual Consumption Number

It can often be difficult to get detailed data from a potential solar customer. Most of the time, this means that you have to do what you can with limited data. The savings analysis endpoint helps you here by giving you a simple way to do a detailed calculation if you only have one number: the customer's annual energy consumption.

Here's a bare-bones example:

{
  "providerAccountId" : "api-eg-01",
  "fromDateTime" : "2014-09-01",
  "propertyInputs" : [ {
    "scenarios" : "before,after",
    "keyName" : "baselineType",
    "dataValue" : "typicalElectricity"
  }, {
    "scenarios" : "before,after",
    "keyName" : "loadSize",
    "dataValue" : "5000",
    "unit":"kWh"
  } ]
}

The two input parameters that we use are baselineType and loadSize. baselineType tells the API that you want to use our database of typicals to do your analysis. It will automatically choose an appropriate usage profile based on your account's location and customer type. loadSize tells the API how much energy your customer is using in a year. In this case, they're using 5,000 kWh. The typical profile is scaled up or down to meet the target load.

Usage Profiles

Usage profiles are how you tell the API how much energy a customer is using or how much energy a solar power system is producing. In order to calculate customer savings, you'll need a usage profile.

Upload TOU Data

We have a detailed how-to for this.

Create a Solar Profile

There are two differences between a normal usage profile and a solar profile. The first is the serviceTypes field. Set it to SOLAR_PV instead of ELECTRICITY to indicate that you're uploading a solar profile. The second difference is where you put the production data. For estimated solar production, you should use the baselineMeasures field to upload your energy estimates. See the detailed example on the usage profile page.

{
  "providerAccountId" : "api-eg-01",
  "providerProfileId" : "eg-BaselineMeasures",
  "serviceTypes" : "SOLAR_PV",
  "sourceId": "SolarPvModel",
  "baselineMeasures": [
      {
          "i":1,
          "v":10
      },
      {
          "i":2,
          "v":20
      },

      /* edited for length */

      {
          "i":8759,
          "v":20
      },
      {
          "i":8760,
          "v":10
      }]
}

Use PVWatts to Create a Solar Profile

If you don't want to use an external tool do your solar estimation, you can use PVWatts. It's integrated into our API, so you can do the estimate and upload a profile at the same time. Set the sourceId to PVWatts and specify the parameters that you want:

{
  "providerAccountId" : "api-eg-008",
  "providerProfileId" : "PVWATTS_RESIDENTIAL_CA_2012",
  "serviceTypes" : "SOLAR_PV",
  "sourceId" : "PVWatts",
  "properties" : {
    "systemSize" : {
      "keyName" : "systemSize",
      "dataValue" : "8.25"
    },
    "azimuth" : {
      "keyName" : "azimuth",
      "dataValue" : "170"
    },
    "derate" : {
      "keyName" : "derate",
      "dataValue" : "0.816"
    },
    "tilt" : {
      "keyName" : "tilt",
      "dataValue" : "17"
    }
  }
}

We support both PVWatts v4 and v5. See the complete documentation for more details.

Account for Hawaii Sun Zones in a PVWatts Profile

When estimating solar production in Hawaii, it's all about location, location, location. Because the weather varies so much there, systems located only a few miles apart may produce wildly different amounts of energy.

To help installers deal with this issue, the Hawaii State Energy Office put together a map of "Sun Zones". These Sun Zones can be used to adjust PVWatts estimates to be more accurate. Fortunately, they're also built right in to the Genability API! In order incorporate a Hawaii Sun Zone into your PVWatts analysis, just add the following property to your add profile request:

"climateDataCorrectionZone": { 
    "keyName":"climateDataCorrectionZone", 
    "dataValue":"{sunZone}" 
}

The Sun Zone values range from 200-250, 251-300, and so on up to 601-650. After you've included this new property, a correction factor based on the Sun Zone will be automatically applied to the resulting profile.