Attention Developers: Our Documentation Is Moving!
Explore the latest updates and features in our new Signal Product Documentation and Switch Product Documentation.
Please note, this site’s retirement date will be announced soon, so make sure to update your bookmarks.
Explore the latest updates and features in our new Signal Product Documentation and Switch Product Documentation.
Please note, this site’s retirement date will be announced soon, so make sure to update your bookmarks.
On-Demand Cost Calculation
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<String,Decimal or Map> | Summary of cost and usage totals and sub-totals. Map key is a String and its value is a Decimal, or sometimes a nested Map (in turn a String and Decimal) See below for details of the Keys | |
| 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. |
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
"masterTariffId": 522,
"tariffName": "Residential",
"totalCost": 762.97,
"fromDateTime": "2013-12-01T00:00:00-08:00",
"toDateTime": "2014-01-01T00:00:00-08:00",
"accuracy": 1,
"currency": "USD",
"summary": {
"subTotalCost": 709.74,
"preTaxMinimumCost": 15.00,
"preTaxMaximumCost": 1722.41,
"taxCost": 53.23,
"totalCost": 762.97,
"adjustedTotalCost": 763.40,
"nonBypassableCost": 26.98,
"kWh": 1419.48,
"kW": 202.04
},
"items": [...],
"assumptions": [...],
"calculatedCostId": "67afe5d7-19f1-4c35-8e83-6868f6402da8",
}
Calculated Cost Summary Map
The summary section gives various totals and sub-totals that make up the calculated costs, as well as some summary information about usage too. Here are the most common values as well as some information about when you will see them included in the results:
| Summary Key | Description of Value | When included? |
|---|---|---|
subTotalCost |
Pre-tax total | Always |
preTaxMinimumCost |
Pre-tax minimum costs | If minimums=true and rates with MINIMUM chargeClass |
preTaxMaximumCost |
Pre-tax maximum costs | Rare. If minimums=true and rates with MAXIMUM chargeClass |
taxCost |
Cost of all taxes | If rates with TAX chargeType |
totalCost |
Post-tax costs, taking into account minimums or maximums but before after tax costs | Always. Matches the calcs totalCost |
adjustedTotalCost |
Total Costs including any costs that come after tax (tax exempt costs) | Rare. If rates with an AFTER_TAX value in chargeClass |
nonBypassableCost |
Portion of the pre-tax costs that cannot be by-passed | California. Rates with NON_BYPASSABLE value in chargeClass |
kWh |
Total kWhs for the calculation range | Always |
kW |
Peak Demand for the calculation range | Has none-zero value if there were DEMAND rates |
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: SUPER_OFF_PEAK, OFF_PEAK, PARTIAL_PEAK, ON_PEAK, SUPER_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 |
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
"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
The PropertyData object is used both as an input object, as part of the propertyInputs list, and also as an output object when returned in the assumptions list.
Every valid keyName that you can use in a PropertyData is available via our Property Key API. This will tell you its meta-data, such as its title, description, data type and possible values.
PropertyData 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 on input) |
| 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 to use for this property. Can be input as the native type, but when populated will be returned as a string. (Required on input when not using dataSeries) |
| dataSeries | Array of Decimal | Used for properties which have many values, such as consumption time series data. (Required on input when not using dataValue). When used in conjunction with exportDataSeries, the dataSeries represents the imports from the grid with exports to the grid defined in the exportDataSeries |
|
| exportDataSeries | Array of Decimal | Used to specify the time series data for power exported to the grid. This is used in conjunction with the dataSeries to create a series of import and export readings for tariffs with real time netting (instantaneous netting). | |
| duration | Integer | Used with dataSeries to specify the time span corresponding to each value in the dataSeries. (Required on input when 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) |
Property Data in requests propertyInputs
As an object used for inputs, you will pass in zero or more PropertyData records to set calculation properties via the propertyInputs parameter. For example, if you tell the calculator that your customer is enrolled in the “SmartRate” program, you would pass in that program’s keyName and dataValue:
1
2
3
4
5
6
7
"propertyInputs": [
{
"keyName": "isSmartRateCustomer",
"dataValue": true
},
...
]
When passing in inputs, we require the keyName and dataValue (for one value) or dataSeries and duration (for multiple). Typically, that’s all that is required. However, where necessary, you can set some of the other fields too, such as fromDateTime and toDateTime. You do not need to pass in informational fields such as dataType or description as these are defined by the property’s meta-data.
Property Data returned in responses assumptions
The assumptions in the CalculatedCost response is a list of PropertyData. It will tell you what assumptions were made for a particular calculation and what propertyInputs might be need to be added or updated to a rerun of the calculation in order to make it more accurate. The API will usually return the dataValue or dataSeries of the value that was actually used, if there is one.
In this example the calculator returned an assumption for isSmartRateCustomer(an optional program that some customer enroll in on this tariff). In this case the calculator didn’t know if they were enrolled (because the accuracy is less than 100 percent) and so assumed they were not enrolled (dataValue of false). If that assumption is wrong (they were in fact enrolled) then this Property Data can be explicitly passed back into the calculator via propertyInputs with a dataValue of true:
1
2
3
4
5
6
7
8
9
10
11
12
13
"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": "false",
"accuracy": 80
},
...
]
Minimum and Maximum assumptions
When running a calculation with minimums set to true, if the calculation results in minumum charges above the pre-tax total costs, or similarly, maximum charges below the pre-tax total costs, the results will be adjusted up to the minimum cost, or down to the maximum cost, respectfully. When this occurs, you will see an assumption entry for each billing period that this occured in. In the example below, we see that for the May bill, the pre-tax costs for all transmission, distribution and supply costs were above a maximum specified in the rates, so the pre-tax costs where adjusted down by $6982.31 (as defined in the dataValue field). Maximums are very rare, but minumums are more common. In the case of a minimum adjustment, the keyName will be mininum and the dataValue will be the amount added to the pre-tax costs to meet the minimum specified in the tariffs rates.
1
2
3
4
5
6
7
8
9
10
11
12
"assumptions": [
{
"keyName": "maximum",
"description": "TRANSMISSION,DISTRIBUTION,SUPPLY",
"dataType": "DECIMAL",
"fromDateTime": "2020-05-24T00:00:00-07:00",
"toDateTime": "2020-06-23T01:00:00-07:00",
"dataValue": "6982.31",
"accuracy": 100
},
...
]
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.
1
2
3
4
5
6
7
{
"status": "success",
"count": 1,
"type": "CalculatedCost",
"requestId": "b9418ae1-af32-473a-b86a-b308fdbd48d1",
"results": [...]
}
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. Examples (Optional, Default=ALL) |
| groupBy | Enumeration | This controls how the calculation details are grouped. Examples (Optional, Defaults to the natural grouping for the rates) |
| minimums | Boolean | This field enables enforcing minimum charges on this calculation. (Optional, Default=false) |
| excludeChargeClass | Command Separated String | Specifies a charge class to exclude from the calculation results. Available options are TRANSMISSION, DISTRIBUTION, SUPPLY, TAX, CONTRACTED, USER_ADJUSTED, AFTER_TAX, and OTHER. (Optional) |
| zipCode | String | (Optional and usually not needed) See below for the cases when you need location data. When populating this field you should also populate country too. |
| country | ISO Country Code | Use this when passing in a zipCode or postCode, and set it to the ISO Country Code of your zipCode since some countries use the same format (Use with zipCode) |
| address | Address | An alternative to using zipCode and country. (Optional and usually not needed) |
| 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) |
| applyUtilityTax | Boolean | When true, the calculation attempts to apply a utility tax to the provided location. (Optional, Default = true when zipCode and country, or address provided, false otherwise) |
Address
You don’t usually need to provide any location information with the On-Demand Cost Calculator. However, for some cases there is a requirement to have a zipcode and country in order to look up location specific information. Examples include:
- when the tariff has rates that vary by baseline region and you aren’t specifying the baseline’s
territoryId - you are a Utilty customer and want to apply utility taxes for a location to the results
The best way to specify the location is to explicitly provide a zipCode and a country (see above). However, if you don’t have these but have some other address fields or maybe geographic coordinates, you can use the address fields below. We will use our Geocoding service (currently Google) to look up the zipCode and a country.
| 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. |
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
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
"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.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
{
"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
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
{
"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
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
{
"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
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
"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
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
{
"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 300.1 kWh usage at midnight of each weekday. The second input specifies 200.6 kWh usage at midnight on the weekends.
Request
POST /rest/v1/ondemand/calculate
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
"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:
- Consumption, Demand, Fixed or Quantity rates
- ISO Pricing
- Block and Index Contracts, including Sellback Blocks
- Custom Time of Use Definitions
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
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
{
"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
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
"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
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
"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
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
"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.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
"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"
}
Example 6 - Overriding Critical Peak Rates in a Calculation
This example demonstrates how to pass in custom critical peak time of use intervals. The purpose of this feature is to
run a calculation with a different critical peak than the one otherwise provided by the tariff. Multiple custom critical
peak times can be passed in to simulate a varying number of critical peak events. Custom critical peak intervals are
passed in to the customTimeOfUseIntervals parameter, which contains a list of time of use intervals
to be overriden. The response will then have its critical peak items shift to the interval that was passed in. However,
none of the other time of use intervals will change. Note that at this time, only critical peak time of use intervals
are supported by this feature.
Request
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
{
"masterTariffId" : 83653,
"fromDateTime" : "2015-09-01",
"toDateTime" : "2015-09-30",
"minimums" : "true",
"detailLevel" : "RATE",
"groupBy" : "HOUR",
"billingPeriod" : "true",
"propertyInputs" : [
{
"fromDateTime" : "2015-09-01",
"toDateTime" : "2015-09-30",
"keyName" : "consumption",
"dataValue" : "2400"
},
{
"keyName" : "pdpProgramEventOption",
"dataValue" : "No Limit - Four Hour Window"
}
],
"customTimeOfUseIntervals": [
{ "touName": "Critical Peak PDP",
"fromDateTime": "2015-09-11T02:00:00-07:00",
"toDateTime": "2015-09-11T04:00:00-07:00",
"touType": "CRITICAL_PEAK"
},
{
"touName": "Critical Peak PDP",
"fromDateTime": "2015-09-12T02:00:00-07:00",
"toDateTime": "2015-09-12T04:00:00-07:00",
"touType": "CRITICAL_PEAK"
},
{
"touName": "Critical Peak PDP",
"fromDateTime": "2015-09-13T02:00:00-07:00",
"toDateTime": "2015-09-13T04:00:00-07:00",
"touType": "CRITICAL_PEAK"
}
]
}
Response (snippet)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
{
"tariffRateId": 17412037,
"tariffRateBandId": 10818319,
"rateSequenceNumber": 9,
"rateGroupName": "PDP Charges & Credits",
"rateName": "PDP Charges - Four Hour Window",
"fromDateTime": "2015-09-11T02:00:00-07:00",
"toDateTime": "2015-09-11T03:00:00-07:00",
"quantityKey": "consumption",
"rateType": "COST_PER_UNIT",
"rateAmount": 1.2,
"itemQuantity": 3.44827586,
"cost": 4.13793103,
"chargeType": "CONSUMPTION_BASED",
"period": "CRITICAL_PEAK",
"touId": 1964,
"touName": "Peak Day Pricing - Four Hour Window"
},
{
"tariffRateId": 17412037,
"tariffRateBandId": 10818319,
"rateSequenceNumber": 9,
"rateGroupName": "PDP Charges & Credits",
"rateName": "PDP Charges - Four Hour Window",
"fromDateTime": "2015-09-11T03:00:00-07:00",
"toDateTime": "2015-09-11T04:00:00-07:00",
"quantityKey": "consumption",
"rateType": "COST_PER_UNIT",
"rateAmount": 1.2,
"itemQuantity": 3.44827586,
"cost": 4.13793103,
"chargeType": "CONSUMPTION_BASED",
"period": "CRITICAL_PEAK",
"touId": 1964,
"touName": "Peak Day Pricing - Four Hour Window"
},
{
"tariffRateId": 17412037,
"tariffRateBandId": 10818319,
"rateSequenceNumber": 9,
"rateGroupName": "PDP Charges & Credits",
"rateName": "PDP Charges - Four Hour Window",
"fromDateTime": "2015-09-12T02:00:00-07:00",
"toDateTime": "2015-09-12T03:00:00-07:00",
"quantityKey": "consumption",
"rateType": "COST_PER_UNIT",
"rateAmount": 1.2,
"itemQuantity": 3.44827586,
"cost": 4.13793103,
"chargeType": "CONSUMPTION_BASED",
"period": "CRITICAL_PEAK",
"touId": 1964,
"touName": "Peak Day Pricing - Four Hour Window"
},
{
"tariffRateId": 17412037,
"tariffRateBandId": 10818319,
"rateSequenceNumber": 9,
"rateGroupName": "PDP Charges & Credits",
"rateName": "PDP Charges - Four Hour Window",
"fromDateTime": "2015-09-12T03:00:00-07:00",
"toDateTime": "2015-09-12T04:00:00-07:00",
"quantityKey": "consumption",
"rateType": "COST_PER_UNIT",
"rateAmount": 1.2,
"itemQuantity": 3.44827586,
"cost": 4.13793103,
"chargeType": "CONSUMPTION_BASED",
"period": "CRITICAL_PEAK",
"touId": 1964,
"touName": "Peak Day Pricing - Four Hour Window"
},
{
"tariffRateId": 17412037,
"tariffRateBandId": 10818319,
"rateSequenceNumber": 9,
"rateGroupName": "PDP Charges & Credits",
"rateName": "PDP Charges - Four Hour Window",
"fromDateTime": "2015-09-13T02:00:00-07:00",
"toDateTime": "2015-09-13T03:00:00-07:00",
"quantityKey": "consumption",
"rateType": "COST_PER_UNIT",
"rateAmount": 1.2,
"itemQuantity": 3.44827586,
"cost": 4.13793103,
"chargeType": "CONSUMPTION_BASED",
"period": "CRITICAL_PEAK",
"touId": 1964,
"touName": "Peak Day Pricing - Four Hour Window"
},
{
"tariffRateId": 17412037,
"tariffRateBandId": 10818319,
"rateSequenceNumber": 9,
"rateGroupName": "PDP Charges & Credits",
"rateName": "PDP Charges - Four Hour Window",
"fromDateTime": "2015-09-13T03:00:00-07:00",
"toDateTime": "2015-09-13T04:00:00-07:00",
"quantityKey": "consumption",
"rateType": "COST_PER_UNIT",
"rateAmount": 1.2,
"itemQuantity": 3.44827586,
"cost": 4.13793103,
"chargeType": "CONSUMPTION_BASED",
"period": "CRITICAL_PEAK",
"touId": 1964,
"touName": "Peak Day Pricing - Four Hour Window"
}