Cost Calculator

Overview

Note that the Tariff Cloud APIs are deprecated. If you are a Switch or Conduct product customer, you should migrate to those APIs instead. If you are new to Genability, do not start to use these. Ask us if you have any questions.

The Cost Calculator service calculates the cost of electricity for a given tariff for a given amount of electricity over a specified period of time. This can be used to calculate a bill, "what-if" different rates, levels of usage, energy efficiency measures or any other electrical activity. (Note that if you want a price or rate for a specific point in time, then look at the Price service.)

To run the calculation, the service needs to know what tariff to use and the inputs that drive the rates. These inputs typically include consumption (kWh) but can also include other values such as:

  • demand (kW)
  • applicability criteria, e.g. whether the consumer lives inside or outside of city limits
  • quantity of other items, e.g. tariffs that are priced based on the number of billing meters at the facility

The accuracy of the calculation is dependent on the accuracy and granularity of the inputs the calculator uses. For example, a time-of-use (TOU) tariff will have different prices depending on the time of day the consumption occurred. Passing in an hourly load profile will generate very accurate calculations. On the other hand, passing in an aggregate consumption such as the monthly total will generate a less accurate calculation since we do not know precisely at what time of the day this consumption occurred. When you don't pass in all of the information that is required, the calculator will make a best-guess to a value to use (e.g. it will estimate the TOU breakdown of your energy usage). You can see what inputs were used to generate a given calculation as these are returned along with the calculation.

Since different tariffs require different inputs, we have provided a service to tell you what inputs are applicable for that plan. In other words, a service that answers the question, "For tariff X, what do I need to give you to get an accurate cost?" This is documented in the Get Inputs section below. What is returned from this can be used as a template for what to pass to the calculator. Just fill in the quantities for the inputs, and call the Calculate method.

Data Definitions

Property Data and Tariff Inputs

Property data and tariff inputs are closely related. Property data tells you the properties associated with the calculation of this tariff. Tariff inputs are the populated properties you pass in when running a calculation. For example:

When you call Get Inputs, the list of property data that is returned tells you what properties you may specify in order to run this calculation. For example, for a property data returned of keyName "connectionType", you may specify if this is a "Primary" or a "Secondary" connection. If you don't specify the "connectionType", it will be defaulted.

When you call Calculate, you will pass in an array of property data (in an array called tariffInputs) and here you will have them populated.

The PropertyData object has the following data structure.

Name Type Fields Description
keyName String M The key name of the property associated with this input. The most common one will be consumption (which is the kWh for the period), and second most common is demand (kW), but can also be applicability properties like cityLimits or hasElectricVehicle
displayName String M A display-friendly name for this property. (Optional)
description String M A text description of this property. (Optional)
dataType String M The type of this property. Possible values are: "STRING", "CHOICE", "BOOLEAN", "DATE", "DECIMAL", "INTEGER", and "FORMULA" (Optional)
fromDateTime DateTime The start of the period where this property is applicable. Defaults to the start of the calculation if not provided. (Optional)
toDateTime DateTime The end of the period where this property is applicable. Defaults to the end of the calculation if not provided. (Optional)
unit String Where applicable, this is the unit of the value. Most common are: "kWh" - for keys of consumption, "kW" - for keys of demand. (Optional)
dataValue String The value of this Property. (Optional)

Calculated Cost

The CalculatedCost object contains the summary of the calculation. The totalCost field holds the overall cost while the details of the calculation are contained within a list of calculated cost items. CalculatedCost also contains the list of inputs that were used in this calculation.

