Oracle Utilities REST API for Digital Self Service Energy Management

Get Annual Disaggregation

get

/apis/disaggregation-v1/utilities/{utilityCode}/customers/{customerId}/consumption/categories

Returns the annual usage disaggregation combined across all utility accounts associated with the customer. If utilityAccountId or fuelType is specified then returns disaggregation only for the appropriate account.

The endDate parameter is optional and defaults to the current date. Results only include the ratio field, which 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

endDate: string(date-time)

Date in YYYY-MM-DD format (example 2001-12-31) used for the end date of the disaggregation annual period.
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 annual disaggregation.

Root Schema : ExternalResponseWrapperDisaggregationResultV2External

Type: object

Show Source

response: object DisaggregationResultV2External

{
    "type":"object",
    "properties":{
        "response":{
            "$ref":"#/definitions/DisaggregationResultV2External"
        }
    }
}

Nested Schema : DisaggregationResultV2External

Type: object

Show Source

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)

{
    "type":"object",
    "properties":{
        "categories":{
            "type":"array",
            "items":{
                "$ref":"#/definitions/DisaggregationValueV2"
            }
        },
        "usageUnits":{
            "description":"type of usage units provided in categories/usage (KWH, THERM)",
            "type":"string"
        },
        "billStartDate":{
            "description":"Date in YYYY-MM-DD format (example 2021-12-31) used as a the start date of the bill.",
            "type":"string",
            "format":"date"
        },
        "billEndDate":{
            "description":"Date in YYYY-MM-DD format (example 2021-12-31) used as a the end date of the bill.",
            "type":"string",
            "format":"date"
        }
    }
}

Nested Schema : categories

Type: array

Show Source

Array of: object DisaggregationValueV2

{
    "type":"array",
    "items":{
        "$ref":"#/definitions/DisaggregationValueV2"
    }
}

Nested Schema : DisaggregationValueV2

Type: object

Show Source

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

{
    "type":"object",
    "properties":{
        "name":{
            "type":"string",
            "enum":[
                "APPLIANCES",
                "CLOTHES_WASHER",
                "COOLING",
                "DISHWASHER",
                "DRYER",
                "ELECTRIC_VEHICLE",
                "ELECTRONICS",
                "HEATING",
                "LIGHTING",
                "OTHER",
                "OVEN",
                "POOL",
                "REFRIGERATOR",
                "GAS_APPLIANCES_OTHER",
                "TOTAL",
                "WATER_HEATING"
            ]
        },
        "ratio":{
            "type":"number"
        },
        "cost":{
            "type":"number"
        },
        "usage":{
            "type":"number"
        }
    }
}

Example Response (application/json)

{
    "response":{
        "categories":[
            {
                "name":"APPLIANCES",
                "ratio":0.09
            },
            {
                "name":"COOLING",
                "ratio":0.02
            },
            {
                "name":"ELECTRIC_VEHICLE",
                "ratio":0.2
            },
            {
                "name":"ELECTRONICS",
                "ratio":0.13
            },
            {
                "name":"HEATING",
                "ratio":0.22
            },
            {
                "name":"LIGHTING",
                "ratio":0.04
            },
            {
                "name":"OTHER",
                "ratio":0.06
            },
            {
                "name":"POOL",
                "ratio":0.13
            },
            {
                "name":"GAS_APPLIANCES_OTHER",
                "ratio":0.02
            },
            {
                "name":"AIR_CONDITION",
                "ratio":0.07
            },
            {
                "name":"TOTAL",
                "ratio":1
            },
            {
                "name":"WATER_HEATING",
                "ratio":0.11
            }
        ]
    }
}

400 Response

Bad request.

Root Schema : ExternalErrorResponse

Type: object

Show Source

error: object ExternalError

{
    "type":"object",
    "properties":{
        "error":{
            "$ref":"#/definitions/ExternalError"
        }
    }
}

Nested Schema : ExternalError

Type: object

Show Source

errorMessage: string

Failure explanation.
httpStatus: integer

{
    "type":"object",
    "properties":{
        "errorMessage":{
            "type":"string",
            "description":"Failure explanation."
        },
        "httpStatus":{
            "type":"integer"
        }
    }
}

Example Response (application/json)

{
    "error":{
        "httpStatus":400,
        "errorMessage":"Bad request"
    }
}

401 Response

Authorization failure.

Root Schema : ExternalErrorResponse

Type: object

Show Source

error: object ExternalError

{
    "type":"object",
    "properties":{
        "error":{
            "$ref":"#/definitions/ExternalError"
        }
    }
}

Nested Schema : ExternalError

Type: object

Show Source

errorMessage: string

Failure explanation.
httpStatus: integer

{
    "type":"object",
    "properties":{
        "errorMessage":{
            "type":"string",
            "description":"Failure explanation."
        },
        "httpStatus":{
            "type":"integer"
        }
    }
}

Example Response (application/json)

{
    "error":{
        "httpStatus":401,
        "errorMessage":"Credentials are required to access this resource"
    }
}

404 Response

Customer account not found.

Root Schema : ExternalErrorResponse

Type: object

Show Source

error: object ExternalError

{
    "type":"object",
    "properties":{
        "error":{
            "$ref":"#/definitions/ExternalError"
        }
    }
}

Nested Schema : ExternalError

Type: object

Show Source

errorMessage: string

Failure explanation.
httpStatus: integer

{
    "type":"object",
    "properties":{
        "errorMessage":{
            "type":"string",
            "description":"Failure explanation."
        },
        "httpStatus":{
            "type":"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.

Root Schema : ExternalErrorResponse

Type: object

Show Source

error: object ExternalError

{
    "type":"object",
    "properties":{
        "error":{
            "$ref":"#/definitions/ExternalError"
        }
    }
}

Nested Schema : ExternalError

Type: object

Show Source

errorMessage: string

Failure explanation.
httpStatus: integer

{
    "type":"object",
    "properties":{
        "errorMessage":{
            "type":"string",
            "description":"Failure explanation."
        },
        "httpStatus":{
            "type":"integer"
        }
    }
}

Example Response (application/json)

{
    "error":{
        "httpStatus":500,
        "errorMessage":"Unexpected error"
    }
}