Oracle Utilities REST API for Digital Self Service Energy Management

Get List of Neighbor Comparisons

get

/apis/neighborComparison-v1/bill/{utilityCode}/{utilityCustomerId}/{fuelType}

Returns a neighbor comparison for a customer for each billing period in the given time span. Data is available for the past 12 months, for a maximum of 13 bills. Any billing period partially or fully within the requested time span is included in the response. If start and end dates are not provided the most recent neighbor comparison for the customer is returned.

Request

Path Parameters

fuelType(required): string

The customer's fuel type.

Allowed Values: [ "ELECTRICITY", "GAS", "COMBINED" ]
utilityCode(required): string

A 3- or 4-character representation of the client code, in all caps. Valid example - UTIL.
utilityCustomerId(required): string

The utility customer ID provided in the standard billing data integration.

Query Parameters

end: string(date-time)

The exclusive end date and time bounds in ISO8601 format. The default value is the end of the most recent complete billing period. The end value must be later than the start value.
start: string(date-time)

The inclusive start date and time bounds in ISO8601 format. The default value is the start of the most recent complete billing period. The start value must be earlier than the end value.

Header Parameters

Authorization(required): string

Oauth2 Bearer type id. For example, 'Bearer 00000000-0000-0000-0000-000000000000'

Response

Supported Media Types

application/json

200 Response

Successful response

Root Schema : schema

Type: object

Show Source

response(required): object BillNeighborComparisonListResponse

{
    "type":"object",
    "properties":{
        "response":{
            "$ref":"#/definitions/BillNeighborComparisonListResponse"
        }
    },
    "required":[
        "response"
    ],
    "additionalProperties":false,
    "example":{
        "response":{
            "utilityCode":"util",
            "utilityCustomerId":12345,
            "fuelType":"ELECTRICITY",
            "start":"2013-09-01T00:00:00-06:00",
            "end":"2014-09-01T00:00:00-06:00",
            "unit":"KWH",
            "neighborComparisons":[
                {
                    "start":"2013-08-20T00:00:00-06:00",
                    "end":"2013-09-20T00:00:00-06:00",
                    "customerUsage":332,
                    "allNeighborsUsage":358.1,
                    "efficientNeighborsUsage":294.4
                },
                {
                    "start":"2013-09-20T00:00:00-06:00",
                    "end":"2013-10-20T00:00:00-06:00",
                    "customerUsage":375.1,
                    "allNeighborsUsage":382.7,
                    "efficientNeighborsUsage":298.2
                }
            ]
        }
    }
}

Example:

{
    "response":{
        "utilityCode":"util",
        "utilityCustomerId":12345,
        "fuelType":"ELECTRICITY",
        "start":"2013-09-01T00:00:00-06:00",
        "end":"2014-09-01T00:00:00-06:00",
        "unit":"KWH",
        "neighborComparisons":[
            {
                "start":"2013-08-20T00:00:00-06:00",
                "end":"2013-09-20T00:00:00-06:00",
                "customerUsage":332,
                "allNeighborsUsage":358.1,
                "efficientNeighborsUsage":294.4
            },
            {
                "start":"2013-09-20T00:00:00-06:00",
                "end":"2013-10-20T00:00:00-06:00",
                "customerUsage":375.1,
                "allNeighborsUsage":382.7,
                "efficientNeighborsUsage":298.2
            }
        ]
    }
}

Nested Schema : BillNeighborComparisonListResponse

Type: object

Show Source

end(required): string(date-time)

End date of the request in ISO8601 format
fuelType(required): string

Allowed Values: [ "ELECTRICITY", "GAS", "COMBINED" ]

'fuelType' in the request
neighborComparisons(required): array neighborComparisons

Minimum Number of Items: 1

Maximum Number of Items: 13

Unique Items Required: true

List of neighbor comparisons, ordered by start date.
start(required): string(date-time)

Start date from the request in ISO8601 format
unit(required): string

