Genability Switch® Now part of Arcadia
Search
Search Log In Sign Up

Account Cost Calculation

The Account Cost Calculation endpoint calculates the cost of electricity, solar PV or natural gas for a given tariff for a given amount of usage over a specified period of time. This can be used to calculate a bill, “what-if” different rates, levels of usage, energy efficiency measures or any other electrical activity.

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

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

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

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 CalculatedCostItem(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 M A decimal value between 0 and 1 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.
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. 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

{
    "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": [...],
    "assumptions": [...]
}

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, 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 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. 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) scales 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 which 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. Most common are: "kWh" - for keys of consumption, "kW" - for keys of demand. (Optional)
accuracy Decimal [0,100] M Estimated accuracy of the property value. Properties which you set explicitly will have an accuracy value of 100. (Output only)

As an input, you will use PropertyData to set calculation assumptions via the propertyInputs parameter, including overriding any properties that have already been set on the Account. For example, you might have already indicated that a particular customer was enrolled in the “SmartRate” program by setting the isSmartRateCustomer property to true on their account. However, you want to see what they would pay if they weren’t enrolled in the smart rate program. To do this you would pass in property the following via the propertyInputs :

1
2
3
4
5
6
7

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

The property doesn’t need to be set on the Account to set it via the calculators propertyInputs parameter. When passing in inputs, we require the keyName and dataValue (for one value) or dataSeries and duration (for multiple values). 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.

The APIs will populate these metadata fields when a PropertyData is returned as an output. The assumptions list of PropertyData returned will tell you what assumptions were made for a particular calculation and what information might be required for a future calculation. The API will usually return the dataValue or dataSeries of the value that was actually used, if there is one. Here’s an example:

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": "true",
      "accuracy": 100 // implies this property was either passed in explicitly or must be true contextually
    }, 
    ...
]

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.

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 new Calculation

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

Resource URI

Account ID

POST /rest/v1/accounts/{accountId}/calculate/

Provider Account ID

POST /rest/v1/accounts/pid/{providerAccountId}/calculate/

Request Parameters

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

Name Type Description
fromDateTime DateTime Starting date and time for this calculation. (Required)
toDateTime DateTime End date and time for this calculation. (Required)
detailLevel Enumeration Toggles the level of details for the calculation result. Explanation (Optional, Default=ALL)
groupBy Enumeration This controls how the calculation details are grouped. Explanation (Optional, Defaults to the natural grouping for the rates)
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 intelligent baselining feature, which allow 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 Genability 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

Example 1 - Calculate last month’s bill

POST /rest/v1/accounts/62d07619-06fd-4a28-9376-62c86c7811d5/calculate/

Below is a sample POST request based on the above accountId.

1
2
3
4
5
6
7
8

{
  "fromDateTime" : "2013-01-08",
  "toDateTime" : "2014-01-12",
  "billingPeriod": true,
  "minimums" : true,
  "detailLevel" : "RATE",
  "groupBy" : "MONTH"
}

And here’s the 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

{
  "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
        },
      ...
      ],
      "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" for the calculation above will return costs and usage broken down by charge type for each hour:

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

"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
    },
    ...
]

Example 2 - Calculate with a Provider Account ID

To identify an account based on the ID value you provided when you created the account, use the following request url format:

POST /rest/v1/accounts/pid/{yourProviderAccountId}/calculate/