Use Account Cost Calculation to calculate electricity, solar PV, or natural gas costs for an account over a specified time period.
Use Account Cost Calculation to calculate electricity, solar PV, or natural gas costs for an account over a specified time period.
Use this API when you need the cost of one account scenario. To compare multiple scenarios and calculate forecasted savings, use Analysis APIs.
To run a calculation, provide the tariff to use and the inputs that drive the rates. These inputs typically include consumption in kilowatt-hours (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 depends on the accuracy and granularity of the inputs. For example, a time-of-use (TOU) tariff has different prices depending on the time of day consumption occurred. Passing an hourly load profile produces more accurate calculations than passing aggregate monthly consumption because the calculator can place usage into the correct time periods.
When required information is missing, the calculator makes a best-guess assumption, such as estimating the TOU breakdown of energy usage. Review the assumptions section of the calculation results to see which assumptions were used.
Data definitions
Calculated cost
The CalculatedCost object contains the results of the calculation. The totalCost field holds the overall cost, while calculation details are contained in a list of CalculatedCostItem objects.
| Name | Type | Fields | Description |
|---|---|---|---|
| masterTariffId | Long | M | Unique Arcadia 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 | M | A decimal value between 0 and 1 represents 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 is represented in the calculation. | |
| calculationId | String | M | Unique identifier for this 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. |
{
"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",
"calculationId": "67afe5d7-19f1-4c35-8e83-6868f6402da8",
"summary": {
"subTotalCost": 198.35,
"taxCost": 0,
"totalCost": 198.35,
"adjustedTotalCost": 198.64,
"kWh": 1000,
"kW": 0
},
"items": [/* cost items */],
"assumptions": [/* assumptions */]
}
Calculated cost item
Calculated cost items contain the detailed line items for the calculation. There is one CalculatedCostItem object for each tariff rate included in the calculation.
| Name | Type | Fields | Description |
|---|---|---|---|
| tariffId | Long | E | Unique Arcadia ID for the tariff associated with this cost item. |
| tariffRateId | Long | M | Unique Arcadia ID for the tariff rate associated with this cost item. |
| tariffRateBandId | Long | M | Unique Arcadia 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. |
| 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, OTHER, CONTRACTED, USER_ADJUSTED or AFTER_TAX. | |
| 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 Arcadia 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 Arcadia 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
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. It 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=Start of calculation) |
| toDateTime | DateTime | M | The end of the period where this property is applicable. (Optional, Default=End of calculation) |
| dataType | String | M | The type of this property. Possible values are: "STRING", "CHOICE", "BOOLEAN", "DATE", "DECIMAL", "INTEGER", and "FORMULA" (Output only) |
| dataFactor | Decimal | For applicable properties (like electricity data) scale the inputs by the value provided (Optional, Input 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 that have many values, such as consumption time series data. (Required on input when not using dataValue) | |
| duration | Integer | Used with dataSeries to specify the time span corresponding to each value in the dataSeries. (Required on input when using dataSeries) | |
| unit | String | M | Where applicable, this is the unit of the value. The 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 that you set explicitly will have an accuracy value of 100. (Output only) |
As an input, use PropertyData to set calculation assumptions with the propertyInputs parameter. You can also use propertyInputs to override properties already set on the Account.
For example, you might have already indicated that a customer is enrolled in the "SmartRate" program by setting the isSmartRateCustomer property to true on the account. To calculate what the customer would pay without the SmartRate program, pass a property input like this:
"propertyInputs": [
{
"keyName": "isSmartRateCustomer",
"dataValue": false
},
// Additional property inputs omitted.
] The property does not need to be set on the Account to use it in the calculator's propertyInputs parameter. When passing inputs, provide keyName and dataValue for one value, or dataSeries and duration for multiple values. Where necessary, you can also set fields such as fromDateTime and toDateTime. You do not need to pass informational fields such as dataType or description; those are defined by the property's metadata.
The APIs populate metadata fields when PropertyData is returned as an output. The returned assumptions list tells you which assumptions were made for the calculation and what information might be required for a future calculation. The API usually returns the dataValue or dataSeries value that was used, when one exists.
This abbreviated example shows returned assumptions:
"assumptions": [
{
"keyName": "isSmartRateCustomer",
"displayName": "Is SmartRate Customer",
"description": "The residential SmartRate program is a voluntary rate supplement to the customer's otherwise applicable rate schedule (OAS). The customer will be billed for all regular charges applicable under the customer's OAS. Additional charges (based on usage during SmartDay High-Price Periods) and SmartRate credits will be determined according to the rates specified in this schedule. The customer must have a SmartMeter system to participate in the residential SmartRate 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.
},
// Additional assumptions omitted.
]
Every valid keyName that you can use in PropertyData is available through the Properties API. Use it to retrieve metadata such as title, description, data type, and possible values.
Request ID
The top-level response object includes a requestId field. The requestId value is generated randomly for each request.
Include the requestId when you submit a support ticket about a specific calculation result. This abbreviated response shows where the field appears.
{
"status": "success",
"count": 1,
"type": "CalculatedCost",
"requestId": "b9418ae1-af32-473a-b86a-b308fdbd48d1",
"results": [/* calculated costs */]
}
Run Account Cost Calculation
To run a calculation, send a POST request with the calculation criteria and inputs in the request body. The response returns a CalculatedCost object. These parameters are part of the request body, not the query string.
Resource URI
Account ID
POST /rest/v1/accounts/{accountId}/calculateProvider Account ID
POST /rest/v1/accounts/pid/{providerAccountId}/calculateRequest parameters
Along with the required authentication parameters, the following parameters are available in the request body:
| Name | Type | Description |
|---|---|---|
| fromDateTime | DateTime | Starting date and time for this calculation. (Required) |
| toDateTime | DateTime | End date and time for this calculation. (Required) |
| detailLevel | Enumeration | Toggles the level of detail 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) |
| includeDefaultProfile | Boolean | Use the default profile on the account. (Optional, Default=true) |
| profileId | String | Use an explicit Profile for this calculation. (Optional) |
| dataFactor | Decimal | Specify a constant scalar to be applied to all profiles used in this calculation. Can also be used in propertyInputs to modify a single profile when multiple are used. (Optional) |
| billingPeriod | String | A true or false flag. If the dates of the calculation represent an actual billing cycle, then you should set this to true. This will give you precise values for items like fixed charges. When it's not set, or set to false, these charges will be prorated across the number of days in the calculation. (Optional, Default=false) |
| minimums | Boolean | This field enables enforcing minimum charges on this calculation. (Optional, Default=false) |
| applyUtilityTax | Boolean | When true, the calculation attempts to apply a utility tax for the address associated with this account. (Optional, Default=false) |
| calcNetExcessGeneration | Boolean | This field includes net metering totals in the summary section of the calculation. (Optional, Default=false) |
| excludeChargeClass | Comma 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) |
| 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. |
| autoBaseline | Boolean | This field enables the intelligent baselining feature, which allows you to move usage data to a different time period. (Optional, Default=false) |
| useIntelligentBaselining | Boolean | This field works in conjunction with autoBaseline (above) and determines how to interpolate and extrapolate usage data when that is set to true. Read intelligent baselining for details. |
| customTimeOfUseIntervals | Array of TimeOfUseInterval | Define your own time-of-use interval to be used in the calculation. (Optional) |
| masterTariffId | Long | Unique Arcadia ID for the master tariff of this tariff. (Optional, Default is the most likely tariff for the account address) |
| propertyInputs | Array | Array of PropertyData to use in the calculation. (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
Calculate last month's bill
POST /rest/v1/accounts/62d07619-06fd-4a28-9376-62c86c7811d5/calculateThis sample POST request uses the accountId from the endpoint path.
{
"fromDateTime" : "2013-01-08",
"toDateTime" : "2014-01-12",
"billingPeriod": true,
"minimums" : true,
"detailLevel" : "RATE",
"groupBy" : "MONTH"
}
The response returns an abbreviated CalculatedCost object:
{
"status": "success",
"count": 1,
"type": "CalculatedCost",
"requestId": "52da5704-a951-4104-ae27-bf0cce98334d",
"results": [
{
"masterTariffId": 522,
"tariffName": "Residential",
"totalCost": 59.19,
"fromDateTime": "2013-01-08T00:00:00-08:00",
"toDateTime": "2014-01-12T00:00:00-08:00",
"currency": "USD",
"summary": {
"ELECTRICITY": {
"kWh": 0,
"kW": 0
},
"subTotalCost": 54.55,
"taxCost": 4.64,
"totalCost": 59.19,
"adjustedTotalCost": 59.19,
"kWh": 0,
"kW": 0
},
"accuracy": 1,
"items": [
{
"tariffRateId": 17023273,
"tariffRateBandId": 10237697,
"rateSequenceNumber": 1,
"rateGroupName": "Generation",
"rateName": "Generation Charge",
"fromDateTime": "2013-01-08T00:00:00-08:00",
"toDateTime": "2014-01-12T00:00:00-08:00",
"quantityKey": "consumption",
"rateType": "COST_PER_UNIT",
"rateAmount": 0.07884,
"itemQuantity": 0,
"cost": 0,
"chargeClass": "SUPPLY"
},
{
"tariffRateId": 17109049,
"tariffRateBandId": 10375380,
"rateSequenceNumber": 999,
"rateGroupName": "Minimum Charge",
"rateName": "Minimum Charge",
"fromDateTime": "2013-01-08T00:00:00-08:00",
"toDateTime": "2014-01-12T00:00:00-08:00",
"quantityKey": "minimum",
"rateType": "COST_PER_UNIT",
"rateAmount": 0.14784,
"itemQuantity": 11,
"cost": 1.62624
},
{
"tariffRateId": 0,
"rateSequenceNumber": 10000,
"rateGroupName": "TAX",
"rateName": "Utility Tax",
"fromDateTime": "2013-01-08T00:00:00-08:00",
"toDateTime": "2014-01-12T00:00:00-08:00",
"quantityKey": "percentage",
"rateType": "PERCENTAGE",
"rateAmount": 0.085,
"itemQuantity": 709.18848,
"cost": 4.6370016
},
// Additional cost items omitted.
],
"assumptions": [
{
"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": "2013-01-08T00:00:00-08:00",
"toDateTime": "2014-01-12T00:00:00-08: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": "2013-01-08T00:00:00-08:00",
"toDateTime": "2014-01-12T00:00:00-08: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": "2013-01-08T00:00:00-08:00",
"toDateTime": "2014-01-12T00:00:00-08: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": "2013-01-08T00:00:00-08:00",
"toDateTime": "2014-01-12T00:00:00-08:00",
"dataValue": "false",
"accuracy": 80
},
{
"keyName": "utilityEmployee",
"displayName": "Is Utility Employee",
"description": "Applicable to domestic service utility employees ",
"dataType": "BOOLEAN",
"fromDateTime": "2013-01-08T00:00:00-08:00",
"toDateTime": "2014-01-12T00:00:00-08: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": "2013-01-08T00:00:00-08:00",
"toDateTime": "2014-01-12T00:00:00-08:00",
"dataValue": "None",
"accuracy": 80
},
{
"keyName": "tariffId",
"dataType": "INTEGER",
"fromDateTime": "2013-01-08T00:00:00-08:00",
"toDateTime": "2013-05-01T00:00:00-07:00",
"dataValue": "3155887",
"accuracy": 100
},
{
"keyName": "tariffId",
"dataType": "INTEGER",
"fromDateTime": "2013-05-01T00:00:00-07:00",
"toDateTime": "2013-10-01T00:00:00-07:00",
"dataValue": "3160193",
"accuracy": 100
},
{
"keyName": "tariffId",
"dataType": "INTEGER",
"fromDateTime": "2013-10-01T00:00:00-07:00",
"toDateTime": "2014-01-01T00:00:00-08:00",
"dataValue": "3163175",
"accuracy": 100
},
{
"keyName": "tariffId",
"dataType": "INTEGER",
"fromDateTime": "2014-01-01T00:00:00-08:00",
"toDateTime": "2014-01-12T00:00:00-08:00",
"dataValue": "3164509",
"accuracy": 100
},
{
"keyName": "minimum",
"dataType": "STRING",
"fromDateTime": "2013-01-08T00:00:00-08:00",
"toDateTime": "2014-01-12T00:00:00-08:00",
"dataValue": "true",
"accuracy": 100
},
{
"keyName": "profileId",
"displayName": "2014 CA Electricity Residential TOU Profile",
"description": "ELECTRICITY_RESIDENTIAL_CA_2014_TOU",
"dataType": "STRING",
"dataValue": "5539691a368c25bd8b993673",
"accuracy": 100
},
{
"keyName": "territoryId",
"displayName": "Territory",
"description": "Territory where tariff is operational",
"dataType": "INTEGER",
"fromDateTime": "2013-01-08T00:00:00-08:00",
"toDateTime": "2014-01-12T00:00:00-08:00",
"dataValue": "3538",
"accuracy": 100
}
]
}
]
}
To get different result aggregations, modify the groupBy and detailLevel values. For example, using "groupBy":"HOUR" and "detailLevel":"CHARGE_TYPE" returns costs and usage broken down by charge type for each hour:
"items": [
{
"fromDateTime": "2013-01-08T00:00:00-08:00",
"toDateTime": "2013-01-08T01:00:00-08:00",
"quantityKey": "minimum",
"rateAmount": 0.00616,
"itemQuantity": 1,
"cost": 0.00616
},
{
"fromDateTime": "2013-01-08T00:00:00-08:00",
"toDateTime": "2013-01-08T01:00:00-08:00",
"quantityKey": "tax",
"rateAmount": 0.0000096,
"itemQuantity": 54.55296,
"cost": 0.0005236
},
// Additional items omitted.
]
Calculate with a provider account ID
To identify an account with the ID value you provided when creating the account, use this request URL format:
POST /rest/v1/accounts/pid/{yourProviderAccountId}/calculateNext steps
- Use Run Account Cost Calculation with
accountIdor Run Account Cost Calculation withproviderAccountIdto calculate account costs. - Use Analysis APIs when you need to compare scenarios or calculate savings.
- Review Dates & Times before sending date ranges or time-zone-aware values.