Allowed Values: [ "KWH", "THERM", "BTU", "GALLON", "CUBIC_METERS", "CENTUM_CUBIC_FEET", "MIL_CUBIC_FEET" ]

Unit of measurement of all fuel usage values
utilityCode(required): string

'utilityCode' in the request
utilityCustomerId(required): string

'utilityCustomerId' in the request

{
    "type":"object",
    "properties":{
        "utilityCode":{
            "description":"'utilityCode' in the request",
            "type":"string"
        },
        "utilityCustomerId":{
            "description":"'utilityCustomerId' in the request",
            "type":"string"
        },
        "fuelType":{
            "description":"'fuelType' in the request",
            "type":"string",
            "enum":[
                "ELECTRICITY",
                "GAS",
                "COMBINED"
            ]
        },
        "start":{
            "description":"Start date from the request in ISO8601 format",
            "type":"string",
            "format":"date-time"
        },
        "end":{
            "description":"End date of the request in ISO8601 format",
            "type":"string",
            "format":"date-time"
        },
        "unit":{
            "description":"Unit of measurement of all fuel usage values",
            "type":"string",
            "enum":[
                "KWH",
                "THERM",
                "BTU",
                "GALLON",
                "CUBIC_METERS",
                "CENTUM_CUBIC_FEET",
                "MIL_CUBIC_FEET"
            ]
        },
        "neighborComparisons":{
            "description":"List of neighbor comparisons, ordered by start date.",
            "type":"array",
            "items":{
                "$ref":"#/definitions/BillNeighborComparison"
            },
            "minItems":1,
            "maxItems":13,
            "uniqueItems":true
        }
    },
    "required":[
        "utilityCode",
        "utilityCustomerId",
        "fuelType",
        "start",
        "end",
        "unit",
        "neighborComparisons"
    ],
    "additionalProperties":false
}

Nested Schema : neighborComparisons

Type: array

Minimum Number of Items: 1

Maximum Number of Items: 13

Unique Items Required: true

List of neighbor comparisons, ordered by start date.

Show Source

Array of: object BillNeighborComparison

{
    "description":"List of neighbor comparisons, ordered by start date.",
    "type":"array",
    "items":{
        "$ref":"#/definitions/BillNeighborComparison"
    },
    "minItems":1,
    "maxItems":13,
    "uniqueItems":true
}

Nested Schema : BillNeighborComparison

Type: object

Show Source

allNeighborsUsage(required): number

Mean fuel usage value, in the specified units, for the customer's neighbors
customerUsage(required): number

Fuel usage value, in the specified units, for the customer
efficientNeighborsUsage(required): number

Mean fuel usage value, in the specified units, for the customer's efficient neighbors
end(required): string(date-time)

Exclusive end date of the period in ISO8601 format
start(required): string(date-time)

Inclusive start date of the period in ISO8601 format

{
    "type":"object",
    "properties":{
        "start":{
            "description":"Inclusive start date of the period in ISO8601 format",
            "type":"string",
            "format":"date-time"
        },
        "end":{
            "description":"Exclusive end date of the period in ISO8601 format",
            "type":"string",
            "format":"date-time"
        },
        "customerUsage":{
            "description":"Fuel usage value, in the specified units, for the customer",
            "type":"number"
        },
        "allNeighborsUsage":{
            "description":"Mean fuel usage value, in the specified units, for the customer's neighbors",
            "type":"number"
        },
        "efficientNeighborsUsage":{
            "description":"Mean fuel usage value, in the specified units, for the customer's efficient neighbors",
            "type":"number"
        }
    },
    "required":[
        "start",
        "end",
        "customerUsage",
        "allNeighborsUsage",
        "efficientNeighborsUsage"
    ],
    "additionalProperties":false
}

400 Response

Bad request

Root Schema : schema

Type: object

Show Source

error(required): object ErrorResponse

