Turn a Bill Amount into kWh

Overview

A common issue that solar developers run into when analyzing a potential project is that most people don't know how much energy they're using. They may have some idea of how much they pay for electricity, but they have no idea how that translates into kWh. The Genability API has just the tool for this job: the Bill Solve option in the Calcluate API. With this option, you can estimate a customer's energy usage for a single bill based on the cost of that bill.

The Bill Solve Request

Here's an example of how it works. For this scenario, we have the following customer:

  1. Residential customer in Southern California Edison territory on the "D" tariff (masterTariffId 447)
  2. Actual bill of $51.76 for the period 2015-11-25 to 2015-12-28

To solve for this customer's monthly consumption value, we'll make the following call:

POST /rest/v1/calculate
{
  "providerAccountId": "sce-cust",
  "fromDateTime": "2015-11-25",
  "toDateTime": "2015-12-28",
  "billingPeriod": "true",
  "tariffInputs": [
    {
      "fromDateTime": "2015-11-25",
      "toDateTime": "2015-12-28",
      "keyName": "total",
      "dataValue": "54.71",
      "unit": "cost"
    },
    {
      "fromDateTime": "2015-11-25",
      "toDateTime": "2015-12-28",
      "keyName": "baselineType",
      "dataValue": "typicalElectricity"
    }
  ]
}

Let's break this down a little. Remember: you can see the full documentation for the Calculate API here.

Important Parameters

  1. Prior to this call, we've created an account called sce-cust that hold's our customer's data. Most importantly, it has their ZIP code, their utility, and their tariff. In this case, the customer is on the "D" tariff (masterTariffId 447).
  2. We set our billing period with fromDateTime and toDateTime to 2015-11-25 and 2015-12-28, respectively. To get the most accurate results, you'll want to make sure to use the actual dates on the bill.
  3. We set billingPeriod to true, because this feature only works for one bill at a time.
  4. We have two entries in the tariffInputs array. These are the inputs to our calculation. The first one is the most important one. For the billing period, our customer's cost is $54.71, so we send in a total property with a dataValue of 54.71. We also need to set the unit to cost so the calculator knows we're talking dollars instead of kWh or kW.
  5. The second input sets our initial guess of monthly consumption. Instead of choosing a particular value, I'm telling the API to use our database of typicals to set the first guess. This has two advantages: the typical profile should start out closer to the customer's actual usage, resulting in fewer guesses and a faster response. More importantly, it will give you fine-grained hourly data for your guess, resulting in more accurate results for TOU customers.

Running the Calculation

Once we've got our request set up, we run it. Here are the results:

{
  "status": "success",
  "count": 1,
  "type": "CalculatedCost",
  "results": [
    {
      "masterTariffId": 447,
      "tariffName": "Domestic",
      "totalCost": 54.96,
      "fromDateTime": "2015-11-25T00:00:00-08:00",
      "toDateTime": "2015-12-28T00:00:00-08:00",
      "currency": "USD",
      "summary": {
        "totalCost": 54.96,
        "kWh": 351.74,
        "kW": 0.71
      }
      ...

So according to our calculator, this customer's usage should be around 352 kWh for December. What happens if we run it in the other direction? We can use the following request to do just that:

POST /rest/v1/calculate
{
  "providerAccountId": "sce-cust",
  "fromDateTime": "2015-11-25",
  "toDateTime": "2015-12-28",
  "billingPeriod": "true",
  "tariffInputs": [
    {
      "fromDateTime": "2015-11-25",
      "toDateTime": "2015-12-28",
      "keyName": "consumption",
      "dataValue": "352"
    }
  ]
}

The results of which are:

{
  "status": "success",
  "count": 1,
  "type": "CalculatedCost",
  "results": [
    {
      "masterTariffId": 447,
      "tariffName": "Domestic",
      "totalCost": 55.02,
      "fromDateTime": "2015-11-25T00:00:00-08:00",
      "toDateTime": "2015-12-28T00:00:00-08:00",
      "currency": "USD",
      "summary": {
        "totalCost": 55.02,
        "kWh": 352,
        "kW": 0
      }
      ...

And that's it! Remember, it only works for one bill at a time.