On-demand Cost Calculation

Overview

The On-demand Cost Calculation endpoint calculates the cost of a service (e.g. Electricity, Natural Gas, Solar PV production) for a given tariff for a given amount of usage over a specified period of time. This can be used to calculate a past bill, to project month-to-date costs, to "what-if" different tariff rate plans and electives, or to compare changes in electricity or other usage.

To run the calculation, the endpoint 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.

Data Definitions

Calculated Cost

The CalculatedCost object contains the results of the calculation. The totalCost field holds the overall cost while the details of the calculation are contained within a list of Calculated Cost Item(s).

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.
accuracy Decimal [0,100] M A decimal value between 0 and 100 representing the accuracy of the calculation. As more "best guess" assumptions are made, the calculation will become less accurate and the accuracy field will be smaller.
currency String The currency represented in the calculation.
summary Map Summary of cost and resource totals.
items Array of CalculatedCostItem M Breakdown of the summary data with variable granularity and grouping.
assumptions Array of PropertyData The properties, modeling assumptions, and other key info used in the calculation.
calculatedCostId String M Unique identifier for this calculation.
{
    "masterTariffId": 522,
    "tariffName": "Residential",
    "totalCost": 198.35,
    "fromDateTime": "2013-12-01T00:00:00-08:00",
    "toDateTime": "2014-01-01T00:00:00-08:00",
    "accuracy": 1,
    "currency": "USD",
    "summary": {
        "subTotalCost": 198.35,
        "taxCost": 0,
        "totalCost": 198.35,
        "adjustedTotalCost": 198.64,
        "kWh": 1000,
        "kW": 0
    },
    "items": [...],
    "assumptions": [...],
    "calculatedCostId": "67afe5d7-19f1-4c35-8e83-6868f6402da8",
}

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.

Name Type Fields Description
tariffId Long E Unique Genability ID for the tariff associated with this cost item.
tariffRateId Long M Unique Genability ID for 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, and demand.
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). BLOCK and BLOCK_SELL_BACK are also supported. See Block and Index Rates
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.
tierUpperLimit Decimal E For a tiered rate, the maximum quantity at which this tier is invoked.
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 Decimal E The amount this rate is being prorated compared to the full rate amount.
chargeType String The type of rate: CONSUMPTION_BASED, DEMAND_BASED, FIXED_TYPE, QUANTITY, MINIMUM, TAX or NET_EXCESS_GENERATION.
chargeClass String The class of rate: TRANSMISSION, DISTRIBUTION, SUPPLY, TAX, CONTRACTED, USER_ADJUSTED, AFTER_TAX, or OTHER.
period String M The Time of Use type: OFF_PEAK, PARTIAL_PEAK, ON_PEAK or CRITICAL_PEAK.
demandInterval DateTime M For demand charges, the time from which demand is measured.
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)
formula String E The formula associated with the quantityKey.
transactionType Enumeration E Transaction type categories: BUY, SELL, NET, BUY_IMPORT or SELL_EXPORT
{
  "tariffId": 3163175,
  "tariffRateId": 17091206,
  "tariffRateBandId": 10341335,
  "rateSequenceNumber": 3,
  "rateGroupName": "Transmission",
  "rateName": "Reliability Service Charge",
  "fromDateTime": "2013-12-01T00:00:00-08:00",
  "toDateTime": "2014-01-01T00:00:00-08:00",
  "quantityKey": "consumption",
  "rateType": "COST_PER_UNIT",
  "rateAmount": -0.00015,
  "itemQuantity": 1000,
  "cost": -0.15,
  "chargeType": "CONSUMPTION_BASED"
}

Property Data

Property data is both an input object and an ouput value for our calculation-related endpoints.

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 (Required)
displayName String M A display-friendly name for this property. (Output only)
description String E A text description of this property. (Output only)
fromDateTime DateTime M The start of the period where this property is applicable.
(Optional, Default= fromDateTime for the calculation request)
toDateTime DateTime M The end of the period where this property is applicable.
(Optional, Default= toDateTime for the calculation request)
period String M The Time of Use type: OFF_PEAK, PARTIAL_PEAK, ON_PEAK or CRITICAL_PEAK.
As input, can alternatively be specified as a Date Period
dataType Enumeration M The type of this property. Possible values are: STRING, CHOICE, BOOLEAN, DATE, DECIMAL, INTEGER, and FORMULA (Output only)
dataValue String M The value of this Property. Can be input as the native type for the property. Always returned as a string. (Required if not using dataSeries)
dataSeries Array of Decimal Used for properties which have many values, such as consumption time series data. (Required if not using dataValue)
duration Integer Used with dataSeries to specify the time span corresponding to each value in the dataSeries. (Required if using dataSeries)
dataFactor Decimal For applicable properties (like usage data) scales the inputs by the value provided (Optional, Input Only)
operator Enumeration For profile data only. Specifies how profiles should be joined. Possible values are + and -.
unit String M Where applicable, this is the unit of the value. Most common are: "kWh" - for keys of consumption, "kW" - for keys of demand. (Optional)
accuracy Decimal [0,100] M Estimated accuracy of the property value. Properties which you set explicitly will have an accuracy value of 100. (Output only)

As an input, you will use PropertyData to set calculation assumptions via the propertyInputs parameter. For example, you might set a property to produce costs assuming the customer is in the "SmartRate" program:

"propertyInputs": [
    {
        "keyName": "isSmartRateCustomer",
        "dataValue": true
    }, 
    ...
]

As an output, PropertyData tells you what assumptions were made for a particular calculation and what information might be required for a future calculation. When you call one of the calculation endpoints, the Calculated Cost object contains an array of PropertyData assigned to the assumptions field:

"assumptions": [
    {
      "keyName": "isSmartRateCustomer",
      "displayName": "Is SmartRate Customer",
      "description": "The residential SmartRate program is a voluntary rate supplement to the customer's \r\notherwise applicable rate schedule (OAS).\r\nThe customer will be billed for all regular charges applicable under the customer's OAS.  \r\nAdditional charges (based on usage during SmartDay High-Price Periods) and \r\nSmartRate credits will be determined according to the rates specified in this schedule.  The customer must have a SmartMeter system to participate in the residential \r\nSmartRate program",
      "fromDateTime": "2013-01-01T00:00:00-08:00",
      "toDateTime": "2014-01-01T00:00:00-08:00",
      "dataType": "BOOLEAN",
      "dataValue": "true",
      "accuracy": 100 // implies this property was either passed in explicitly or must be true contextually
    }, 
    ...
]

Address

Used to find the appropriate tax when doing a calculation with utility tax.

Name Type Description
addressString String Full free text string representing address. This is the property that is usually passed in. Zip will suffice but the full address is better.
addressName String A name associated with the address (e.g. Headquarters). Not usually set.
address1 String First part of the address. Usually populated by our address validation from the addressString passed in.
address2 String Second part of the address. Usually populated by our address validation from the addressString passed in.
city String City of the address. Usually populated by our address validation from the addressString passed in.
state String State of the address. Usually populated by our address validation from the addressString passed in.
zip String Postcode or ZIP code of the address. Usually populated by our address validation from the addressString passed in.
country String Usually the ISO Country Code of the address. Usually populated by our address validation from the addressString passed in.
lon Double Longitude of the address. We'll populate this by geo-tagging the address.
lat Double Latitude of the address. We'll populate this by geo-tagging the address.

Request ID

In the top level response object a requestId field is returned from this request. The requestId value is generated randomly for each request. The primary use case of the requestId is to submit it along with a support ticket when there is a question regarding a particular calculation result.

{
  "status": "success",
  "count": 1,
  "type": "CalculatedCost",
  "requestId": "b9418ae1-af32-473a-b86a-b308fdbd48d1",
  "results": [...]
}

Operations

Run a Calculation

To run a new calculation, you will POST a payload containing the calculation criteria and inputs, and a CalculatedCost object will be returned.

Resource URI

POST /rest/v1/ondemand/calculate

Request Parameters

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

Name Type Description
masterTariffId Long Unique Genability ID for the master tariff of this tariff version. (Required)
fromDateTime DateTime Starting date and time for this calculation. (Required)
toDateTime DateTime End date and time for this calculation. (Required)
propertyInputs Array of PropertyData This is where you'll specify the usage data and applicabilities for the calculation.
expected Map Set expectations on calculation results (totalCost, adjustedTotalCost, kWh, kW) to enable accuracy validation. (Optional) See an example
billingPeriod Boolean 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. (Optional, Default=false)
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)
minimums Boolean This field enables enforcing minimum charges on this calculation. (Optional, Default=false)
excludeChargeClass String Specifies a charge class to exclude from the calculation results. (Optional)
applyUtilityTax Boolean When true, the calculation attempts to apply a utility tax to the provided address. (Optional, Default = true when address provided, false otherwise)
address Address Specifies the location in which to apply a utility tax when applyUtilityTax is true. (Required if applyUtilityTax = true)
calcNetExcessGeneration Boolean This field includes net metering totals in the summary section of the calculation. (Optional, Default=false)
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. (Optional)
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)

Examples

Example 1 - Calculate last month's bill

Example where you pass in the tariff and usage data for last month's billing period. In this case the usage data is hourly consumption numbers, passed in as a contiguous data series.