Name Type Fields Description
masterTariffId Long M Unique Genability ID for the master tariff of this calculation's tariff.
tariffName String M The name of this tariff.
totalCost Decimal M Total summed up cost of all cost items (see below).
fromDateTime DateTime M The start date and time of this calculation.
toDateTime DateTime M The end date and time of this calculation.
currency String M The currency represented in the calculation.
summary Map A summary map of totalCost, kWh, and kW used in the calculation.
accuracy Decimal M A decimal value between 0 and 1 representing the accuracy of the calculation. As more best guess calculation assumptions are made, the calculation will become less accurate and the accuracy field will be smaller.
items Array of CalculatedCostItem M Array of the CalculatedCostItem objects that comprise this calculated cost. These will be summarized as requested. Currently this is one item per tariff rate, but soon there will be other options for levels of summary or detail.
assumptions Array of PropertyData The assumptions that were used by the calculator. In the event that a required input was not provided, the calculator will make a best guess assumption for what was used. The accuracy field of each PropertyData item indicates how accurate this input was, with values ranging from 0 - 1 with 1 being a completely accurate input.

Calculated Cost Item

The calculated cost items contain the details of the calculations. There is one CalculatedCostItem object for each tariff rate that is included in the calculation. The CalculatedCostItems object has the following data structure.

Name Type Fields Description
tariffId Long E Unitque Genability ID of the tariff associated with this cost item.
tariffRateId Long M Unique Genability ID of the tariff rate associated with this cost item.
tariffRateBandId Long M Unique Genability ID for the band associated with this cost item.
rateSequenceNumber Integer M The sequence number of the rate group that the tariff rate belongs to.
rateGroupName String M The name of the group this rate belongs to.
rateName String M The name of this rate.
fromDateTime DateTime M The start date and time of the period applicable for this cost item.
toDateTime DateTime M The end date and time of the period applicable for this cost item.
quantityKey String M The key for the quantity this calculated cost item refers to. Possible values include: fixed, consumption, minimum.
quantityKeyDescription String E The textual description of the quantity key specified by quantityKey.
rateType String M The type of rate this charge is. Current values include "COST_PER_UNIT" which is a cost for each unit of quantity consumed (e.g. $0.10 per kWh), and "PERCENTAGE" which is a percent of another cost (e.g. 10% of your bill).
rateAmount Decimal M The monetary amount of the rate associated with this cost item.
tierLowerLimit Decimal E For a tiered rate, the minimum quantity needed to invoke this tier. (Optional)
tierUpperLimit Decimal E For a tiered rate, the maximum quantity at which this tier is invoked. (Optional)
itemQuantity Decimal M Total quantity used for this item's charge. This will typically be 1 but will have different values for charges related to the number of units of some items (e.g. number of billing meters at a facility).
cost Decimal M This is the total cost for this line item.
rateProration E E The amount this rate is being prorated compared to the full rate amount. (Optional)
chargeType String E The type of rate such as CONSUMPTION_BASED or DEMAND_BASED.
chargeClass String E The class of rate such as TRANSMISSION or DISTRIBUTION.
period String E The Time of Use type, such as OFF_PEAK and PEAK. (Optional)
family String E The family associated with the quantityKey. (Optional)
formula String E The formula associated with the quantityKey. (Optional)
demandInterval DateTime E For demand charges, the time from which demand is measured. (Optional)
duration Integer The duration in milliseconds (Optional)
touId Long The unique Genability ID of the time of use associated with this cost item. (Optional)
touName String Human-readable name of the time of use specified by touId. (Optional)
seasonId Long The unique Genability ID of the season in which the time of use period is situated, which can affect the rate. (Optional)
seasonName String Human-readable name for the season in which the time of use period is situated. (Optional)

Operations

Get Calculate Input meta-data

The GET method returns the inputs that may be passed into a calculation for the specified tariff, for the specified period of time. Many tariffs accept additional query parameters for the tariff's applicability values, such as cityLimits or connectionType. This is needed because rates differ based on the value of these applicability values. When these are required for the tariff but not provided in the request body, they will be defaulted, and an assumption will be added to the response.

Resource URI

GET /rest/v1/calculate/{masterTariffId}

Request Parameters

Along with the required security parameters, the following parameters are available as part of the request:

Name Type Description
fromDateTime DateTime Starting date and time for this Calculate request. (Required)
toDateTime DateTime End date and time for this Calculate request. (Required)
groupBy String This controls how the calculation details are grouped, for example grouping the details by month or year. There is no default value; if not specified the details will use the frequency contained within the rates. (Optional) The choices are:
HOUR - groups the calculation details by hour.
DAY - groups the calculation details by day.
MONTH - groups the calculation details by month.
YEAR - groups the calculation details by year.
ALL - One group for the entire calculation period.
billingPeriod String A true or false flag. If the dates of the calculation represent an actual billing cycle, then you should set this to true. This will give you precise values for items like fixed charges. When it's not set, or set to false, these charges will be prorated across the number of days in the calculation. Default is false. (Optional)
applicability keyName String Any additional applicability parameters that are required to calculate this tariff must be passed in on the request URL. To find out how to get the list of applicability properties required for a tariff, read more here. If the tariff requires a territoryId, (as most CA tariffs do), read here to see how to get the territoryId from a ZIP code.
tariffEffectiveOn DateTime This field enables doing a calculation with a single, specified version of a given tariff. For example, if the user specifies that they want to use the 2016-01-01 version of PG&E's E-1 tariff, any calculation, whether it's for 2013, 2015, or 2016, would use the rate data from that version and only that version of the tariff.
minimums Boolean This field enables enforcing minimum charges on this calculation. The default value is false. (Optional)
excludeChargeClass String Specifies a charge class to exclude from the calculation results. (Optional)
calcNetExcessGeneration Boolean This field enables including net metering totals in the summary section of the calculation. The default value is false. (Optional)

Example - request the properties used by tariff 512

GET /rest/v1/calculate/512?fromDateTime=2011-12-01T00:00:00.0-0500&toDateTime=2012-01-01T00:00:00.0-0500

Below is a sample response containing three PropertyData items for consumption, cityLimits and connectionType. These are the three items that may be supplied to the POST calculate method (below) in order to run the calculation for this tariff. If the cityLimits property is not passed to the POST calculate method, it will be defaulted.

{
   "status":"success",
   "count":3,
   "type":"PropertyData",
   "results":[
      {
         "keyName":"consumption",
         "dataType":"DECIMAL",
         "fromDateTime":"2011-12-01T00:00:00-05:00",
         "toDateTime":"2012-01-01T00:00:00-05:00",
         "unit":"kwh"
      },
      {
         "keyName":"cityLimits",
         "displayName":"City Limits",
         "description":"Is this service inside or outside city limits.",
         "dataType":"CHOICE",
         "fromDateTime":"2011-12-01T00:00:00-05:00",
         "toDateTime":"2012-01-01T00:00:00-05:00",
         "dataValue":"Inside"
      },
      {
         "keyName":"connectionType",
         "displayName":"Connection Type",
         "description":"Where/how the service is connected to the grid (e.g. primary, transmission, subtransmission).",
         "dataType":"CHOICE",
         "fromDateTime":"2011-12-01T00:00:00-05:00",
         "toDateTime":"2012-01-01T00:00:00-05:00",
         "dataValue":"Primary"
      }
   ]
}

Run new Calculation

To run a new calculation, you will POST a payload containing the calculation criteria and inputs, and a CalculatedCost object will be returned. Note that these parameters are part of the request body, not the query string. See below for an example.