{
    "type":"object",
    "properties":{
        "error":{
            "$ref":"#/definitions/ErrorResponse"
        }
    },
    "required":[
        "error"
    ],
    "additionalProperties":false,
    "example":{
        "error":{
            "httpStatus":400,
            "serviceErrorCode":"'INVALID_DATE_RANGE' or 'INVALID_DATE' or 'INVALID_FUEL_TYPE'",
            "details":"'Start must be within the last 12 months' or 'Start and end timestamp should be specified in ISO8601 format. For example: YYYY-MM-DDThh:mm:ssTZD' or 'Fuel type must be one of ELECTRICITY, GAS, COMBINED'"
        }
    }
}

Example:

{
    "error":{
        "httpStatus":400,
        "serviceErrorCode":"'INVALID_DATE_RANGE' or 'INVALID_DATE' or 'INVALID_FUEL_TYPE'",
        "details":"'Start must be within the last 12 months' or 'Start and end timestamp should be specified in ISO8601 format. For example: YYYY-MM-DDThh:mm:ssTZD' or 'Fuel type must be one of ELECTRICITY, GAS, COMBINED'"
    }
}

Nested Schema : ErrorResponse

Type: object

Show Source

details: string

Details about the error.
errorMessage: string

Short failure explanation.
httpStatus: integer

Minimum Value: 100

Maximum Value: 600

The HTTP status code for the error.
serviceErrorCode: string

An error code for the error.

{
    "type":"object",
    "properties":{
        "httpStatus":{
            "description":"The HTTP status code for the error.",
            "type":"integer",
            "minimum":100,
            "maximum":600
        },
        "serviceErrorCode":{
            "description":"An error code for the error.",
            "type":"string"
        },
        "errorMessage":{
            "description":"Short failure explanation.",
            "type":"string"
        },
        "details":{
            "description":"Details about the error.",
            "type":"string"
        }
    },
    "additionalProperties":false
}

401 Response

Unauthorized

Root Schema : schema

Type: object

Show Source

error(required): object ErrorResponse

{
    "type":"object",
    "properties":{
        "error":{
            "$ref":"#/definitions/ErrorResponse"
        }
    },
    "required":[
        "error"
    ],
    "additionalProperties":false,
    "example":{
        "error":{
            "httpStatus":401,
            "details":"Credentials are required to access this resource."
        }
    }
}

Example:

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

Nested Schema : ErrorResponse

Type: object

Show Source

details: string

Details about the error.
errorMessage: string

Short failure explanation.
httpStatus: integer

Minimum Value: 100

Maximum Value: 600

The HTTP status code for the error.
serviceErrorCode: string

An error code for the error.

{
    "type":"object",
    "properties":{
        "httpStatus":{
            "description":"The HTTP status code for the error.",
            "type":"integer",
            "minimum":100,
            "maximum":600
        },
        "serviceErrorCode":{
            "description":"An error code for the error.",
            "type":"string"
        },
        "errorMessage":{
            "description":"Short failure explanation.",
            "type":"string"
        },
        "details":{
            "description":"Details about the error.",
            "type":"string"
        }
    },
    "additionalProperties":false
}

403 Response

Forbidden

Root Schema : schema

Type: object

Show Source

error(required): object ErrorResponse

{
    "type":"object",
    "properties":{
        "error":{
            "$ref":"#/definitions/ErrorResponse"
        }
    },
    "required":[
        "error"
    ],
    "additionalProperties":false,
    "example":{
        "error":{
            "httpStatus":403,
            "details":"User not authorized. Missing required scope utility.{utilityCode}.{tier}"
        }
    }
}

Example:

{
    "error":{
        "httpStatus":403,
        "details":"User not authorized. Missing required scope utility.{utilityCode}.{tier}"
    }
}

Nested Schema : ErrorResponse

Type: object

Show Source

details: string

Details about the error.
errorMessage: string

Short failure explanation.
httpStatus: integer

Minimum Value: 100

Maximum Value: 600

The HTTP status code for the error.
serviceErrorCode: string

An error code for the error.