Request

POST /rest/v1/ondemand/calculate
{
  "fromDateTime": "2016-07-13T00:00:00-07:00",
  "toDateTime": "2016-08-11T00:00:00-07:00",
  "masterTariffId": 522,
  "groupBy": "MONTH",
  "detailLevel": "RATE",
  "billingPeriod": true,
  "propertyInputs": [{
    "keyName": "consumption",
    "fromDateTime": "2016-07-13T00:00:00-07:00",
    "duration": 3600000,
    "dataSeries": [ 1.58, 1.58, 1.58, 1.58, 1.59, 1.60, 1.61, 1.62, 1.63, 1.63, 1.64, 1.64, 1.66, 1.68, 1.70, 1.73, 1.75, 1.76, 1.78, 1.80, 1.80, 1.81, 1.81, 1.81, 1.84, 1.88, 1.91, 1.95, 1.97, 1.98, 2.00, 2.01, 2.02, 2.03, 2.04, 2.05, 2.06, 2.07, 2.08, 2.09, 2.09, 2.11, 2.12, 2.13, 2.13, 2.11, 2.09, 2.08, 2.07, 2.05, 2.03, 2.02, 2.01, 2.01, 2.01, 2.01, 2.02, 2.02, 2.03, 2.04, 2.02, 1.99, 1.96, 1.92, 1.90, 1.89, 1.88, 1.86, 1.85, 1.83, 1.82, 1.79, 1.77, 1.74, 1.71, 1.67, 1.65, 1.63, 1.61, 1.60, 1.58, 1.55, 1.53, 1.51, 1.51, 1.51, 1.52, 1.52, 1.54, 1.56, 1.58, 1.60, 1.60, 1.59, 1.58, 1.58, 1.58, 1.59, 1.59, 1.60, 1.61, 1.63, 1.65, 1.67, 1.67, 1.67, 1.67, 1.67, 1.69, 1.72, 1.74, 1.77, 1.78, 1.79, 1.79, 1.80, 1.80, 1.79, 1.79, 1.78, 1.81, 1.85, 1.89, 1.94, 1.96, 1.97, 1.98, 2.00, 2.01, 2.02, 2.04, 2.05, 2.06, 2.06, 2.07, 2.07, 2.08, 2.09, 2.11, 2.12, 2.12, 2.12, 2.12, 2.12, 2.12, 2.11, 2.09, 2.08, 2.08, 2.08, 2.08, 2.08, 2.07, 2.07, 2.06, 2.05, 2.03, 2.00, 1.97, 1.94, 1.91, 1.90, 1.88, 1.86, 1.84, 1.83, 1.82, 1.81, 1.78, 1.74, 1.70, 1.66, 1.65, 1.64, 1.64, 1.63, 1.61, 1.57, 1.54, 1.51, 1.51, 1.51, 1.52, 1.52, 1.54, 1.56, 1.58, 1.60, 1.60, 1.59, 1.58, 1.57, 1.54, 1.54, 1.54, 1.54, 1.55, 1.56, 1.56, 1.57, 1.58, 1.57, 1.57, 1.57, 1.58, 1.61, 1.63, 1.65, 1.68, 1.71, 1.73, 1.76, 1.78, 1.79, 1.80, 1.81, 1.83, 1.85, 1.88, 1.90, 1.91, 1.92, 1.92, 1.93, 1.93, 1.93, 1.92, 1.91, 1.92, 1.93, 1.93, 1.94, 1.95, 1.97, 1.99, 2.01, 2.01, 2.00, 1.99, 1.98, 1.97, 1.97, 1.96, 1.96, 1.96, 1.95, 1.95, 1.94, 1.95, 1.96, 1.97, 1.98, 1.97, 1.96, 1.94, 1.92, 1.90, 1.89, 1.87, 1.86, 1.84, 1.81, 1.79, 1.76, 1.74, 1.72, 1.71, 1.69, 1.66, 1.64, 1.61, 1.58, 1.56, 1.54, 1.52, 1.49, 1.48, 1.49, 1.49, 1.50, 1.52, 1.53, 1.55, 1.57, 1.57, 1.56, 1.55, 1.53, 1.51, 1.51, 1.52, 1.52, 1.53, 1.53, 1.54, 1.55, 1.55, 1.55, 1.55, 1.55, 1.56, 1.58, 1.61, 1.62, 1.65, 1.67, 1.70, 1.73, 1.74, 1.74, 1.75, 1.76, 1.77, 1.80, 1.82, 1.85, 1.86, 1.86, 1.86, 1.86, 1.86, 1.86, 1.85, 1.85, 1.85, 1.86, 1.86, 1.87, 1.88, 1.90, 1.91, 1.93, 1.93, 1.92, 1.91, 1.90, 1.90, 1.89, 1.89, 1.88, 1.88, 1.88, 1.88, 1.87, 1.88, 1.90, 1.91, 1.93, 1.92, 1.90, 1.88, 1.86, 1.85, 1.84, 1.83, 1.82, 1.80, 1.78, 1.76, 1.73, 1.71, 1.69, 1.68, 1.66, 1.64, 1.61, 1.58, 1.55, 1.52, 1.50, 1.48, 1.46, 1.46, 1.46, 1.47, 1.47, 1.49, 1.51, 1.53, 1.55, 1.54, 1.53, 1.52, 1.50, 1.48, 1.48, 1.49, 1.50, 1.51, 1.51, 1.52, 1.52, 1.52, 1.52, 1.52, 1.52, 1.54, 1.56, 1.58, 1.60, 1.62, 1.64, 1.66, 1.69, 1.70, 1.70, 1.70, 1.70, 1.72, 1.74, 1.77, 1.79, 1.80, 1.80, 1.80, 1.80, 1.80, 1.79, 1.79, 1.78, 1.78, 1.79, 1.79, 1.80, 1.81, 1.82, 1.83, 1.85, 1.85, 1.84, 1.83, 1.83, 1.82, 1.82, 1.81, 1.80, 1.80, 1.80, 1.80, 1.80, 1.82, 1.83, 1.85, 1.87, 1.86, 1.85, 1.83, 1.81, 1.80, 1.79, 1.79, 1.78, 1.76, 1.74, 1.73, 1.71, 1.69, 1.67, 1.65, 1.63, 1.61, 1.57, 1.54, 1.51, 1.49, 1.47, 1.45, 1.43, 1.43, 1.44, 1.44, 1.45, 1.46, 1.48, 1.50, 1.52, 1.52, 1.51, 1.49, 1.49, 1.52, 1.53, 1.53, 1.54, 1.55, 1.55, 1.56, 1.56, 1.57, 1.57, 1.57, 1.57, 1.58, 1.60, 1.62, 1.64, 1.66, 1.68, 1.70, 1.73, 1.73, 1.73, 1.74, 1.74, 1.76, 1.78, 1.80, 1.83, 1.84, 1.84, 1.84, 1.85, 1.84, 1.84, 1.83, 1.83, 1.83, 1.83, 1.84, 1.85, 1.86, 1.86, 1.88, 1.89, 1.89, 1.88, 1.87, 1.86, 1.86, 1.85, 1.85, 1.84, 1.84, 1.84, 1.84, 1.84, 1.85, 1.87, 1.88, 1.90, 1.89, 1.88, 1.86, 1.84, 1.83, 1.82, 1.82, 1.81, 1.79, 1.77, 1.75, 1.73, 1.71, 1.69, 1.68, 1.66, 1.63, 1.60, 1.57, 1.55, 1.52, 1.50, 1.48, 1.46, 1.46, 1.47, 1.48, 1.48, 1.50, 1.52, 1.54, 1.55, 1.56, 1.54, 1.53, 1.54, 1.57, 1.57, 1.58, 1.58, 1.59, 1.59, 1.60, 1.60, 1.61, 1.61, 1.61, 1.61, 1.62, 1.64, 1.66, 1.68, 1.70, 1.72, 1.74, 1.76, 1.76, 1.77, 1.77, 1.78, 1.79, 1.82, 1.84, 1.86, 1.88, 1.88, 1.88, 1.89, 1.89, 1.88, 1.88, 1.88, 1.88, 1.88, 1.88, 1.89, 1.90, 1.91, 1.92, 1.93, 1.93, 1.91, 1.91, 1.90, 1.89, 1.89, 1.89, 1.88, 1.88, 1.88, 1.88, 1.88, 1.89, 1.90, 1.92, 1.93, 1.92, 1.91, 1.89, 1.87, 1.86, 1.85, 1.85, 1.84, 1.82, 1.80, 1.78, 1.76, 1.74, 1.72, 1.70, 1.68, 1.66, 1.63, 1.61, 1.58, 1.56, 1.54, 1.52, 1.49, 1.49, 1.50, 1.51, 1.52, 1.53, 1.55, 1.57, 1.59, 1.59, 1.58, 1.58, 1.57, 1.58, 1.58, 1.58, 1.58, 1.59, 1.60, 1.62, 1.63, 1.64, 1.64, 1.63, 1.63, 1.64, 1.67, 1.70, 1.73, 1.74, 1.76, 1.77, 1.78, 1.79, 1.79, 1.78, 1.78, 1.80, 1.83, 1.86, 1.90, 1.91, 1.92, 1.92, 1.93, 1.93, 1.94, 1.94, 1.95, 1.96, 1.97, 1.98, 1.99, 1.99, 2.01, 2.01, 2.02, 2.02, 2.01, 2.01, 2.00, 2.00],
    "unit":"kWh"
  }]
}

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",
  "requestId": "92f92a95-7cd3-43d7-b514-8617ca8c5ee0",
  "results": [
    {
      "masterTariffId": 522,
      "tariffName": "Residential",
      "totalCost": 336.2,
      "fromDateTime": "2016-07-13T00:00:00-07:00",
      "toDateTime": "2016-08-11T00:00:00-07:00",
      "currency": "USD",
      "summary": {
        "subTotalCost": 336.2,
        "taxCost": 0,
        "totalCost": 336.2,
        "adjustedTotalCost": 336.55,
        "kWh": 1217.68,
        "kW": 0
      },
      "accuracy": 1,
      "items": [
        {
          "tariffRateId": 17565366,
          "tariffRateBandId": 11063709,
          "rateSequenceNumber": 17,
          "rateGroupName": "Conservation Incentive Adjustment",
          "rateName": "Conservation Incentive Adjustment  (Summer - Territory P)",
          "fromDateTime": "2016-07-13T00:00:00-07:00",
          "toDateTime": "2016-08-11T00:00:00-07:00",
          "quantityKey": "consumption",
          "rateType": "COST_PER_UNIT",
          "rateAmount": 0.04852916,
          "itemQuantity": 1217.68,
          "cost": 59.09298755,
          "chargeType": "CONSUMPTION_BASED",
          "chargeClass": "DISTRIBUTION"
        },
        {
          "tariffRateId": 17565386,
          "tariffRateBandId": 11063805,
          "rateSequenceNumber": 18,
          "rateGroupName": "Generation",
          "rateName": "Generation Charge",
          "fromDateTime": "2016-07-13T00:00:00-07:00",
          "toDateTime": "2016-08-11T00:00:00-07:00",
          "quantityKey": "consumption",
          "rateType": "COST_PER_UNIT",
          "rateAmount": 0.09684,
          "itemQuantity": 1217.68,
          "cost": 117.9201312,
          "chargeType": "CONSUMPTION_BASED",
          "chargeClass": "SUPPLY"
        },
        {
          "tariffRateId": 17565389,
          "tariffRateBandId": 11063808,
          "rateSequenceNumber": 19,
          "rateGroupName": "Transmission",
          "rateName": "Reliability Service Charge",
          "fromDateTime": "2016-07-13T00:00:00-07:00",
          "toDateTime": "2016-08-11T00:00:00-07:00",
          "quantityKey": "consumption",
          "rateType": "COST_PER_UNIT",
          "rateAmount": 0.00023,
          "itemQuantity": 1217.68,
          "cost": 0.2800664,
          "chargeType": "CONSUMPTION_BASED",
          "chargeClass": "TRANSMISSION"
        },
        {
          "tariffRateId": 17565387,
          "tariffRateBandId": 11063806,
          "rateSequenceNumber": 19,
          "rateGroupName": "Transmission",
          "rateName": "Transmission",
          "fromDateTime": "2016-07-13T00:00:00-07:00",
          "toDateTime": "2016-08-11T00:00:00-07:00",
          "quantityKey": "consumption",
          "rateType": "COST_PER_UNIT",
          "rateAmount": 0.02144,
          "itemQuantity": 1217.68,
          "cost": 26.1070592,
          "chargeType": "CONSUMPTION_BASED",
          "chargeClass": "TRANSMISSION"
        },
        {
          "tariffRateId": 17565388,
          "tariffRateBandId": 11063807,
          "rateSequenceNumber": 19,
          "rateGroupName": "Transmission",
          "rateName": "Transmission Rate Adjustments",
          "fromDateTime": "2016-07-13T00:00:00-07:00",
          "toDateTime": "2016-08-11T00:00:00-07:00",
          "quantityKey": "consumption",
          "rateType": "COST_PER_UNIT",
          "rateAmount": 0.0001,
          "itemQuantity": 1217.68,
          "cost": 0.121768,
          "chargeType": "CONSUMPTION_BASED",
          "chargeClass": "TRANSMISSION"
        },
        {
          "tariffRateId": 17565391,
          "tariffRateBandId": 11063810,
          "rateSequenceNumber": 20,
          "rateGroupName": "Distribution",
          "rateName": "Distribution Charge",
          "fromDateTime": "2016-07-13T00:00:00-07:00",
          "toDateTime": "2016-08-11T00:00:00-07:00",
          "quantityKey": "consumption",
          "rateType": "COST_PER_UNIT",
          "rateAmount": 0.08339,
          "itemQuantity": 1217.68,
          "cost": 101.5423352,
          "chargeType": "CONSUMPTION_BASED",
          "chargeClass": "DISTRIBUTION"
        },
        {
          "tariffRateId": 17565390,
          "tariffRateBandId": 11063809,
          "rateSequenceNumber": 20,
          "rateGroupName": "Distribution",
          "rateName": "New System Generation Charge",
          "fromDateTime": "2016-07-13T00:00:00-07:00",
          "toDateTime": "2016-08-11T00:00:00-07:00",
          "quantityKey": "consumption",
          "rateType": "COST_PER_UNIT",
          "rateAmount": 0.00255,
          "itemQuantity": 1217.68,
          "cost": 3.105084,
          "chargeType": "CONSUMPTION_BASED",
          "chargeClass": "DISTRIBUTION"
        },
        {
          "tariffRateId": 17565392,
          "tariffRateBandId": 11063811,
          "rateSequenceNumber": 21,
          "rateGroupName": "Public Purpose Programs",
          "rateName": "Public Purpose Programs",
          "fromDateTime": "2016-07-13T00:00:00-07:00",
          "toDateTime": "2016-08-11T00:00:00-07:00",
          "quantityKey": "consumption",
          "rateType": "COST_PER_UNIT",
          "rateAmount": 0.01405,
          "itemQuantity": 1217.68,
          "cost": 17.108404,
          "chargeType": "CONSUMPTION_BASED",
          "chargeClass": "DISTRIBUTION"
        },
        {
          "tariffRateId": 17565393,
          "tariffRateBandId": 11063812,
          "rateSequenceNumber": 22,
          "rateGroupName": "Nuclear Decommissioning",
          "rateName": "Nuclear Decommissioning",
          "fromDateTime": "2016-07-13T00:00:00-07:00",
          "toDateTime": "2016-08-11T00:00:00-07:00",
          "quantityKey": "consumption",
          "rateType": "COST_PER_UNIT",
          "rateAmount": 0.00022,
          "itemQuantity": 1217.68,
          "cost": 0.2678896,
          "chargeType": "CONSUMPTION_BASED",
          "chargeClass": "DISTRIBUTION"
        },
        {
          "tariffRateId": 17565394,
          "tariffRateBandId": 11063813,
          "rateSequenceNumber": 23,
          "rateGroupName": "DWR Bond Charge",
          "rateName": "DWR Bond Charge",
          "fromDateTime": "2016-07-13T00:00:00-07:00",
          "toDateTime": "2016-08-11T00:00:00-07:00",
          "quantityKey": "consumption",
          "rateType": "COST_PER_UNIT",
          "rateAmount": 0.00539,
          "itemQuantity": 1217.68,
          "cost": 6.5632952,
          "chargeType": "CONSUMPTION_BASED",
          "chargeClass": "DISTRIBUTION"
        },
        {
          "tariffRateId": 17565395,
          "tariffRateBandId": 11063814,
          "rateSequenceNumber": 24,
          "rateGroupName": "Ongoing CTC",
          "rateName": "Ongoing CTC",
          "fromDateTime": "2016-07-13T00:00:00-07:00",
          "toDateTime": "2016-08-11T00:00:00-07:00",
          "quantityKey": "consumption",
          "rateType": "COST_PER_UNIT",
          "rateAmount": 0.00338,
          "itemQuantity": 1217.68,
          "cost": 4.1157584,
          "chargeType": "CONSUMPTION_BASED",
          "chargeClass": "DISTRIBUTION"
        },
        {
          "tariffRateId": 17565396,
          "tariffRateBandId": 11063815,
          "rateSequenceNumber": 25,
          "rateGroupName": "Energy Cost Recovery Amount",
          "rateName": "Energy Cost Recovery Amount",
          "fromDateTime": "2016-07-13T00:00:00-07:00",
          "toDateTime": "2016-08-11T00:00:00-07:00",
          "quantityKey": "consumption",
          "rateType": "COST_PER_UNIT",
          "rateAmount": -0.00002,
          "itemQuantity": 1217.68,
          "cost": -0.0243536,
          "chargeType": "CONSUMPTION_BASED",
          "chargeClass": "DISTRIBUTION"
        },
        {
          "tariffRateId": 17565397,
          "tariffRateBandId": 11063817,
          "rateSequenceNumber": 26,
          "rateGroupName": "Greenhouse Gas Volumetric Return",
          "rateName": "Greenhouse Gas Volumetric Return (Summer - Territory P)",
          "fromDateTime": "2016-07-13T00:00:00-07:00",
          "toDateTime": "2016-08-11T00:00:00-07:00",
          "quantityKey": "consumption",
          "rateType": "COST_PER_UNIT",
          "rateAmount": 0,
          "itemQuantity": 1217.68,
          "cost": 0,
          "chargeType": "CONSUMPTION_BASED",
          "chargeClass": "DISTRIBUTION"
        },
        {
          "tariffRateId": 17368253,
          "tariffRateBandId": 10770115,
          "rateSequenceNumber": 30,
          "rateGroupName": "Energy Surcharge",
          "rateName": "Energy Surcharge",
          "fromDateTime": "2016-07-13T00:00:00-07:00",
          "toDateTime": "2016-08-11T00:00:00-07:00",
          "quantityKey": "consumption",
          "rateType": "COST_PER_UNIT",
          "rateAmount": 0.00029,
          "itemQuantity": 1217.68,
          "cost": 0.3531272,
          "chargeType": "CONSUMPTION_BASED",
          "chargeClass": "AFTER_TAX"
        },
        {
          "tariffRateId": 17492212,
          "tariffRateBandId": 10994649,
          "rateSequenceNumber": 32,
          "rateGroupName": "Green Tariff (GT) Program Charges",
          "rateName": "Generation Credit",
          "fromDateTime": "2016-07-13T00:00:00-07:00",
          "toDateTime": "2016-08-11T00:00:00-07:00",
          "quantityKey": "consumption",
          "rateType": "COST_PER_UNIT",
          "rateAmount": 0,
          "itemQuantity": 1217.68,
          "cost": 0,
          "chargeType": "CONSUMPTION_BASED",
          "chargeClass": "DISTRIBUTION"
        },
        {
          "tariffRateId": 17492214,
          "tariffRateBandId": 10994653,
          "rateSequenceNumber": 32,
          "rateGroupName": "Green Tariff (GT) Program Charges",
          "rateName": "PCIA",
          "fromDateTime": "2016-07-13T00:00:00-07:00",
          "toDateTime": "2016-08-11T00:00:00-07:00",
          "quantityKey": "consumption",
          "rateType": "COST_PER_UNIT",
          "rateAmount": 0,
          "itemQuantity": 1217.68,
          "cost": 0,
          "chargeType": "CONSUMPTION_BASED",
          "chargeClass": "DISTRIBUTION"
        },
        {
          "tariffRateId": 17492213,
          "tariffRateBandId": 10994651,
          "rateSequenceNumber": 32,
          "rateGroupName": "Green Tariff (GT) Program Charges",
          "rateName": "Program Charge",
          "fromDateTime": "2016-07-13T00:00:00-07:00",
          "toDateTime": "2016-08-11T00:00:00-07:00",
          "quantityKey": "consumption",
          "rateType": "COST_PER_UNIT",
          "rateAmount": 0,
          "itemQuantity": 1217.68,
          "cost": 0,
          "chargeType": "CONSUMPTION_BASED",
          "chargeClass": "DISTRIBUTION"
        },
        {
          "tariffRateId": 17492211,
          "tariffRateBandId": 10994647,
          "rateSequenceNumber": 32,
          "rateGroupName": "Green Tariff (GT) Program Charges",
          "rateName": "Solar Charge",
          "fromDateTime": "2016-07-13T00:00:00-07:00",
          "toDateTime": "2016-08-11T00:00:00-07:00",
          "quantityKey": "consumption",
          "rateType": "COST_PER_UNIT",
          "rateAmount": 0,
          "itemQuantity": 1217.68,
          "cost": 0,
          "chargeType": "CONSUMPTION_BASED",
          "chargeClass": "DISTRIBUTION"
        },
        {
          "tariffRateId": 17565451,
          "tariffRateBandId": 11063917,
          "rateSequenceNumber": 33,
          "rateGroupName": "California Climate Credit",
          "rateName": "California Climate Credit",
          "fromDateTime": "2016-07-13T00:00:00-07:00",
          "toDateTime": "2016-08-11T00:00:00-07:00",
          "quantityKey": "fixed",
          "rateType": "COST_PER_UNIT",
          "rateAmount": 0,
          "itemQuantity": 0,
          "cost": 0,
          "chargeType": "FIXED_PRICE",
          "chargeClass": "AFTER_TAX"
        }
      ],
      "assumptions": [
        {
          "keyName": "tariffId",
          "dataType": "INTEGER",
          "fromDateTime": "2016-07-13T00:00:00-07:00",
          "toDateTime": "2016-08-11T00:00:00-07:00",
          "dataValue": "3258081"
        },
        {
          "keyName": "territoryId",
          "dataType": "INTEGER",
          "fromDateTime": "2016-07-13T00:00:00-07:00",
          "toDateTime": "2016-08-11T00:00:00-07:00",
          "dataValue": "3534",
          "accuracy": 80
        },
        {
          "keyName": "dailyMedicalAllowance",
          "displayName": "Daily Medical Allowance ",
          "description": "Residential customers on a medical allowance get additional quantities of energy at the lowest (baseline) price. The medical allowance is a daily value. ",
          "dataType": "DECIMAL",
          "fromDateTime": "2016-07-13T00:00:00-07:00",
          "toDateTime": "2016-08-11T00:00:00-07:00",
          "dataValue": "0",
          "accuracy": 80
        },
        {
          "keyName": "hasCAEnergySurchargeExemption",
          "displayName": "Has Energy Surcharge Exemption",
          "description": "Exemptions for CA Energy Surcharge apply to the following:\r\n1. Federal Agencies\r\n2. American National Red Cross facilities\r\n3. Energy consumed on Indian reservations\r\n4. Foreign consular employees\r\n5. Federal Credit Unions",
          "dataType": "BOOLEAN",
          "fromDateTime": "2016-07-13T00:00:00-07:00",
          "toDateTime": "2016-08-11T00:00:00-07:00",
          "dataValue": "false",
          "accuracy": 80
        },
        {
          "keyName": "smartMeterOptOut",
          "displayName": "Has Smart Meter Opt-Out",
          "description": "Customers  who elect to opt-out of receiving a smart meter and choose to retain a non-smart meter, are subject to the Smart Meter Opt-Out fees.\r\n\r\nSmart Meter Opt-Out Customers are subject to one-time, up-front fee and a recurring monthly fee ",
          "dataType": "BOOLEAN",
          "fromDateTime": "2016-07-13T00:00:00-07:00",
          "toDateTime": "2016-08-11T00:00:00-07:00",
          "dataValue": "false",
          "accuracy": 80
        },
        {
          "keyName": "isSmartRateCustomer",
          "displayName": "Is SmartRate Customer",
          "description": "The residential SmartRate program is a voluntary rate supplement to the customer's \r\notherwise applicable rate schedule (OAS).\r\nThe customer will be billed for all regular charges applicable under the customer's OAS.  \r\nAdditional charges (based on usage during SmartDay High-Price Periods) and \r\nSmartRate credits will be determined according to the rates specified in this schedule.  The customer must have a SmartMeter system to participate in the residential \r\nSmartRate program",
          "dataType": "BOOLEAN",
          "fromDateTime": "2016-07-13T00:00:00-07:00",
          "toDateTime": "2016-08-11T00:00:00-07:00",
          "dataValue": "false",
          "accuracy": 80
        },
        {
          "keyName": "utilityEmployee",
          "displayName": "Is Utility Employee",
          "description": "Applicable to domestic service utility employees ",
          "dataType": "BOOLEAN",
          "fromDateTime": "2016-07-13T00:00:00-07:00",
          "toDateTime": "2016-08-11T00:00:00-07:00",
          "dataValue": "false",
          "accuracy": 80
        },
        {
          "keyName": "powerChargeIndifferenceAdjustmentVintageYear",
          "displayName": "Power Charge Indifference Adjustment  Vintage Year ",
          "description": "The adjustment (either a \r\ncharge or credit) is intended to ensure that customers that purchase electricity from \r\nnon-utility suppliers pay their share of cost for generation acquired prior to 2003",
          "dataType": "STRING",
          "fromDateTime": "2016-07-13T00:00:00-07:00",
          "toDateTime": "2016-08-11T00:00:00-07:00",
          "dataValue": "None",
          "accuracy": 80
        },
        {
          "keyName": "solarChoiceCustomerCategory",
          "displayName": "Solar Choice Customer Category",
          "description": "The customer is a solar choice customer  taking service under Schedule E-GT. The customer will pay the applicable Program Charge based on the year service under this schedule was started. ",
          "dataType": "STRING",
          "fromDateTime": "2016-07-13T00:00:00-07:00",
          "toDateTime": "2016-08-11T00:00:00-07:00",
          "dataValue": "None",
          "accuracy": 80
        }
      ],
      "calculatedCostId": "1212281e-d0cd-4a4c-b785-be152022d456"
    }
  ]
}