Name Type Description
fromDateTime DateTime Starting date and time for this Calculate request. (Required)
toDateTime DateTime End date and time for this Calculate request. (Required)
accountId String The accountId of the account for which to run this calculation. This will cause the calculator to take default values from the specified account, but you can override values contained in the account by passing in values through the inputs array below. (Optional)
detailLevel Enumeration Toggles the level of details for the calculation result. Explanation (Optional, Default=ALL)
groupBy Enumeration This controls how the calculation details are grouped. Explanation (Optional, Defaults to the natural grouping for the rates)
billingPeriod String A true or false flag. If the dates of the calculation represent an actual billing cycle, then you should set this to true. This will give you precise values for items like fixed charges. When it's not set, or set to false, these charges will be prorated across the number of days in the calculation. Default is false. (Optional)
tariffInputs Array of PropertyData The input values to use when running the calculation. This is where you would specify an accountId as well as any other inputs. Note: accountId can also be specified as a query string parameter, e.g. accountId=abc123. If you are not specifying any inputs, you must still include an empty tariffInputs field. (Required)
rateInputs Array of TariffRate The rate input values are used to override existing rates on the tariff during the calculation. This enables modeling and/or setting customer specific rates during a calculation. (Optional)

Resource URI

POST /rest/v1/calculate/{masterTariffId}

Examples

Example 1 - Calculate with an Account

Note, the tariff ID in the URL is optional when the account contains a tariff ID. If a tariff is specified in the URL, this will override the tariff ID in the account.

POST /rest/v1/calculate/512

Below is a sample POST request containing the accountId.

{
   "fromDateTime":"2011-11-01T00:00:00-05:00",
   "toDateTime":"2012-01-01T00:00:00-05:00",
   "groupBy":"MONTH",
   "detailLevel":"TOTAL",
   "tariffInputs":[
      {
         "keyName":"accountId",
         "fromDateTime":"2011-11-01T00:00:00-0500",
         "toDateTime":"2012-01-01T00:00:00-0500",
         "dataValue":"62d07619-06fd-4a28-9376-62c86c7811d5"
      }
   ]
}

The fromDateTime and toDateTime are required on all tariffInputs. When specifying the accountId, you must also include these fields, although the values are not currently used. Passing in multiple accountIds does nothing as the calculation is run on the first accountId that is passed in.

Example 2 - Calculate Without an Account

The tariff ID must be specified in the URI.

POST /rest/v1/calculate/512

Below is a sample POST request with the three required tariffInputs populated.

{
  "fromDateTime" : "2011-12-01T00:00:00-05:00",
  "toDateTime" : "2011-12-01T01:00:00-05:00",
  "tariffInputs" : [ 
  {
    "keyName" : "consumption",
    "fromDateTime" : "2011-12-01T00:00:00-0500",
    "toDateTime" : "2011-12-01T00:15:00-0500",
    "unit" : "kWh",
    "dataValue" : 2.2
  },
  {
    "keyName" : "consumption",
    "fromDateTime" : "2011-12-01T00:15:00-0500",
    "toDateTime" : "2011-12-01T00:30:00-0500",
    "unit" : "kWh",
    "dataValue" : 1.3
  },
  {
    "keyName" : "consumption",
    "fromDateTime" : "2011-12-01T00:30:00-0500",
    "toDateTime" : "2011-12-01T00:45:00-0500",
    "unit" : "kWh",
    "dataValue" : 0.6
  },
  {
    "keyName" : "consumption",
    "fromDateTime" : "2011-12-01T00:45:00-0500",
    "toDateTime" : "2011-12-01T01:00:00-0500",
    "unit" : "kWh",
    "dataValue" : 2.1
  },
  {
    "keyName" : "cityLimits",
    "fromDateTime" : "2011-12-01T00:00:00-0500",
    "toDateTime" : "2011-12-01T01:00:00-0500",
    "dataValue" : "Inside"
  } ,
  { 
    "keyName" : "connectionType",
    "fromDateTime" : "2011-12-01T00:00:00-0500",
    "toDateTime" : "2011-12-01T01:00:00-0500",
    "dataValue" : "Primary"
  }  ]
}

Run Calculate Response

The result of the calculation is returned in one CalculatedCost object. Each tariff rate within this tariff is calculated and returned in its own calculated cost item. The sum of all the calculated cost items is the totalCost, contained in the parent calculated cost.

