UtilityScore Bill API Documentation

UtilityScore Attribution Widget

Note: Per the UtilityScore Terms of Use, the API must be used in conjunction with with the UtilityScore Attribution Logo, which is accessed here.

UtilityScore API

URL : http://api.myutilityscore.com/getutilityscore

Method : POST

Api-Key passed through Header

Parameter name Required? Description Valid responses

has_property_data

Yes

Indicates whether the request will include basic property characteristic data

Ex: "has_property_data": True

True

home_type

Yes

Type of residential property

SF: Single-family detached 2to4: Duplex, triplex, or quadplex MF: Multifamily building with 5 or more units

Other: Lots, mobile homes

Ex: "home_type":"SF"

Valid Responses:
"SF"
"2to4"
"MF"
"Other"

address

Yes

Full street address

Ex: "address":"652 Folsom St"

String

city

Yes

City name and territory code

Ex: "city":"Los Angeles, CA"

String

post_code

Yes

Postal code

Ex: "post_code":"90063"

5-digit number

year_built

Yes

Year the home was built

Ex: "year_built": "1948"

4-digit number

home_area

Yes

Size (area) of the home in sqft

Ex: "home_area": "773"

Float

lot_area

Yes

Lot size (area) in sqft

Ex: "lot_area": "27225"

Float

space_heating_fuel

Optional

Default if omitted: Default value for local comparison area

Space heating fuel type

Ex: "space_heating_fuel": "Gas"

Valid Responses:
"Gas"
"Electric"

water_heating_fuel

Optional

Default if omitted: Default value for local comparison area

Water heating fuel type

Ex: "water_heating_fuel" : "Gas"

Valid Responses:
"Gas"
"Electric"

has_air_conditioning

Optional

Default if omitted: Default value for local comparison area

Presence of air conditioning at home

Ex: "has_air_conditioning": True

Boolean

air_conditioning_type

Optional

Default if omitted: Default value for local comparison area

Air conditioning type

Ex: "air_conditioning_type": "Central"

Valid responses:
"Central"
"Room"

has_pool

Optional

Default if omitted: False

Presence of a swimming pool on the property

Ex: "has_pool": False

Boolean

num_occupants

Optional

Default if omitted: 3

Number of occupants

Ex: "num_occupants": "3"

Int

daytimeocc

Optional

Default if omitted: False

Day time occupancy

Ex: "daytimeocc": False

Boolean

winter_thermostat_setting

Optional

Default if omitted: 68

Winter thermostat setting (deg F)

Ex: "winter_thermostat_setting": "70"

Int

summer_thermostat_setting

Optional

Default if omitted: 74

Summer thermostat setting (deg F)

Ex: "summer_thermostat_setting": "72"

Int

has_solar

Optional

Default if omitted: False

Does the home have a rooftop photovoltaix system?

Ex: "has_solar":True

Boolean

solar_capacity

Optional

Default if omitted: 4.5

Size of rooftop photovoltaic system (in kW)

Only works if has_solar=True

Ex: "solar_capacity":"4.5"

Float (whole numbers and decimals)

has_electricity

Optional

Default if omitted: True

Does the home receive electricity service from a utility? (e.g., not an on-site generator)

Ex: "has_electricity":True

Boolean

has_naturalgas

Optional

Default if omitted: True

Does the home receive natural gas service from a utility? (e.g., not propane, fuel oil, etc.)

Ex: "has_naturalgas":True

Boolean

has_water

Optional

Default if omitted: True

Does the home receive water service from a utility? (e.g., not a well)

Ex: "has_water":True

Boolean

has_sewer

Optional

Default if omitted: True

Does the home receive sewer service from a utility? (e.g., not a septic system)

Ex: "has_sewer":True

Boolean

Request Parameter Example

{
          "has_property_data": true,
          "home_type": "SF",
          "address": "5281 Clearbrook Dr",
          "city": "5281 Clearbrook Dr",
          "post_code": "94521",
          "year_built": "2007",
          "home_area": "2493",
          "lot_area": "5800",
          "has_air_conditioning": true,
          "space_heating_fuel": "Gas",
          "water_heating_fuel": "Gas",
          "air_conditioning_type": "Central",
          "has_pool": false,
          "has_spa": false,
          "num_occupants": "3",
          "daytimeocc": false,
          "winter_thermostat_setting": "64",
          "summer_thermostat_setting": "74",
          "has_solar":false,
          "solar_capacity":false,
          "has_electricity":true,
          "has_naturalgas":true,
          "has_water":true,
          "has_sewer":true
}

Exceptions

Success code Message Description
405 Invalid or missing city If you not entered or invalid city then you will get “Invalid or missing city”
406 Invalid or missing post_code If you not entered or invalid post_code then you will get “Invalid or missing post_code”
407 Invalid or missing year_built If you not entered or invalid year_built then you will get “Invalid or missing year_built”
408 Invalid or missing conditioned_area If you not entered or invalid conditioned_area then you will get “Invalid or missing conditioned_area”
409 Invalid or missing lot_area If you not entered or invalid conditioned_area then you will get “Invalid or missing lot_area”
404 Result not found. Result not found from database then it will return this error.

Response parameters

Response Parameter Name Description Unit
electricity_ bill_monthly Monthly electricity bill Currency
electricity_bill_annual Annual electricity bill Currency
electricity_bill_peak_summer Peak summer electricity bill Currency
natural_gas_monthly Monthly natural gas bill Currency
natural_gas_annual Annual natural gas bill Currency
natural_gas_peak_winter Peak winter natural gas bill Currency
natural_gas_peak_winter Peak winter natural gas bill Currency
water_sewer_monthly Monthly water sewer bill Currency
water_sewer_annual Annual water sewer bill Currency
water_sewer_peak_summer Peak summer water sewer bill Currency
electricity_ bill_current_month Current month electricity bill Currency
natural_gas_bill_current_month Current month natural gas bill Currency
water_sewer_bill_current_month Current month water sewer bill Currency
bill_current_month Total current monthly bill Currency
total_bill_annual Total annual utility bill Currency
neighborhood_bill_annual Median neighborhood annual utility bills Currency
neighborhood_utility_score Neighborhood utility score Number
utility_score Utility score Number
as_of Date that outputs were produced String
currency_unit Currency unit String

Response parameter example

{
          "code": 200,
          "message": "success",
          "data": {
                    "electricity_ bill_monthly": "169",
                    "electricity_bill_annual": "2032",
                    "electricity_bill_peak_summer": "215",
                    "natural_gas_monthly": "43",
                    "natural_gas_annual": "519",
                    "natural_gas_peak_winter": "55",
                    "water_sewer_monthly": "103",
                    "water_sewer_annual": "1241",
                    "water_sewer_peak_summer": "116",
                    "electricity_bill_current_month": "147",
                    "natural_gas_bill_current_month": "61",
                    "water_sewer_bill_current_month": "89",
                    "bill_current_month": "297",
                    "total_bill_annual": "3792",
                    "neighborhood_bill_annual": "4008",
                    "neighborhood_utility_score": "30",
                    "utility_score": 46,
                    "as_of": "2016-12-22 UTC",
                    "currency_unit": "USD"
          }
}

API Display Requriements

  • As_of parameter must be displayed next to any data returned by UtilityScore Savings API
  • For any cached request, if expiration date has been met then a new request must be made

UtilityScore Introduction

View our UtilityScore API introduction presentation here (PDF).