Example 2 - Calculate with expected values

This example passes in values for Total Cost, Adjusted Total Cost and Total kWh (typically comes from the billing data or CIS system). This triggers Signal's real-time calculation QA process. Note that the consumption input is set as a single value, not a series like the previous example.

Request

POST /rest/v1/ondemand/calculate
{
  "fromDateTime": "2016-07-10T00:00:00-05:00",
  "toDateTime": "2016-08-12T00:00:00-05:00",
  "masterTariffId": 512,
  "groupBy": "ALL",
  "detailLevel": "TOTAL",
  "billingPeriod": true,
  "minimums": true,
  "expected": {
    "totalCost": 170.20,
    "adjustedTotalCost":170.18,
    "kWh": 1266.48
  },
  "propertyInputs": [
  {
    "keyName" : "consumption",
    "unit" : "kWh",
    "dataValue" : 1266.48
  },
  {
    "keyName" : "cityLimits",
    "dataValue" : "Inside"
  },
  { 
    "keyName" : "isLowIncomeSeniorCitizen953",
    "dataValue" : false
  }]
}

Response

{
  "status": "success",
  "count": 1,
  "type": "CalculatedCost",
  "requestId": "d0c96efc-7058-40f8-802b-48f6480ae411",
  "results": [
    {
      "masterTariffId": 512,
      "tariffName": "Residential",
      "totalCost": 170.22,
      "fromDateTime": "2016-07-10T01:00:00-04:00",
      "toDateTime": "2016-08-12T01:00:00-04:00",
      "currency": "USD",
      "summary": {
        "subTotalCost": 170.22,
        "taxCost": 0,
        "totalCost": 170.22,
        "adjustedTotalCost": 170.22,
        "kWh": 1266.48,
        "kW": 0
      },
      "accuracy": 1,
      "items": [
        {
          "fromDateTime": "2016-07-10T01:00:00-04:00",
          "toDateTime": "2016-08-12T01:00:00-04:00",
          "quantityKey": "consumption",
          "rateAmount": 0.13440682,
          "itemQuantity": 1266.48,
          "cost": 170.22354375
        }
      ],
      "assumptions": [
        {
          "keyName": "tariffId",
          "dataType": "INTEGER",
          "fromDateTime": "2016-07-10T01:00:00-04:00",
          "toDateTime": "2016-08-12T01:00:00-04:00",
          "dataValue": "3258294"
        },
        {
          "keyName": "isLowIncomeSeniorCitizen953",
          "displayName": "Is Low Income Senior Citizen",
          "description": "Customers who are at least 62 years of age or older or be a disabled person as evidenced by receiving Supplemental Security Income (SSI) or State Supplemental Payment (SSP) and whose total gross annual income for all persons in the applicant's household may not exceed seventy-five (75) percent of the most recent median income levels.",
          "dataType": "BOOLEAN",
          "fromDateTime": "2016-07-10T01:00:00-04:00",
          "toDateTime": "2016-08-12T01:00:00-04:00",
          "dataValue": "false",
          "accuracy": 100
        },
        {
          "keyName": "cityLimits",
          "displayName": "Service Area (Inside/outside city limits)",
          "description": "Has service inside or outside city limits",
          "dataType": "STRING",
          "fromDateTime": "2016-07-10T01:00:00-04:00",
          "toDateTime": "2016-08-12T01:00:00-04:00",
          "dataValue": "Inside",
          "accuracy": 100
        }
      ]
    }
    "calculatedCostId": "1212281e-d0cd-4a4c-b785-be152022d456"
  ]
}