{
    "status" : "success",
    "count" : 1,
    "type" : "CalculatedCost",
    "results" : [ {
    "masterTariffId" : 512,
    "tariffName" : "Residential Service",
    "fromDateTime" : "2011-12-01T00:00:00-05:00",
    "toDateTime" : "2011-12-01T01:00:00-05:00",
    "totalCost" : 0.326115,
    "accuracy" : 1.0,
    "items" : [ {
      "tariffRateId" : 2734,
      "tariffRateBandId" : 3258,
      "rateGroupName" : "Basic Service Charge",
      "rateName" : "Basic Service Charge",
      "fromDateTime" : "2011-12-01T00:00:00-05:00",
      "toDateTime" : "2011-12-01T01:00:00-05:00",
      "rateType" : "COST_PER_UNIT",
      "quantityKey" : "fixed",
      "itemQuantity" : 1.0,
      "itemCount" : 1,
      "cost" : 0.012097
    }, {
      "tariffRateId" : 16959920,
      "tariffRateBandId" : 10139634,
      "rateGroupName" : "Demand Side Management Residential Schedule",
      "rateName" : "Demand Side Management Residential Schedule",
      "fromDateTime" : "2011-12-01T00:00:00-05:00",
      "toDateTime" : "2011-12-01T01:00:00-05:00",
      "rateType" : "PERCENTAGE",
      "quantityKey" : "fixed",
      "itemQuantity" : 1.0,
      "itemCount" : 1,
      "cost" : .000008
    }, {
      "tariffRateId" : 2724,
      "tariffRateBandId" : 3248,
      "rateGroupName" : "Environmental Compliance Cost Recovery Schedule",
      "rateName" : "Environmental Compliance Cost Recovery Schedule",
      "fromDateTime" : "2011-12-01T00:00:00-05:00",
      "toDateTime" : "2011-12-01T01:00:00-05:00",
      "rateType" : "PERCENTAGE",
      "quantityKey" : "fixed",
      "itemQuantity" : 1.0,
      "itemCount" : 1,
      "cost" : .0000044
    }, {
      "tariffRateId" : 16968759,
      "tariffRateBandId" : 10147863,
      "rateGroupName" : "Municipal Franchise Fee Schedule",
      "rateName" : "Municipal Franchise Fee Schedule",
      "fromDateTime" : "2011-12-01T00:00:00-05:00",
      "toDateTime" : "2011-12-01T01:00:00-05:00",
      "rateType" : "PERCENTAGE",
      "quantityKey" : "QUANTITY",
      "itemQuantity" : 1.0,
      "itemCount" : 1,
      "cost" : .0000013,
      "rateAmount" : 2.9109
    }, {
      "tariffRateId" : 16959921,
      "tariffRateBandId" : 10139635,
      "rateGroupName" : "Nuclear Construction Cost Recovery Schedule",
      "rateName" : "Nuclear Construction Cost Recovery Schedule",
      "fromDateTime" : "2011-12-01T00:00:00-05:00",
      "toDateTime" : "2011-12-01T01:00:00-05:00",
      "rateType" : "PERCENTAGE",
      "quantityKey" : "fixed",
      "itemQuantity" : 1.0,
      "itemCount" : 1,
      "cost" : .0000028
    }, {
      "tariffRateId" : 2735,
      "tariffRateBandId" : 3259,
      "rateGroupName" : "Energy Charges",
      "rateName" : "Winter Energy Charges",
      "fromDateTime" : "2011-12-01T00:00:00-05:00",
      "toDateTime" : "2011-12-01T01:00:00-05:00",
      "rateType" : "COST_PER_UNIT",
      "quantityKey" : "consumption",
      "itemQuantity" : 6.2,
      "itemCount" : 1,
      "cost" : 0.313925
    }, {
      "tariffRateId" : 2737,
      "tariffRateBandId" : 3265,
      "rateGroupName" : "Minimum Charge",
      "rateName" : "Minimum Charge",
      "fromDateTime" : "2011-12-01T00:00:00-05:00",
      "toDateTime" : "2011-12-01T01:00:00-05:00",
      "rateType" : "COST_PER_UNIT",
      "quantityKey" : "minimum",
      "itemQuantity" : 1.0,
      "itemCount" : 1,
      "cost" : 0.0,
      "rateAmount" : 9.0
    } ]
  } ]
}

