UtilityScore Savings API Documentation

UtilityScore Attribution Logo

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/getsavings

Method : GET

Api-Key passed through Header

Sample Call:
https://api.myutilityscore.com/getsavings?data={"has_property_data":false,"home_type":"SF", "address":"3341 El Dorado Loop S","city":"Salem, Or", "post_code":"97302","year_built":"1991", "home_area":"5194", "lot_area":"6458", "has_solar":false,"solar_capacity":"7","daytimeocc":false}

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 photovoltaic 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

data = {
          "has_property_data": true,
          "home_type": "SF",
          "address": "652 Folsom St",
          "city": "San Francisco, CA",
          "post_code": "91342",
          "year_built": "1948",
          "home_area": "1600",
          "lot_area": "3600",
          "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":true,
          "solar_capacity":"7",
          "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
USID UtilityScore ID, unique for each address String
response Response code and description (e.g., 200: Success, 410: Not available for this property) String
utility_score Home’s current UtilityScore (1-100) Int
ACHT_Duct_billsavings_annual Estimated annual utility bill savings from installing new heating and cooling ducts Decimal
ACHT_Duct_scorechange Change in UtilityScore as a result of installing this project Int
AC_Central_billsavings_annual High-efficiency central air conditioning Decimal
AC_Central_scorechange Change in UtilityScore as a result of installing this project Int
AC_MiniSplit_billsavings_annual High-efficiency mini-split air conditioner Decimal
AC_MiniSplit_scorechange Change in UtilityScore as a result of installing this project Int
BF_billsavings_annual Low-flow WaterSense bathroom faucet Decimal
total_bill_annual Total annual utility bill Currency
BF_scorechange Change in UtilityScore as a result of installing this project Int
CW_billsavings_annual ENERGY STAR front-loading clothes washer Decimal
CW_scorechange Change in UtilityScore as a result of installing this project Int
DW_billsavings_annual ENERGY STAR dishwasher Decimal
DW_scorechange Change in UtilityScore as a result of installing this project Int
HT_NatGas_billsavings_annual High-efficiency natural gas furnace Decimal
HT_NatGas_scorechange Change in UtilityScore as a result of installing this project Int
HT_HeatPump_billsavings_annual High-efficiency electric heat pump furnace Decimal
HT_HeatPump_scorechange Change in UtilityScore as a result of installing this project Int
KF_billsavings_annual Low-flow kitchen faucet Decimal
KF_scorechange Change in UtilityScore as a result of installing this project Int
RF_BM_billsavings_annual ENERGY STAR refrigerator: bottom-mounted freezer Decimal
RF_BM_scorechange Change in UtilityScore as a result of installing this project Int
RF_SBS_billsavings_annual ENERGY STAR refrigerator: side-by-side freeze Decimal
RF_SBS_scorechange Change in UtilityScore as a result of installing this project Int
RF_TM_billsavings_annual ENERGY STAR refrigerator: top-mounted freezer Decimal
RF_TM_scorechange Change in UtilityScore as a result of installing this project Int
SH_billsavings_annual Low-flow WaterSense showerhead Decimal
SH_scorechange Change in UtilityScore as a result of installing this project Int
SL_billsavings_annual Rooftop solar/photovoltaics Decimal
SL_scorechange Change in UtilityScore as a result of installing this project Int
TL_1.28_billsavings_annual 1.28 gallon per flush toilet Decimal
TL_1.28_scorechange Change in UtilityScore as a result of installing this project Int
TL_1.00_billsavings_annual Change in UtilityScore as a result of installing this project Decimal
TL_1.00_scorechange Change in UtilityScore as a result of installing this project Int
WH_Gas_Tank_billsavings_annual High-efficiency gas tank water heater Decimal
WH_Gas_Tank_scorechange Change in UtilityScore as a result of installing this project Int
WH_Gas_Tankless_billsavings_annual High-efficiency gas tankless water heater Decimal
WH_Gas_Tankless_scorechange Change in UtilityScore as a result of installing this project Int
WH_Elec_Tank_billsavings_annual High-efficiency electric tank water heater Decimal
WH_Elec_Tank_scorechange Change in UtilityScore as a result of installing this project Int
WH_Elec_Tankless_billsavings_annual High-efficiency electric tankless water heater Decimal
WH_Elec_Tankless_scorechange Change in UtilityScore as a result of installing this project Int
WN_DP_billsavings_annual ENERGY STAR double-pane windows Decimal
WN_DP_scorechange Change in UtilityScore as a result of INTEGER installing this project Int
WN_TP_billsavings_annual ENERGY STAR triple-pane windows Decimal
WN_TP__scorechange Change in UtilityScore as a result of INTEGER installing this project Int
as_of Month and year. Month that output was processed. UtilityScore values expire on the 3rd day of the following month (or next business day if the 3rd is a weekend or holiday) following the as_of date String

Response header example

  • Cache-Control:   public
  • Connection:   close
  • Content-Length:   1353
  • Content-Type   application/json
  • Date:   Tue, 06 Dec 2016 19:40:18 GMT
  • Expires:   Thu, 5 Jan 2017 0:00:00 GMT

Response parameter example

{
     "code":  200,
     "message":  "success",
     "data":  {
                    "utility_score":  26,
                    "currency_unit":  "USD",
                    "ACHT_Duct_billsavings_annual":  137,
                    "ACHT_Duct_scorechange":  1,
                    "AC_Central_billsavings_annual":  0,
                    "AC_Central_scorechange":  0,
                    "AC_MiniSplit_billsavings_annual":  0,
                    "AC_MiniSplit_scorechange":  0,
                    "BF_billsavings_annual":  15,
                    "BF_scorechange":  1,
                    "CW_billsavings_annual":  102,
                    "CW_scorechange":  2,
                    "DW_billsavings_annual":  8,
                    "DW_scorechange":  1,
                    "HT_NatGas_billsavings_annual":  137,
                    "HT_NatGas_scorechange":  1,
                    "HT_HeatPump_billsavings_annual":  487,
                    "HT_HeatPump_scorechange":  3,
                    "KF_billsavings_annual":  26,
                    "KF_scorechange":  1,
                    "RF_BM_billsavings_annual":  6,
                    "RF_BM_scorechange":  1,
                    "RF_SBS_billsavings_annual":  10,
                    "RF_SBS_scorechange":  1,
                    "RF_TM_billsavings_annual":  19,
                    "RF_TM_scorechange":  1,
                    "SH_billsavings_annual":  46,
                    "SH_scorechange":  1,
                    "SL_billsavings_annual":  1224,
                    "SL_scorechange":  43,
                    "TL_1.28_billsavings_annual":  53,
                    "TL_1.28_scorechange":  2,
                    "TL_1.00_billsavings_annual":  65,
                    "TL_1.00_scorechange":  2,
                    "WH_Gas_Tank_billsavings_annual":  74,
                    "WH_Gas_Tank_scorechange":  1,
                    "WH_Gas_Tankless_billsavings_annual":  115,
                    "WH_Gas_Tankless_scorechange":  1,
                    "WH_Elec_Tank_billsavings_annual":  92,
                    "WH_Elec_Tank_scorechange":  1,
                    "WH_Elec_Tankless_billsavings_annual":  100,
                    "WH_Elec_Tankless_scorechange":  1,
                    "WN_DP_billsavings_annual":  167,
                    "WN_DP_scorechange":  1,
                    "WN_TP_billsavings_annual":  239,
                    "WN_TP_scorechange":  1,
                    "as_of":  "2016-12-06 UTC"
                    }
}

API Display Requirements

  • 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).