Example 3 - Calculate by passing in periods

In the following examples, we pass in consumption data using periods (for time of use bucketed values).

3a: Passing period as an enumeration

Periods can be passed in as enumeration values corresponding to the tariff labels for time-of-use periods:

Request
POST /rest/v1/ondemand/calculate
{
    "masterTariffId": 525,
    "fromDateTime": "2015-12-08T00:00:00-08:00",
    "toDateTime": "2016-01-03T00:00:00-08:00",
    "billingPeriod": true,
    "minimums": true,
    "groupBy": "MONTH",
    "detailLevel": "RATE",
    "fields": "ext",
    "propertyInputs": [ {
        "keyName": "consumption",
        "unit": "kWh",
        "period": "PARTIAL_PEAK",
        "dataValue": "300.1"
    },{
        "keyName" : "consumption",
        "unit" : "kWh",
        "period":"OFF_PEAK",
        "dataValue":"200.6"
    }]
}
Response
{
  "status": "success",
  "count": 1,
  "type": "CalculatedCost",
  "requestId": "e149e5c4-8f9c-4fc1-b865-24941d69afd4",
  "results": [
    {
      "masterTariffId": 525,
      "tariffName": "Residential - Time of Use",
      "totalCost": 85.99,
      "fromDateTime": "2015-12-08T00:00:00-08:00",
      "toDateTime": "2016-01-03T00:00:00-08:00",
      "currency": "USD",
      "summary": {
        "subTotalCost": 85.99,
        "taxCost": 0,
        "totalCost": 85.99,
        "adjustedTotalCost": 86.14,
        "kWh": 500.7,
        "kW": 0
      },
      "accuracy": 1,
      "items": [
        {
          "tariffRateId": 17368253,
          "tariffRateBandId": 10770115,
          "rateSequenceNumber": 0,
          "rateGroupName": "Energy Surcharge",
          "rateName": "Energy Surcharge",
          "fromDateTime": "2015-12-08T00:00:00-08:00",
          "toDateTime": "2016-01-03T00:00:00-08:00",
          "quantityKey": "consumption",
          "rateType": "COST_PER_UNIT",
          "rateAmount": 0.00029,
          "itemQuantity": 500.7,
          "cost": 0.145203,
          "chargeType": "CONSUMPTION_BASED",
          "chargeClass": "AFTER_TAX",
          "transactionType": "NET"
        },
        {
          "tariffRateId": 17411233,
          "tariffRateBandId": 10815788,
          "rateSequenceNumber": 1,
          "rateGroupName": "Generation",
          "rateName": "Generation Charge - Winter Off-Peak",
          "fromDateTime": "2015-12-08T00:00:00-08:00",
          "toDateTime": "2016-01-03T00:00:00-08:00",
          "quantityKey": "consumption",
          "rateType": "COST_PER_UNIT",
          "rateAmount": 0.07707,
          "itemQuantity": 183.79581152,
          "cost": 14.16514319,
          "chargeType": "CONSUMPTION_BASED",
          "chargeClass": "SUPPLY",
          "period": "OFF_PEAK",
          "seasonName": "Winter",
          "transactionType": "NET"
        },
        {
          "tariffRateId": 17459959,
          "tariffRateBandId": 10892524,
          "rateSequenceNumber": 1,
          "rateGroupName": "Generation",
          "rateName": "Generation Charge - Winter Off-Peak",
          "fromDateTime": "2015-12-08T00:00:00-08:00",
          "toDateTime": "2016-01-03T00:00:00-08:00",
          "quantityKey": "consumption",
          "rateType": "COST_PER_UNIT",
          "rateAmount": 0.08243,
          "itemQuantity": 16.80418848,
          "cost": 1.38516926,
          "chargeType": "CONSUMPTION_BASED",
          "chargeClass": "SUPPLY",
          "period": "OFF_PEAK",
          "seasonName": "Winter",
          "transactionType": "NET"
        },
        {
          "tariffRateId": 17411231,
          "tariffRateBandId": 10815786,
          "rateSequenceNumber": 1,
          "rateGroupName": "Generation",
          "rateName": "Generation Charge - Winter Part-Peak",
          "fromDateTime": "2015-12-08T00:00:00-08:00",
          "toDateTime": "2016-01-03T00:00:00-08:00",
          "quantityKey": "consumption",
          "rateType": "COST_PER_UNIT",
          "rateAmount": 0.09116,
          "itemQuantity": 300.1,
          "cost": 27.357116,
          "chargeType": "CONSUMPTION_BASED",
          "chargeClass": "SUPPLY",
          "period": "PARTIAL_PEAK",
          "seasonName": "Winter",
          "transactionType": "NET"
        },
        {
          "tariffRateId": 17411214,
          "tariffRateBandId": 10815769,
          "rateSequenceNumber": 3,
          "rateGroupName": "California Climate Credit",
          "rateName": "California Climate Credit",
          "fromDateTime": "2015-12-08T00:00:00-08:00",
          "toDateTime": "2016-01-03T00:00:00-08:00",
          "quantityKey": "fixed",
          "rateType": "COST_PER_UNIT",
          "rateAmount": 0,
          "itemQuantity": 0,
          "cost": 0,
          "chargeType": "FIXED_PRICE",
          "chargeClass": "AFTER_TAX",
          "transactionType": "BUY"
        },
        {
          "tariffRateId": 17459940,
          "tariffRateBandId": 10892505,
          "rateSequenceNumber": 3,
          "rateGroupName": "California Climate Credit",
          "rateName": "California Climate Credit",
          "fromDateTime": "2015-12-08T00:00:00-08:00",
          "toDateTime": "2016-01-03T00:00:00-08:00",
          "quantityKey": "fixed",
          "rateType": "COST_PER_UNIT",
          "rateAmount": 0,
          "itemQuantity": 0,
          "cost": 0,
          "chargeType": "FIXED_PRICE",
          "chargeClass": "AFTER_TAX",
          "transactionType": "BUY"
        },
        {
          "tariffRateId": 17411215,
          "tariffRateBandId": 10815770,
          "rateSequenceNumber": 4,
          "rateGroupName": "Transmission",
          "rateName": "Transmission",
          "fromDateTime": "2015-12-08T00:00:00-08:00",
          "toDateTime": "2016-01-03T00:00:00-08:00",
          "quantityKey": "consumption",
          "rateType": "COST_PER_UNIT",
          "rateAmount": 0.01659,
          "itemQuantity": 483.89581152,
          "cost": 8.02783151,
          "chargeType": "CONSUMPTION_BASED",
          "transactionType": "NET"
        },
        {
          "tariffRateId": 17459941,
          "tariffRateBandId": 10892506,
          "rateSequenceNumber": 4,
          "rateGroupName": "Transmission",
          "rateName": "Transmission",
          "fromDateTime": "2015-12-08T00:00:00-08:00",
          "toDateTime": "2016-01-03T00:00:00-08:00",
          "quantityKey": "consumption",
          "rateType": "COST_PER_UNIT",
          "rateAmount": 0.01659,
          "itemQuantity": 16.80418848,
          "cost": 0.27878149,
          "chargeType": "CONSUMPTION_BASED",
          "transactionType": "NET"
        },
        {
          "tariffRateId": 17411234,
          "tariffRateBandId": 10815789,
          "rateSequenceNumber": 5,
          "rateGroupName": "Distribution",
          "rateName": "Distribution Charge - Winter Off-Peak",
          "fromDateTime": "2015-12-08T00:00:00-08:00",
          "toDateTime": "2016-01-03T00:00:00-08:00",
          "quantityKey": "consumption",
          "rateType": "COST_PER_UNIT",
          "rateAmount": 0.04966,
          "itemQuantity": 183.79581152,
          "cost": 9.1273,
          "chargeType": "CONSUMPTION_BASED",
          "period": "OFF_PEAK",
          "seasonName": "Winter",
          "transactionType": "NET"
        },
        {
          "tariffRateId": 17459960,
          "tariffRateBandId": 10892525,
          "rateSequenceNumber": 5,
          "rateGroupName": "Distribution",
          "rateName": "Distribution Charge - Winter Off-Peak",
          "fromDateTime": "2015-12-08T00:00:00-08:00",
          "toDateTime": "2016-01-03T00:00:00-08:00",
          "quantityKey": "consumption",
          "rateType": "COST_PER_UNIT",
          "rateAmount": 0.0624,
          "itemQuantity": 16.80418848,
          "cost": 1.04858136,
          "chargeType": "CONSUMPTION_BASED",
          "period": "OFF_PEAK",
          "seasonName": "Winter",
          "transactionType": "NET"
        },
        {
          "tariffRateId": 17411232,
          "tariffRateBandId": 10815787,
          "rateSequenceNumber": 5,
          "rateGroupName": "Distribution",
          "rateName": "Distribution Charge - Winter Part-Peak",
          "fromDateTime": "2015-12-08T00:00:00-08:00",
          "toDateTime": "2016-01-03T00:00:00-08:00",
          "quantityKey": "consumption",
          "rateType": "COST_PER_UNIT",
          "rateAmount": 0.07449,
          "itemQuantity": 300.1,
          "cost": 22.354449,
          "chargeType": "CONSUMPTION_BASED",
          "period": "PARTIAL_PEAK",
          "seasonName": "Winter",
          "transactionType": "NET"
        },
        {
          "tariffRateId": 17411216,
          "tariffRateBandId": 10815771,
          "rateSequenceNumber": 5,
          "rateGroupName": "Transmission",
          "rateName": "Transmission Rate Adjustments",
          "fromDateTime": "2015-12-08T00:00:00-08:00",
          "toDateTime": "2016-01-03T00:00:00-08:00",
          "quantityKey": "consumption",
          "rateType": "COST_PER_UNIT",
          "rateAmount": 0.00085,
          "itemQuantity": 483.89581152,
          "cost": 0.41131144,
          "chargeType": "CONSUMPTION_BASED",
          "transactionType": "NET"
        },
        {
          "tariffRateId": 17459942,
          "tariffRateBandId": 10892507,
          "rateSequenceNumber": 5,
          "rateGroupName": "Transmission",
          "rateName": "Transmission Rate Adjustments",
          "fromDateTime": "2015-12-08T00:00:00-08:00",
          "toDateTime": "2016-01-03T00:00:00-08:00",
          "quantityKey": "consumption",
          "rateType": "COST_PER_UNIT",
          "rateAmount": -0.00033,
          "itemQuantity": 16.80418848,
          "cost": -0.00554538,
          "chargeType": "CONSUMPTION_BASED",
          "transactionType": "NET"
        },
        {
          "tariffRateId": 17411217,
          "tariffRateBandId": 10815772,
          "rateSequenceNumber": 6,
          "rateGroupName": "Transmission",
          "rateName": "Reliability Service Charge",
          "fromDateTime": "2015-12-08T00:00:00-08:00",
          "toDateTime": "2016-01-03T00:00:00-08:00",
          "quantityKey": "consumption",
          "rateType": "COST_PER_UNIT",
          "rateAmount": 0.00015,
          "itemQuantity": 483.89581152,
          "cost": 0.07258437,
          "chargeType": "CONSUMPTION_BASED",
          "transactionType": "NET"
        },
        {
          "tariffRateId": 17459943,
          "tariffRateBandId": 10892508,
          "rateSequenceNumber": 6,
          "rateGroupName": "Transmission",
          "rateName": "Reliability Service Charge",
          "fromDateTime": "2015-12-08T00:00:00-08:00",
          "toDateTime": "2016-01-03T00:00:00-08:00",
          "quantityKey": "consumption",
          "rateType": "COST_PER_UNIT",
          "rateAmount": 0.00023,
          "itemQuantity": 16.80418848,
          "cost": 0.00386496,
          "chargeType": "CONSUMPTION_BASED",
          "transactionType": "NET"
        },
        {
          "tariffRateId": 17411218,
          "tariffRateBandId": 10815773,
          "rateSequenceNumber": 7,
          "rateGroupName": "Distribution",
          "rateName": "New System Generation Charge",
          "fromDateTime": "2015-12-08T00:00:00-08:00",
          "toDateTime": "2016-01-03T00:00:00-08:00",
          "quantityKey": "consumption",
          "rateType": "COST_PER_UNIT",
          "rateAmount": 0.00302,
          "itemQuantity": 483.89581152,
          "cost": 1.46136535,
          "chargeType": "CONSUMPTION_BASED",
          "transactionType": "NET"
        },
        {
          "tariffRateId": 17459944,
          "tariffRateBandId": 10892509,
          "rateSequenceNumber": 7,
          "rateGroupName": "Distribution",
          "rateName": "New System Generation Charge",
          "fromDateTime": "2015-12-08T00:00:00-08:00",
          "toDateTime": "2016-01-03T00:00:00-08:00",
          "quantityKey": "consumption",
          "rateType": "COST_PER_UNIT",
          "rateAmount": 0.00255,
          "itemQuantity": 16.80418848,
          "cost": 0.04285068,
          "chargeType": "CONSUMPTION_BASED",
          "transactionType": "NET"
        },
        {
          "tariffRateId": 17411221,
          "tariffRateBandId": 10815776,
          "rateSequenceNumber": 8,
          "rateGroupName": "DWR Bond Charge",
          "rateName": "DWR Bond Charge",
          "fromDateTime": "2015-12-08T00:00:00-08:00",
          "toDateTime": "2016-01-03T00:00:00-08:00",
          "quantityKey": "consumption",
          "rateType": "COST_PER_UNIT",
          "rateAmount": 0.00526,
          "itemQuantity": 483.89581152,
          "cost": 2.54529197,
          "chargeType": "CONSUMPTION_BASED",
          "transactionType": "NET"
        },
        {
          "tariffRateId": 17411219,
          "tariffRateBandId": 10815774,
          "rateSequenceNumber": 8,
          "rateGroupName": "Public Purpose Programs",
          "rateName": "Public Purpose Programs",
          "fromDateTime": "2015-12-08T00:00:00-08:00",
          "toDateTime": "2016-01-03T00:00:00-08:00",
          "quantityKey": "consumption",
          "rateType": "COST_PER_UNIT",
          "rateAmount": 0.01312,
          "itemQuantity": 483.89581152,
          "cost": 6.34871305,
          "chargeType": "CONSUMPTION_BASED",
          "transactionType": "NET"
        },
        {
          "tariffRateId": 17459945,
          "tariffRateBandId": 10892510,
          "rateSequenceNumber": 8,
          "rateGroupName": "Public Purpose Programs",
          "rateName": "Public Purpose Programs",
          "fromDateTime": "2015-12-08T00:00:00-08:00",
          "toDateTime": "2016-01-03T00:00:00-08:00",
          "quantityKey": "consumption",
          "rateType": "COST_PER_UNIT",
          "rateAmount": 0.01405,
          "itemQuantity": 16.80418848,
          "cost": 0.23609885,
          "chargeType": "CONSUMPTION_BASED",
          "transactionType": "NET"
        },
        {
          "tariffRateId": 17459946,
          "tariffRateBandId": 10892511,
          "rateSequenceNumber": 9,
          "rateGroupName": "DWR Bond Charge",
          "rateName": "DWR Bond Charge",
          "fromDateTime": "2015-12-08T00:00:00-08:00",
          "toDateTime": "2016-01-03T00:00:00-08:00",
          "quantityKey": "consumption",
          "rateType": "COST_PER_UNIT",
          "rateAmount": 0.00539,
          "itemQuantity": 16.80418848,
          "cost": 0.09057458,
          "chargeType": "CONSUMPTION_BASED",
          "transactionType": "NET"
        },
        {
          "tariffRateId": 17411220,
          "tariffRateBandId": 10815775,
          "rateSequenceNumber": 9,
          "rateGroupName": "Nuclear Decommissioning",
          "rateName": "Nuclear Decommissioning",
          "fromDateTime": "2015-12-08T00:00:00-08:00",
          "toDateTime": "2016-01-03T00:00:00-08:00",
          "quantityKey": "consumption",
          "rateType": "COST_PER_UNIT",
          "rateAmount": 0.00097,
          "itemQuantity": 483.89581152,
          "cost": 0.46937894,
          "chargeType": "CONSUMPTION_BASED",
          "transactionType": "NET"
        },
        {
          "tariffRateId": 17459947,
          "tariffRateBandId": 10892512,
          "rateSequenceNumber": 9,
          "rateGroupName": "Nuclear Decommissioning",
          "rateName": "Nuclear Decommissioning",
          "fromDateTime": "2015-12-08T00:00:00-08:00",
          "toDateTime": "2016-01-03T00:00:00-08:00",
          "quantityKey": "consumption",
          "rateType": "COST_PER_UNIT",
          "rateAmount": 0.00022,
          "itemQuantity": 16.80418848,
          "cost": 0.00369692,
          "chargeType": "CONSUMPTION_BASED",
          "transactionType": "NET"
        },
        {
          "tariffRateId": 17411222,
          "tariffRateBandId": 10815777,
          "rateSequenceNumber": 9,
          "rateGroupName": "Ongoing CTC",
          "rateName": "Ongoing CTC",
          "fromDateTime": "2015-12-08T00:00:00-08:00",
          "toDateTime": "2016-01-03T00:00:00-08:00",
          "quantityKey": "consumption",
          "rateType": "COST_PER_UNIT",
          "rateAmount": 0.00067,
          "itemQuantity": 483.89581152,
          "cost": 0.32421019,
          "chargeType": "CONSUMPTION_BASED",
          "transactionType": "NET"
        },
        {
          "tariffRateId": 17459948,
          "tariffRateBandId": 10892513,
          "rateSequenceNumber": 9,
          "rateGroupName": "Ongoing CTC",
          "rateName": "Ongoing CTC",
          "fromDateTime": "2015-12-08T00:00:00-08:00",
          "toDateTime": "2016-01-03T00:00:00-08:00",
          "quantityKey": "consumption",
          "rateType": "COST_PER_UNIT",
          "rateAmount": 0.00338,
          "itemQuantity": 16.80418848,
          "cost": 0.05679816,
          "chargeType": "CONSUMPTION_BASED",
          "transactionType": "NET"
        },
        {
          "tariffRateId": 17411223,
          "tariffRateBandId": 10815778,
          "rateSequenceNumber": 15,
          "rateGroupName": "Energy Cost Recovery Amount",
          "rateName": "Energy Cost Recovery Amount",
          "fromDateTime": "2015-12-08T00:00:00-08:00",
          "toDateTime": "2016-01-03T00:00:00-08:00",
          "quantityKey": "consumption",
          "rateType": "COST_PER_UNIT",
          "rateAmount": -0.00504,
          "itemQuantity": 483.89581152,
          "cost": -2.43883489,
          "chargeType": "CONSUMPTION_BASED",
          "transactionType": "NET"
        },
        {
          "tariffRateId": 17459949,
          "tariffRateBandId": 10892514,
          "rateSequenceNumber": 15,
          "rateGroupName": "Energy Cost Recovery Amount",
          "rateName": "Energy Cost Recovery Amount",
          "fromDateTime": "2015-12-08T00:00:00-08:00",
          "toDateTime": "2016-01-03T00:00:00-08:00",
          "quantityKey": "consumption",
          "rateType": "COST_PER_UNIT",
          "rateAmount": -0.00002,
          "itemQuantity": 16.80418848,
          "cost": -0.00033608,
          "chargeType": "CONSUMPTION_BASED",
          "transactionType": "NET"
        },
        {
          "tariffRateId": 17411241,
          "tariffRateBandId": 10815816,
          "rateSequenceNumber": 17,
          "rateGroupName": "Conservation Incentive Adjustment",
          "rateName": "Conservation Incentive Adjustment (Winter Off Peak - Territory P)",
          "fromDateTime": "2015-12-08T00:00:00-08:00",
          "toDateTime": "2016-01-03T00:00:00-08:00",
          "quantityKey": "consumption",
          "rateType": "COST_PER_UNIT",
          "rateAmount": 0.00338252,
          "itemQuantity": 183.79581152,
          "cost": 0.62169301,
          "chargeType": "CONSUMPTION_BASED",
          "period": "OFF_PEAK",
          "seasonName": "Winter",
          "transactionType": "NET"
        },
        {
          "tariffRateId": 17459967,
          "tariffRateBandId": 10892550,
          "rateSequenceNumber": 17,
          "rateGroupName": "Conservation Incentive Adjustment",
          "rateName": "Conservation Incentive Adjustment (Winter Off Peak - Territory P)",
          "fromDateTime": "2015-12-08T00:00:00-08:00",
          "toDateTime": "2016-01-03T00:00:00-08:00",
          "quantityKey": "consumption",
          "rateType": "COST_PER_UNIT",
          "rateAmount": -0.03355,
          "itemQuantity": 16.80418848,
          "cost": -0.56378052,
          "chargeType": "CONSUMPTION_BASED",
          "period": "OFF_PEAK",
          "seasonName": "Winter",
          "transactionType": "NET"
        },
        {
          "tariffRateId": 17411240,
          "tariffRateBandId": 10815811,
          "rateSequenceNumber": 17,
          "rateGroupName": "Conservation Incentive Adjustment",
          "rateName": "Conservation Incentive Adjustment (Winter Partial Peak - Territory P)",
          "fromDateTime": "2015-12-08T00:00:00-08:00",
          "toDateTime": "2016-01-03T00:00:00-08:00",
          "quantityKey": "consumption",
          "rateType": "COST_PER_UNIT",
          "rateAmount": -0.01870748,
          "itemQuantity": 300.1,
          "cost": -5.61411475,
          "chargeType": "CONSUMPTION_BASED",
          "period": "PARTIAL_PEAK",
          "seasonName": "Winter",
          "transactionType": "NET"
        },
        {
          "tariffRateId": 17411239,
          "tariffRateBandId": 10815808,
          "rateSequenceNumber": 18,
          "rateGroupName": "Greenhouse Gas Volumetric Return",
          "rateName": "Greenhouse Gas Volumetric Return (Winter - Territory P)",
          "fromDateTime": "2015-12-08T00:00:00-08:00",
          "toDateTime": "2016-01-03T00:00:00-08:00",
          "quantityKey": "consumption",
          "rateType": "COST_PER_UNIT",
          "rateAmount": -0.00375176,
          "itemQuantity": 483.89581152,
          "cost": -1.81546095,
          "chargeType": "CONSUMPTION_BASED",
          "seasonName": "Winter",
          "transactionType": "NET"
        },
        {
          "tariffRateId": 17459965,
          "tariffRateBandId": 10892543,
          "rateSequenceNumber": 18,
          "rateGroupName": "Greenhouse Gas Volumetric Return",
          "rateName": "Greenhouse Gas Volumetric Return (Winter - Territory P)",
          "fromDateTime": "2015-12-08T00:00:00-08:00",
          "toDateTime": "2016-01-03T00:00:00-08:00",
          "quantityKey": "consumption",
          "rateType": "COST_PER_UNIT",
          "rateAmount": 0,
          "itemQuantity": 16.80418848,
          "cost": 0,
          "chargeType": "CONSUMPTION_BASED",
          "seasonName": "Winter",
          "transactionType": "NET"
        },
        {
          "tariffRateId": 17492212,
          "tariffRateBandId": 10994649,
          "rateSequenceNumber": 999,
          "rateGroupName": "Green Tariff (GT) Program Charges",
          "rateName": "Generation Credit",
          "fromDateTime": "2015-12-08T00:00:00-08:00",
          "toDateTime": "2016-01-03T00:00:00-08:00",
          "quantityKey": "consumption",
          "rateType": "COST_PER_UNIT",
          "rateAmount": 0,
          "itemQuantity": 16.80418848,
          "cost": 0,
          "chargeType": "CONSUMPTION_BASED",
          "chargeClass": "SUPPLY",
          "transactionType": "NET"
        },
        {
          "tariffRateId": 17492214,
          "tariffRateBandId": 10994653,
          "rateSequenceNumber": 999,
          "rateGroupName": "Green Tariff (GT) Program Charges",
          "rateName": "PCIA",
          "fromDateTime": "2015-12-08T00:00:00-08:00",
          "toDateTime": "2016-01-03T00:00:00-08:00",
          "quantityKey": "consumption",
          "rateType": "COST_PER_UNIT",
          "rateAmount": 0,
          "itemQuantity": 16.80418848,
          "cost": 0,
          "chargeType": "CONSUMPTION_BASED",
          "chargeClass": "DISTRIBUTION",
          "transactionType": "NET"
        },
        {
          "tariffRateId": 17492213,
          "tariffRateBandId": 10994651,
          "rateSequenceNumber": 999,
          "rateGroupName": "Green Tariff (GT) Program Charges",
          "rateName": "Program Charge",
          "fromDateTime": "2015-12-08T00:00:00-08:00",
          "toDateTime": "2016-01-03T00:00:00-08:00",
          "quantityKey": "consumption",
          "rateType": "COST_PER_UNIT",
          "rateAmount": 0,
          "itemQuantity": 16.80418848,
          "cost": 0,
          "chargeType": "CONSUMPTION_BASED",
          "chargeClass": "DISTRIBUTION",
          "transactionType": "NET"
        },
        {
          "tariffRateId": 17492211,
          "tariffRateBandId": 10994647,
          "rateSequenceNumber": 999,
          "rateGroupName": "Green Tariff (GT) Program Charges",
          "rateName": "Solar Charge",
          "fromDateTime": "2015-12-08T00:00:00-08:00",
          "toDateTime": "2016-01-03T00:00:00-08:00",
          "quantityKey": "consumption",
          "rateType": "COST_PER_UNIT",
          "rateAmount": 0,
          "itemQuantity": 16.80418848,
          "cost": 0,
          "chargeType": "CONSUMPTION_BASED",
          "chargeClass": "SUPPLY",
          "transactionType": "NET"
        },
        {
          "tariffRateId": 17411315,
          "tariffRateBandId": 10816100,
          "rateSequenceNumber": 999,
          "rateGroupName": "Minimum Charge",
          "rateName": "Minimum Charge",
          "fromDateTime": "2015-12-08T00:00:00-08:00",
          "toDateTime": "2016-01-03T00:00:00-08:00",
          "quantityKey": "minimum",
          "rateType": "COST_PER_UNIT",
          "rateAmount": 0.32854,
          "itemQuantity": 24,
          "cost": 7.88496,
          "chargeType": "MINIMUM",
          "transactionType": "BUY"
        },
        {
          "tariffRateId": 17460041,
          "tariffRateBandId": 10892836,
          "rateSequenceNumber": 999,
          "rateGroupName": "Minimum Charge",
          "rateName": "Minimum Charge",
          "fromDateTime": "2015-12-08T00:00:00-08:00",
          "toDateTime": "2016-01-03T00:00:00-08:00",
          "quantityKey": "minimum",
          "rateType": "COST_PER_UNIT",
          "rateAmount": 0.32854,
          "itemQuantity": 2,
          "cost": 0.65708,
          "chargeType": "MINIMUM",
          "transactionType": "BUY"
        }
      ],
      "assumptions": [...],
      "calculatedCostId": "bcb7f8cd-3ecb-4ae2-a78f-f14f0b947757"
    }
  ]
}

