Get Bill Disaggregation
get
/apis/disaggregation-v1/utilities/{utilityCode}/customers/{customerId}/bills/consumption/categories
Returns the bill disaggregation for the bill specified using the bill start and end date combined across all utility accounts associated with the customer. If utilityAccountId or fuelType is provided, then the bill disaggregation only for the applicable account is returned.
Results include the ratio and cost fields. The ratio is a decimal in the range [0, 1].
The following disaggregation categories are available APPLIANCES, CLOTHES_WASHER, COOLING, DISHWASHER, DRYER, ELECTRIC_VEHICLE, ELECTRONICS, HEATING, LIGHTING, OTHER, OVEN, POOL, REFRIGERATOR, GAS_APPLIANCES_OTHER, TOTAL, WATER_HEATING.
The list of categories can be extended, but existing categories will not be removed. APPLIANCES is an aggregate category for CLOTHES_WASHER, DISHWASHER, DRYER, OVEN, REFRIGERATOR, GAS_APPLIANCES_OTHER (for GAS or COMBINED customer). If heating or cooling model insights are not available, the disaggregation insights are not calculated, and a response status code 404 is returned.
Request
Path Parameters
-
customerId(required): integer
Utility customer ID.
-
utilityCode(required): string
A 3- or 4-character representation of the client code. Valid examples - "UTIL" and "util".
Query Parameters
-
billEndDate: string(date-time)
Date in YYYY-MM-DD format (example 2001-12-31) used for the end date of the bill.
-
billStartDate: string(date-time)
Date in YYYY-MM-DD format (example 2001-12-31) used for the start date of the bill.
-
fuelType: string
Identifies the customer account id based on the fuel type.Allowed Values:
[ "ELEC", "GAS" ] -
utilityAccountId: string
Utility customer account ID.
Response
200 Response
Returns bill disaggregation.
Nested Schema : DisaggregationResultV2External
Type:
Show Source
object-
billEndDate:
string(date)
Date in YYYY-MM-DD format (example 2021-12-31) used as a the end date of the bill.
-
billStartDate:
string(date)
Date in YYYY-MM-DD format (example 2021-12-31) used as a the start date of the bill.
-
categories:
array categories
-
usageUnits:
string
type of usage units provided in categories/usage (KWH, THERM)
Nested Schema : DisaggregationValueV2
Type:
Show Source
object-
cost:
number
-
name:
string
Allowed Values:
[ "APPLIANCES", "CLOTHES_WASHER", "COOLING", "DISHWASHER", "DRYER", "ELECTRIC_VEHICLE", "ELECTRONICS", "HEATING", "LIGHTING", "OTHER", "OVEN", "POOL", "REFRIGERATOR", "GAS_APPLIANCES_OTHER", "TOTAL", "WATER_HEATING" ] -
ratio:
number
-
usage:
number
Example Response (application/json)
{
"response":{
"categories":[
{
"name":"APPLIANCES",
"ratio":0.05,
"cost":490,
"usage":4900
},
{
"name":"CLOTHES_WASHER",
"ratio":0.01,
"cost":110,
"usage":1100
},
{
"name":"COOLING",
"ratio":0.26,
"cost":2600,
"usage":26000
},
{
"name":"DRYER",
"ratio":0.01,
"cost":220,
"usage":2200
},
{
"name":"ELECTRIC_VEHICLE",
"ratio":0.08,
"cost":760,
"usage":7600
},
{
"name":"ELECTRONICS",
"ratio":0.09,
"cost":863,
"usage":8630
},
{
"name":"HEATING",
"ratio":0.29,
"cost":2892,
"usage":28920
},
{
"name":"LIGHTING",
"ratio":0.02,
"cost":235,
"usage":2350
},
{
"name":"OTHER",
"ratio":0.04,
"cost":406,
"usage":4060
},
{
"name":"POOL",
"ratio":0.08,
"cost":824,
"usage":8240
},
{
"name":"REFRIGERATOR",
"ratio":0.01,
"cost":160,
"usage":1600
},
{
"name":"GAS_APPLIANCES_OTHER",
"ratio":0.01,
"cost":160,
"usage":1600
},
{
"name":"AIR_CONDITION",
"ratio":0.01,
"cost":160,
"usage":1600
},
{
"name":"TOTAL",
"ratio":1,
"cost":10000,
"usage":100000
},
{
"name":"WATER_HEATING",
"ratio":0.09,
"cost":930,
"usage":9300
}
],
"usageUnits":"KWH",
"billStartDate":"2014-04-01",
"billEndDate":"2015-06-28"
}
}400 Response
Bad request.
Nested Schema : ExternalError
Type:
Show Source
object-
errorMessage:
string
Failure explanation.
-
httpStatus:
integer
Example Response (application/json)
{
"error":{
"httpStatus":400,
"errorMessage":"Bad request"
}
}401 Response
Authorization failure.
Nested Schema : ExternalError
Type:
Show Source
object-
errorMessage:
string
Failure explanation.
-
httpStatus:
integer
Example Response (application/json)
{
"error":{
"httpStatus":401,
"errorMessage":"Credentials are required to access this resource"
}
}404 Response
Customer account not found.
Nested Schema : ExternalError
Type:
Show Source
object-
errorMessage:
string
Failure explanation.
-
httpStatus:
integer
Example Response (application/json)
{
"error":{
"httpStatus":404,
"errorMessage":"Account 00000000 not found. (917aab1d-b12a-4df9-b85d-968cc017a96e) "
}
}500 Response
Something unexpected happened while processing your request or an upstream request failed.
Nested Schema : ExternalError
Type:
Show Source
object-
errorMessage:
string
Failure explanation.
-
httpStatus:
integer
Example Response (application/json)
{
"error":{
"httpStatus":500,
"errorMessage":"Unexpected error"
}
}