{
    "type":"object",
    "properties":{
        "httpStatus":{
            "description":"The HTTP status code for the error.",
            "type":"integer",
            "minimum":100,
            "maximum":600
        },
        "serviceErrorCode":{
            "description":"An error code for the error.",
            "type":"string"
        },
        "errorMessage":{
            "description":"Short failure explanation.",
            "type":"string"
        },
        "details":{
            "description":"Details about the error.",
            "type":"string"
        }
    },
    "additionalProperties":false
}

404 Response

Not found

Root Schema : schema

Type: object

Show Source

error(required): object ErrorResponse

{
    "type":"object",
    "properties":{
        "error":{
            "$ref":"#/definitions/ErrorResponse"
        }
    },
    "required":[
        "error"
    ],
    "additionalProperties":false,
    "example":{
        "error":{
            "httpStatus":404,
            "serviceErrorCode":"'ACCOUNT_NOT_FOUND' or 'SITE_NOT_FOUND' or 'CUSTOMER_NOT_FOUND'",
            "details":"'The customer does not have an active account for that given fuel type' or 'The customer does not have a service point for the given fuel type' or 'No customer with the given utilityCustomerId'"
        }
    }
}

Example:

{
    "error":{
        "httpStatus":404,
        "serviceErrorCode":"'ACCOUNT_NOT_FOUND' or 'SITE_NOT_FOUND' or 'CUSTOMER_NOT_FOUND'",
        "details":"'The customer does not have an active account for that given fuel type' or 'The customer does not have a service point for the given fuel type' or 'No customer with the given utilityCustomerId'"
    }
}

Nested Schema : ErrorResponse

Type: object

Show Source

details: string

Details about the error.
errorMessage: string

Short failure explanation.
httpStatus: integer

Minimum Value: 100

Maximum Value: 600

The HTTP status code for the error.
serviceErrorCode: string

An error code for the error.

{
    "type":"object",
    "properties":{
        "httpStatus":{
            "description":"The HTTP status code for the error.",
            "type":"integer",
            "minimum":100,
            "maximum":600
        },
        "serviceErrorCode":{
            "description":"An error code for the error.",
            "type":"string"
        },
        "errorMessage":{
            "description":"Short failure explanation.",
            "type":"string"
        },
        "details":{
            "description":"Details about the error.",
            "type":"string"
        }
    },
    "additionalProperties":false
}

500 Response

Internal server error

Root Schema : schema

Type: object

Show Source

error(required): object ErrorResponse

{
    "type":"object",
    "properties":{
        "error":{
            "$ref":"#/definitions/ErrorResponse"
        }
    },
    "required":[
        "error"
    ],
    "additionalProperties":false,
    "example":{
        "error":{
            "httpStatus":500,
            "serviceErrorCode":"'INSIGHT_UNAVAILABLE' or 'UNKNOWN'",
            "details":"'The insight was unavailable for the given customer. This could occur if the site has more than one service point, or if there are not enough similar neighbors to generate an insight' or 'An internal server error occurred'"
        }
    }
}

Example:

{
    "error":{
        "httpStatus":500,
        "serviceErrorCode":"'INSIGHT_UNAVAILABLE' or 'UNKNOWN'",
        "details":"'The insight was unavailable for the given customer. This could occur if the site has more than one service point, or if there are not enough similar neighbors to generate an insight' or 'An internal server error occurred'"
    }
}

Nested Schema : ErrorResponse

Type: object

Show Source

details: string

Details about the error.
errorMessage: string

Short failure explanation.
httpStatus: integer

Minimum Value: 100

Maximum Value: 600

The HTTP status code for the error.
serviceErrorCode: string

An error code for the error.

{
    "type":"object",
    "properties":{
        "httpStatus":{
            "description":"The HTTP status code for the error.",
            "type":"integer",
            "minimum":100,
            "maximum":600
        },
        "serviceErrorCode":{
            "description":"An error code for the error.",
            "type":"string"
        },
        "errorMessage":{
            "description":"Short failure explanation.",
            "type":"string"
        },
        "details":{
            "description":"Details about the error.",
            "type":"string"
        }
    },
    "additionalProperties":false
}