3b: Passing usage in custom periods

We provide a more generalized format for inputting data for arbitrary periods. In the request below, 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.

Request
POST /rest/v1/ondemand/calculate
{
    "masterTariffId": 525,
    "fromDateTime": "2015-12-08T00:00:00-08:00",
    "toDateTime": "2016-01-03T00:00:00-08:00",
    "billingPeriod": true,
    "minimums": true,
    "groupBy": "MONTH",
    "detailLevel": "RATE",
    "fields": "ext",
    "propertyInputs": [ {
        "keyName": "consumption",
        "unit": "kWh",
        "period": "1:5e 0H",
        "dataValue": "300.1"
    },
    {
        "keyName" : "consumption",
        "unit" : "kWh",
        "period":"6:7e 0H",
        "dataValue":"200.6"
    }]
}

Example 4 - Competitive Electric Supply, Community Choice Aggregation and other rate overrides

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.

4a: Competitive Electric Supply

In deregulated markets, customers can purchase electricity or gas from a third-party supplier rather than the distributing utility. To calculate costs in these scenarios, the calculate method accepts rates as inputs via rateInputs allowing you to define the “contracted” rate or rate structure. This contracted rate can be used within the calculation, overriding the bypassable rates. Contracted rates can include:

rateInputs is an array of TariffRate, and can include one or more rates of any charge type. For example, if you want to set a customer’s supply rate to 5¢/kWh for a calculation, you would pass in the following:

