**Attention Developers: Our Documentation Is Moving!**

Explore the latest updates and features in our new Signal Product Documentation and Switch Product Documentation.

Please note, this site’s retirement date will be announced soon, so make sure to update your bookmarks.

# Turning Bills into kWh

A common issue that new energy companies run into when analyzing a potential project is that they need to know how much electricity a home or business is using, but cannot get access to meter data or good quality usage numbers. Most customers don’t know how much electricity 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 our Calculator. With this option, you can back into an estimate of a customer’s energy usage for a single billing period with just the cost of that bill. Similarly, if your customer knows what they spend annually on electricity, *Bill Solve* can estimate annual kWh as well.

Our On-Demand Cost Calculator supports these Bill Solve calculations.

*While Bill Solve provides monthly and annual options to determine a customer’s usage, we recommend using the monthly option with exact billing dates for the highest precision. The annual option requires Bill Solve to make assumptions about how your customer’s usage is distributed over the entire year.*

## Monthly Bill Solve Request

Here’s an example of how the monthly option works. For this scenario, we have the following customer:

- Residential customer in Southern California Edison territory on the “D” tariff (
`masterTariffId`

447) - 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 to the On-Demand Cost Calculator:

```
POST /rest/v1/ondemand/calculate
```

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

{
"fromDateTime": "2015-11-25",
"toDateTime": "2015-12-28",
"masterTariffId": 447,
"billingPeriod": "true",
"propertyInputs": [
{
"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 On Demand Cost Calculator here.

### Important Parameters

- Prior to this call, using the customers ZIP code, we determined their current tariff. which in this case ustomer is SCE’s “D” tariff (
`masterTariffId`

447). - We set our calculation date range 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. - We set
`billingPeriod`

to`true`

, because we want to ensure monthly charges (if any) are considered in the calculation. - We have two entries in the
`propertyInputs`

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

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

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/ondemand/calculate
```

1
2
3
4
5
6
7
8
9
10
11
12
13

{
"fromDateTime": "2015-11-25",
"toDateTime": "2015-12-28",
"billingPeriod": "true",
"propertyInputs": [
{
"fromDateTime": "2015-11-25",
"toDateTime": "2015-12-28",
"keyName": "consumption",
"dataValue": "352"
}
]
}

The results of which are:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

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

That’s how a monthly *Bill Solve* request works but what if we want to find out consumption based on a year’s electricity cost?

## Annual Bill Solve Request

Here’s an example of how to back into a usage estimate if you have an annual cost. For this scenario, we have the following customer:

- Residential customer in Baltimore Gas & Electric’s territory on the “R” tariff (
`masterTariffId`

674) - Estimated annual cost of $1700 for the period 2016-10-15 to 2017-10-15

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

```
POST /rest/v1/ondemand/calculate
```

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

{
"fromDateTime": "2016-10-15",
"toDateTime": "2017-10-15",
"masterTariffId": 674,
"billingPeriod": "false",
"propertyInputs": [
{
"fromDateTime": "2016-10-15",
"toDateTime": "2017-10-15",
"keyName": "total",
"dataValue": "1700",
"unit": "cost"
},
{
"fromDateTime": "2016-10-15",
"toDateTime": "2017-10-15",
"keyName": "baselineType",
"dataValue": "typicalElectricity"
}
]
}

### Important Parameters

- For this example, like the previous one, we used the customers ZIP code to determine their tariff. In this case, the customer is on BG&E’s “R” tariff (
`masterTariffId`

674). - We set our billing period with
`fromDateTime`

and`toDateTime`

to`2016-10-15`

and`2017-10-15`

, respectively. As with monthly bill solve, using the day of the month from the bill will improve precision. - We set
`billingPeriod`

to`false`

, because this calculation will include many billing periods, not one. This is important for tariffs that have fixed monthly charges. - We have two entries in the
`propertyInputs`

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 $1700, so we send in a`total`

property with a`dataValue`

of 1700. We also need to set the`unit`

to`cost`

so the calculator knows we’re talking dollars instead of kWh or kW. - 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:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

{
"status": "success",
"count": 1,
"type": "CalculatedCost",
"results": [
{
"masterTariffId": 674,
"tariffName": "Residential",
"totalCost": 1702.21,
"fromDateTime": "2016-10-15T00:00:00-04:00",
"toDateTime": "2017-10-15T00:00:00-04:00",
"currency": "USD",
"summary": {
"subTotalCost": 1702.21,
"taxCost": 0,
"totalCost": 1702.21,
"adjustedTotalCost": 1702.21,
"kWh": 11108.53,
"kW": 3.75
}
...

So according to our calculator, this customer’s usage should be around 11109 kWh for a year starting in mid-October of 2016. What happens if we run it in the other direction? We can use the following request to do just that:

```
POST /rest/v1/ondemand/calculate
```

1
2
3
4
5
6
7
8
9
10
11
12
13
14

{
"fromDateTime": "2016-10-15",
"toDateTime": "2017-10-15",
"masterTariffId": 674,
"billingPeriod": "false",
"propertyInputs": [
{
"fromDateTime": "2016-10-15",
"toDateTime": "2017-10-15",
"keyName": "consumption",
"dataValue": "11109"
}
]
}

The results of which are:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

{
"status": "success",
"count": 1,
"type": "CalculatedCost",
"results": [
{
"masterTariffId": 674,
"tariffName": "Residential",
"totalCost": 1708.23,
"fromDateTime": "2016-10-15T00:00:00-04:00",
"toDateTime": "2017-10-15T00:00:00-04:00",
"currency": "USD",
"summary": {
"subTotalCost": 1708.23,
"taxCost": 0,
"totalCost": 1708.23,
"adjustedTotalCost": 1708.23,
"kWh": 11109,
"kW": 0
}
...

And that’s it! Remember, calculating usage for one bill will yield more precise results than an annual calculation.