Example 3 - Calculate by passing in periods

In this example we pass in consumption data using periods. The first input specifies 3.1 kWh usage at midnight of each weekday. The second input specifies 2.6 kWh usage at midnight on the weekends. The fromDateTime and toDateTime of the consumption tariff inputs should be the overall date range of the calculation, and not specific to the dates in the period.

POST /rest/v1/calculate/512

Below is a sample POST request with the two tariffInputs populated.

{
    "fromDateTime" : "2011-12-01T00:00:00-05:00",
    "toDateTime" : "2012-01-01T00:00:00-05:00",
    "tariffInputs" : [ {
    "keyName" : "consumption",
    "fromDateTime" : "2011-12-01T00:00:00-0500",
    "toDateTime" : "2012-01-01T00:00:00-0500",
    "unit" : "kWh",
    "period":"1:5e 0H",
    "dataValue":"3.1"
  },
  {
    "keyName" : "consumption",
    "fromDateTime" : "2011-12-01T00:00:00-0500",
    "toDateTime" : "2012-01-01T00:00:00-0500",
    "unit" : "kWh",
    "period":"6:7e 0H",
    "dataValue":"2.6"
  } ]
}

Example 4 - Overriding rates with Rate Inputs, Incorporating Competitive Electric Supply

The calculate method accepts rates as inputs, allowing you to set a contracted rate amount on a deregulated tariff or, more generally, to model "what-if" scenarios with a tariff. A RateInput object has the same object structure as a TariffRate object - but with only the overridden fields required. At this time, we support overriding the rateAmount or the calculationFactor (a percentage applied against the rateAmount).

Overriding the rateAmount replaces the rate amounts for the tariff's rates which match the chargeClass (e.g. contracted, transmission, distribution) or chargeType (e.g. consumption, demand, fixed, other) of the passed-in rate. This allows you to set specific rates by chargeType and/or chargeClass, but keep the other rates associated to the tariff. For example, if you want to set the contracted supply rate for a tariff to $0.05 for a calculation, the following would be passed in:

POST /rest/v1/calculate/512
{
   "fromDateTime":"2011-01-01T00:00:00-05:00",
   "toDateTime":"2012-01-01T00:00:00-05:00",
   "tariffInputs":[
      {
         "keyName":"consumption",
         "dataValue":"1000"
      }
   ],
  "rateInputs":[
    {
         "fromDateTime":"2011-01-01T00:00:00-05:00",
         "toDateTime":"2012-01-01T00:00:00-05:00",
         "chargeClass":"CONTRACTED",
         "rateBands":[
            {
               "rateAmount":".05"
            }
         ]
      }
   ]
}

This call would result in the passed in $0.05 replacing all the contracted (also called bypassable) rates with the override rate amount provided. All non-contracted charges would continue to be calculated as before.

Overriding the calculation factor allows the user to model changes to rate amounts or apply discounts to the tariff during the calculation based on the chargeType or chargeClass. For example, to simulate the effect of a 10% increase in the consumption rate amounts, the following would be passed to the calculate method:

POST /rest/v1/calculate/512
{
   "fromDateTime":"2011-11-01T00:00:00-05:00",
   "toDateTime":"2012-01-01T00:00:00-05:00",
   "tariffInputs":[
      {
         "keyName":"consumption",
         "dataValue":"1000"
      }
   ],
  "rateInputs":[
    {
         "chargeType":"CONSUMPTION_BASED",
         "rateBands":[
            {
               "calculationFactor":"1.10"
            }
         ]
      }
   ]
}

