Jump to

• Request
• Response

Get Bill Comparison

get

/apis/billComparison-v2/{utilityCode}/bill-comparison/accounts/{utilityAccountId}

Returns a customer's bill comparsion. Compare a customer's electricity or gas bill to a prior bill (either previous bill or last year's bill) along with an explanation of the cost differences.

Request

Path Parameters

• utilityAccountId(required): number
  Unique utility account identifier. This value is returned as the id field when using the Get Utility Account List endpoint.
• utilityCode(required): string
  Unique code specific to utility company

Query Parameters

• asOf: string(date)
  The most recent bill that ends before the asOf date is chosen as reference one

  Default Value: NOW
• comparisonBill: string
  Type of bill to compare with. If there is no YEAR_AGO bill, fallback to PREVIOUS

  Default Value: PREVIOUS

  Allowed Values: [ "PREVIOUS", "YEAR_AGO" ]
• fallbackToPreviousPeriod: boolean
  Whether to use fallback from YEAR_AGO to PREVIOUS on missed bills

  Default Value: true

  Allowed Values: [ true, false ]

Back to Top

Response

Supported Media Types

• application/json

200 Response

Successful response

Body ()

Root Schema : billComparisonResponse

Type: object

Returns a single object representing a bill comparison

Show Source

• failureExplanation: string
  Allowed Values: [ "NOT_ENOUGH_USAGE_DATA" ]

  in case of unsuccessful comparison contains information about failure cause
• response(required): object response

{
    "type":"object",
    "description":"Returns a single object representing a bill comparison",
    "required":[
        "response"
    ],
    "properties":{
        "response":{
            "description":"contains bill-based comparison",
            "$ref":"#/definitions/response"
        },
        "failureExplanation":{
            "description":"in case of unsuccessful comparison contains information about failure cause",
            "type":"string",
            "enum":[
                "NOT_ENOUGH_USAGE_DATA"
            ]
        }
    },
    "example":{
        "response":{
            "meterUnit":"KWH",
            "currencySymbol":"$",
            "temperatureUnit":"FAHRENHEIT",
            "analysisResults":[
                {
                    "analysisName":"WEATHER",
                    "costDifferenceExplained":-176.44
                },
                {
                    "analysisName":"OTHER",
                    "costDifferenceExplained":-840.16
                }
            ],
            "reference":{
                "charges":76.48,
                "usage":865.857,
                "startDate":"2016-03-02",
                "endDate":"2016-03-31",
                "averageTemperature":48.3,
                "ratePlan":"AB"
            },
            "compared":{
                "charges":1093.08,
                "usage":1200,
                "startDate":"2016-02-01",
                "endDate":"2016-03-01",
                "averageTemperature":34.1,
                "ratePlan":"AB"
            }
        }
    }
}

Example:

{
    "response":{
        "meterUnit":"KWH",
        "currencySymbol":"$",
        "temperatureUnit":"FAHRENHEIT",
        "analysisResults":[
            {
                "analysisName":"WEATHER",
                "costDifferenceExplained":-176.44
            },
            {
                "analysisName":"OTHER",
                "costDifferenceExplained":-840.16
            }
        ],
        "reference":{
            "charges":76.48,
            "usage":865.857,
            "startDate":"2016-03-02",
            "endDate":"2016-03-31",
            "averageTemperature":48.3,
            "ratePlan":"AB"
        },
        "compared":{
            "charges":1093.08,
            "usage":1200,
            "startDate":"2016-02-01",
            "endDate":"2016-03-01",
            "averageTemperature":34.1,
            "ratePlan":"AB"
        }
    }
}

Nested Schema : response

Type: object

Show Source

• analysisResult: array analysisResult
  Contains bill difference insights
• compared: object bill
  The Bill object contains the bill attributes used to generate the comparison to the prior period.
• currencySymbol(required): string
  Defines currency for bill costs
• meterUnit: string
  Allowed Values: [ "KWH", "THERM", "GAL", "M3", "CCF", "MCF" ]

  Defines meter unit for bill usages
• reference: object bill
  The Bill object contains the bill attributes used to generate the comparison to the prior period.
• temperatureUnit(required): string
  Allowed Values: [ "FAHRENHEIT" ]

  Defines temparature unit for weather insight

{
    "type":"object",
    "required":[
        "currencySymbol",
        "temperatureUnit"
    ],
    "properties":{
        "meterUnit":{
            "description":"Defines meter unit for bill usages",
            "type":"string",
            "enum":[
                "KWH",
                "THERM",
                "GAL",
                "M3",
                "CCF",
                "MCF"
            ]
        },
        "currencySymbol":{
            "description":"Defines currency for bill costs",
            "type":"string"
        },
        "temperatureUnit":{
            "description":"Defines temparature unit for weather insight",
            "type":"string",
            "enum":[
                "FAHRENHEIT"
            ]
        },
        "analysisResult":{
            "description":"Contains bill difference insights",
            "type":"array",
            "items":{
                "$ref":"#/definitions/analysisResult"
            }
        },
        "reference":{
            "description":"Contains data for reference bill",
            "$ref":"#/definitions/bill"
        },
        "compared":{
            "description":"Contains data for compared bill",
            "$ref":"#/definitions/bill"
        }
    }
}

Nested Schema : analysisResult

Type: array

Contains bill difference insights

Show Source

• Array of: object analysisResult
  The Analysis Result contains the list of reasons for the difference from the prior bill and the amount monetary difference attributed to the reason

{
    "description":"Contains bill difference insights",
    "type":"array",
    "items":{
        "$ref":"#/definitions/analysisResult"
    }
}

Nested Schema : bill

Type: object

The Bill object contains the bill attributes used to generate the comparison to the prior period.

Show Source

• averageTemperature: number
  average temperature for bill period
• charges(required): number
  bill cost
• endDate(required): string(date)
  last day of the bill (inclusive)
• ratePlan: string
  bill rate plan
• startDate(required): string(date)
  first day of the bill
• usage(required): number
  bill usages

{
    "description":"The Bill object contains the bill attributes used to generate the comparison to the prior period.  ",
    "type":"object",
    "required":[
        "charges",
        "usage",
        "startDate",
        "endDate"
    ],
    "properties":{
        "charges":{
            "description":"bill cost",
            "type":"number"
        },
        "usage":{
            "description":"bill usages",
            "type":"number"
        },
        "startDate":{
            "description":"first day of the bill",
            "type":"string",
            "format":"date"
        },
        "endDate":{
            "description":"last day of the bill (inclusive)",
            "type":"string",
            "format":"date"
        },
        "averageTemperature":{
            "description":"average temperature for bill period",
            "type":"number"
        },
        "ratePlan":{
            "description":"bill rate plan",
            "type":"string"
        }
    }
}

Nested Schema : analysisResult

Type: object

The Analysis Result contains the list of reasons for the difference from the prior bill and the amount monetary difference attributed to the reason

Show Source

• analysisName(required): string
  Allowed Values: [ "WEATHER", "NUM_DAYS", "RATE_PLAN", "OTHER" ]

  The given reason for a change in cost between a reference bill and comparison bill
• costDifferenceExplained(required): number
  Value of the monetary difference of a reference and comparison bill due to the change defined by the name

{
    "description":"The Analysis Result contains the list of reasons for the difference from the prior bill and the amount monetary difference attributed to the reason",
    "type":"object",
    "required":[
        "analysisName",
        "costDifferenceExplained"
    ],
    "properties":{
        "analysisName":{
            "description":"The given reason for a change in cost between a reference bill and comparison bill",
            "type":"string",
            "enum":[
                "WEATHER",
                "NUM_DAYS",
                "RATE_PLAN",
                "OTHER"
            ]
        },
        "costDifferenceExplained":{
            "description":"Value of the monetary difference of a reference and comparison bill due to the change defined by the name",
            "type":"number"
        }
    }
}

401 Response

Authorization failure

Body ()

Root Schema : notAuthorizedErrorResponse

Type: object

Error reponse for unsuccessful bill comparison

Show Source

• error(required): object error
  Brief error explaination

{
    "description":"Error reponse for unsuccessful bill comparison",
    "type":"object",
    "required":[
        "error"
    ],
    "properties":{
        "error":{
            "$ref":"#/definitions/error"
        }
    },
    "example":{
        "error":{
            "httpStatus":401,
            "errorMessage":"Credentials are required to access this resource"
        }
    }
}

Example:

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

Nested Schema : error

Type: object

Brief error explaination

Show Source

• errorMessage(required): string
  human-readable failure cause explanation
• httpStatus(required): integer
  contains one of standart http error statuses

{
    "description":"Brief error explaination",
    "type":"object",
    "required":[
        "httpStatus",
        "errorMessage"
    ],
    "properties":{
        "httpStatus":{
            "description":"contains one of standart http error statuses",
            "type":"integer"
        },
        "errorMessage":{
            "description":"human-readable failure cause explanation",
            "type":"string"
        }
    }
}

404 Response

Utility account not found

Body ()

Root Schema : notFoundErrorResponse

Type: object

Error reponse for 'Not Found' http status

Show Source

• error(required): object error
  Brief error explaination

{
    "description":"Error reponse for 'Not Found' http status",
    "type":"object",
    "required":[
        "error"
    ],
    "properties":{
        "error":{
            "$ref":"#/definitions/error"
        }
    },
    "example":{
        "error":{
            "httpStatus":404,
            "errorMessage":"No utility account with id xxxx"
        }
    }
}

Example:

{
    "error":{
        "httpStatus":404,
        "errorMessage":"No utility account with id xxxx"
    }
}

Nested Schema : error

Type: object

Brief error explaination

Show Source

• errorMessage(required): string
  human-readable failure cause explanation
• httpStatus(required): integer
  contains one of standart http error statuses

{
    "description":"Brief error explaination",
    "type":"object",
    "required":[
        "httpStatus",
        "errorMessage"
    ],
    "properties":{
        "httpStatus":{
            "description":"contains one of standart http error statuses",
            "type":"integer"
        },
        "errorMessage":{
            "description":"human-readable failure cause explanation",
            "type":"string"
        }
    }
}

500 Response

Internal server error

Body ()

Root Schema : internalServerErrorResponse

Type: object

Error reponse for unsuccessful bill comparison

Show Source

• error(required): object error
  Brief error explaination

{
    "description":"Error reponse for unsuccessful bill comparison",
    "type":"object",
    "required":[
        "error"
    ],
    "properties":{
        "error":{
            "$ref":"#/definitions/error"
        }
    },
    "example":{
        "error":{
            "httpStatus":500,
            "errorMessage":"Comparison cannot be performed right now"
        }
    }
}

Example:

{
    "error":{
        "httpStatus":500,
        "errorMessage":"Comparison cannot be performed right now"
    }
}

Nested Schema : error

Type: object

Brief error explaination

Show Source

• errorMessage(required): string
  human-readable failure cause explanation
• httpStatus(required): integer
  contains one of standart http error statuses

{
    "description":"Brief error explaination",
    "type":"object",
    "required":[
        "httpStatus",
        "errorMessage"
    ],
    "properties":{
        "httpStatus":{
            "description":"contains one of standart http error statuses",
            "type":"integer"
        },
        "errorMessage":{
            "description":"human-readable failure cause explanation",
            "type":"string"
        }
    }
}

Back to Top