Request
POST /rest/v1/ondemand/calculate
{
   "masterTariffId": 522,
   "fromDateTime":"2015-01-01T00:00:00-07:00",
   "toDateTime":"2016-01-01T00:00:00-07:00",
   "groupBy": "MONTH",
   "detailLevel": "CHARGE_TYPE",
   "propertyInputs":[
       {
            "fromDateTime" : "2015-01-01",
            "toDateTime" : "2015-02-01",
            "keyName" : "consumption",
            "dataValue" : 520
        },{
            "fromDateTime" : "2015-02-01",
            "toDateTime" : "2015-03-01",
            "keyName" : "consumption",
            "dataValue" : 980
        },{
            "fromDateTime" : "2015-03-01",
            "toDateTime" : "2015-04-01",
            "keyName" : "consumption",
            "dataValue" : 1235
        },{
            "fromDateTime" : "2015-04-01",
            "toDateTime" : "2015-05-01",
            "keyName" : "consumption",
            "dataValue" : 1013
        },       {
            "fromDateTime" : "2015-05-01",
            "toDateTime" : "2015-06-01",
            "keyName" : "consumption",
            "dataValue" : 520
        },{
            "fromDateTime" : "2015-06-01",
            "toDateTime" : "2015-07-01",
            "keyName" : "consumption",
            "dataValue" : 980
        },{
            "fromDateTime" : "2015-07-01",
            "toDateTime" : "2015-08-01",
            "keyName" : "consumption",
            "dataValue" : 1235
        },{
            "fromDateTime" : "2015-08-01",
            "toDateTime" : "2015-09-01",
            "keyName" : "consumption",
            "dataValue" : 1013
        },{
            "fromDateTime" : "2015-09-01",
            "toDateTime" : "2015-10-01",
            "keyName" : "consumption",
            "dataValue" : 784
        },{
            "fromDateTime" : "2015-10-01",
            "toDateTime" : "2015-11-01",
            "keyName" : "consumption",
            "dataValue" : 895
        },{
            "fromDateTime" : "2015-11-01",
            "toDateTime" : "2015-12-01",
            "keyName" : "consumption",
            "dataValue" : 953
        },{
            "fromDateTime" : "2015-12-01",
            "toDateTime" : "2016-01-01",
            "keyName" : "consumption",
            "dataValue" : 1015
        }],
    "rateInputs":[
        {
            "fromDateTime":"2015-01-01T00:00:00-07:00",
            "toDateTime":"2016-01-01T00:00:00-07: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.

4b: Community Choice Aggregation (CCA)

Community Choice Aggregation (CCA) allows communities to choose to offer their residents alternative electric supply while continuing to have their electricity delivered by their local distribution utility. In such an arrangement the supply charges are from the CCA (e.g. Marin Clean Energy) and the transmission & distribution charges are from the distributing utility (e.g. Pacific Gas & Electric).

While we model CCA tariffs in their entirety, we also enable the calculation from the distributing utility’s point of view. The parameter is excludeChargeClass and you provide the charge class you would like to exclude. For example, to exclude the supply charges for a CCA customer (the distributing utility’s point of view), you make the following call:

Request
POST /rest/v1/ondemand/calculate
{
    "masterTariffId": 3251054,
    "fromDateTime": "2016-01-03",
    "toDateTime": "2016-02-05",
    "groupBy": "MONTH",
    "detailLevel": "RATE",
    "billingPeriod" : true,
    "excludeChargeClass": "SUPPLY",
    "propertyInputs" :[
    {
        "keyName": "consumption",
        "unit": "kWh",
        "dataValue": "1200"
    }]
}

4c: Modeling rate change using factors

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:

Request
POST /rest/v1/ondemand/calculate
{
    "masterTariffId": 3251054,
    "fromDateTime": "2011-11-01T00:00:00-05:00",
    "toDateTime": "2012-01-01T00:00:00-05:00",
    "propertyInputs":[
    {
        "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.

Request

POST /rest/v1/ondemand/calculate

Example request with tax rate inputs

{
   "masterTariffId": 522,
   "fromDateTime": "2016-06-01",
   "toDateTime": "2016-07-03",
   "billingPeriod": true,
   "propertyInputs":[
    {
         "keyName":"consumption",
         "dataValue":1000
    }],
   "rateInputs":[
    {
         "rateGroupName":"Taxes",    
         "rateName":"Utility Users Tax",
         "chargeType":"TAX",
         "rateBands":[
            {
               "rateAmount": 0.075,
               "rateUnit":"PERCENTAGE"
            }]
    }]
}

Response (snippet)

Item quantity reflects the subtotaled amount.

{
    "tariffRateId": 0,
    "rateSequenceNumber": 10000,
    "rateGroupName": "Taxes",
    "rateName": "Utility Users Tax",
    "fromDateTime": "2016-06-01T00:00:00-07:00",
    "toDateTime": "2016-07-03T00:00:00-07:00",
    "quantityKey": "percentage",
    "rateType": "PERCENTAGE",
    "rateAmount": 0.075,
    "itemQuantity": 233.52446,
    "cost": 17.5143345,
    "chargeType": "TAX"
}