Example 5 - Calculating Rates with Tax Inputs

Calculations can also be performed with tax rate inputs. Simply pass in the tax rate as a tariff rate input using the chargeType set to "TAX". Tax rates are calculated using the subtotal from the calculated amount. Either a rate percentage or specific rate dollar amount can be used. Optionally, you can set the rateName and rateGroup so the returned cost items can be broken out.

Example request with tax rate inputs

{
   "fromDateTime":"2013-06-01",
   "toDateTime":"2013-07-01",
   "tariffInputs":[
      {
         "keyName":"consumption",
         "dataValue":"1000"
      }
   ],
   "rateInputs":[
    {
         "rateGroupName":"Taxes",    
         "rateName":"Utility Users Tax",
         "fromDateTime":"2013-06-01",
         "toDateTime":"2013-07-01",
         "chargeType":"TAX",
         "rateBands":[
            {
               "rateAmount":".075",
               "rateUnit":"PERCENTAGE"
            }
         ]
      }
   ]
}

Example response. Item quantity reflects the subtotaled amount.

{
    "rateGroupName" : "Taxes",
    "rateName" : "Utility Users Tax",
    "rateSequenceNumber" : 100000,
    "fromDateTime" : "2013-06-01T00:00:00-04:00",
    "toDateTime" : "2013-07-01T00:00:00-04:00",
    "rateType" : "PERCENTAGE",
    "quantityKey" : "TAX",
    "itemQuantity" : 135.31,
    "rateAmount" : 0.075,
    "cost" : 10.148261
}

Example 6 - Solar Savings Analysis

Another way to use the cost calculator is to do a simple solar analysis. If you want to do a full-blown savings analysis, you can use the Savings Analysis endpoint, but the Cost Calculator will suffice if you're just interested in calculating cost.

To do the calculation, you pass in the profileId(s) that you are interested in calculating costs for. You can also pass in other arguments to override what is stored in the account. For instance, if you want to run an alternative tariff to the one set up in the account, pass in its masterTariffId. Lots of similar options are available.

Here are two very simple but common uses. The first is calculating electricity costs "before" solar for a year. The second is running the same calculation, but with a pre-existing PVWatts profile included to give "after" solar electricity costs. The difference between the two is the avoided cost.

POST /rest/v1/calculate/

For the "before" solar costs, call with this request body:

{
    "fromDateTime":"2012-01-01",
    "toDateTime":"2013-01-01",
    "detailLevel":"TOTAL",
    "groupBy":"MONTH",
    "tariffInputs":[
    {
        "keyName":"accountId",
        "dataValue":"c713dd5c-d2ad-4ad7-a064-45f00fbcbb9b"
    },
    {
        "keyName":"profileId",   // <== electricity profile
        "dataValue":"b5a252e5-1a2a-4670-a570-97e787c6e134"
    }]
}

Then for the "after" solar costs, call with this request body:

{
   "fromDateTime":"2012-05-01",
   "toDateTime":"2012-06-01",
   "detailLevel":"TOTAL",
   "groupBy":"MONTH",
   "tariffInputs":[
    {
        "keyName":"accountId",
        "dataValue":"c713dd5c-d2ad-4ad7-a064-45f00fbcbb9b"
    },
    {
        "keyName":"profileId", // <== usage profile
        "dataValue":"b5a252e5-1a2a-4670-a570-97e787c6e134"
    },
    {
        "keyName":"profileId", // <== pvWatts profile
        "dataValue":"4c459984-4c12-48bf-a200-ef83d0598409",
        "operator":"-"
    }]
}

Note the use of the operator field in the second example. This field tells the calculator how it should combine multiple profiles. The "-" in this case tells it to subtract the solar profile form the usage profile, resulting in net usage. The default operation when given multiple profiles is to add them (equivalent to passing "+" in the operator field).