Home Energy Saver API Methods

Model a New Home

newSession

  • Starts a new HES session with user submitted zipcode
  • WSDL: session
  • Usage: newSession(client_guid, ZipCode, website_type)
  • Calls: retrieveSessionByID11
  • Parameters:
NameDescriptionTypePossible Values
client_guidUser's API keystring
zipcodePostal code for the home location, USPS Zip codestringUSPS ZipCode
Website_typeused by GUI, for API will always be zeroint0
  • Results: The input settings for the session.
  • Returns:
    • rowid, sortOrder, inputTableName, inputColumnName, formGroup, formForm, formSubForm, forSite, formInputName, formInputID, formInputType, formInputMinimumValue, formInputMaximumValue, formInputZeroAllowd, formInputIsRequired, defaultValue, sessionValue, possibleValues, textLabel
  • Example

Update an Already Modeled Home

saveSession11

  • Saves a collection of inputs to the database for a given session, optionally recalculates the session.
  • WSDL: session
  • Usage:saveSession11(client_guid, session_id, input_array, validate)
  • Parameters:
NameDescriptionTypePossible Values
client_guidUser's API keystring
session_idID number for the session assigned by newSessionint
input_arrayArray of API save input valuesArraySee API save inputs
validateSwitch indicating if session will be calculated on save0 (save only), 1 (save and calc)
  • Results: 
  • Returns: return code [1=success], return text
  • Example

Calculate an Existing Modeled Home

calcBaseHome11

  • Runs the calculation of cost and carbon emissions for the base home, and an upgraded efficient home. Since this does not change the inputs in most cases API users will want to use saveSession11 with the 'validate' switch to run the calculation. Use if session was saved but not previously calculated.
  • WSDL: calculate
  • Usage:calcBaseHome11(client_guid, session_id, profile)
  • Parameters:
NameDescriptionTypePossible Values
client_guidUser's API keystring
session_idID number for the session assigned by newSessionint
profile
  • Results: 
  • Returns: 
  • Example

Retrieve the Session Values for a Modeled home

retrieveSessionById11

  • Retrieves an existing HES session by id number
  • WSDL: session
  • Usage: retrieveSessionByID11(client_guid, session_id, session_type, website_type)
  • Called by: newSession
  • Parameters:
NameDescriptionTypePossible Values
client_guidUser's API keystring
session_idexisting HES session numberintset when session created
session_typeIndicator for input type, quick or detailedint0 (quick),1 (detailed)
website_typeused by GUI, for API will always be zeroint0
  • Results: The input settings for the session, both default and session values. Does not return results.
  • Returns: 
    • rowid, sortOrder, inputTableName, inputColumnName, formGroup, formForm, formSubForm, forSite, formInputName, formInputID, formInputType, formInputMinimumValue, formInputMaximumValue, formInputZeroAllowd, formInputIsRequired, defaultValue, sessionValue, possibleValues, textLabel
  • Examples: Detailed 

Retrieve Results for a Home

retrieveSessionResults11

  • Returns Compare page results for summary and detailed
  • WSDL: session
  • Usage: retrieveSessionResults11(client_guid,$session_id, page)
  • Parameters:
NameDescriptionTypePossible Values
client_guidUser's API keystring
session_idID number for the session assigned by newSessionint
PageName corresponding to page in GUIstring
  • Results:
  • Returns:
  • Example:

retrieveDetailedSessionResults11

  • Retrieves session results, data corresponds to the "Compare" pages in the HES website
  • WSDL: session
  • Usage: retrieveDetailedSessionResults11(client_guid, session_id)
  • Parameters:
NameDescriptionTypePossible Values
client_guidUser's API keystring
session_idID number for the session assigned by newSessionint
  • Results: Gives estimated whole house energy costs, percent improvement, and emissions for base and upgraded house; heating, cooling, lg. appliance, sm. appliance and lighting fuel consumption.
  • Returns:
    • sessionId, zip_city, zip_state, BaseCost, newcost, details (Array)
      • [details]: group, type, existing, upgrades, savings, percent
  • Example

retrieveSummarySessionResults11

  • Retrieves summary data, two arrays specific to the Compare page bar charts, these are the data for the top level "compare" page.
  • WSDL: session
  • Usage: retrieveSummarySessionResults11(client_guid, session_id)
  • Parameters:
NameDescriptionTypePossible Values
client_guidUser's API keystring
session_idID number for the session assigned by newSessionint
  • Results: House identifiers, total cost estimate- base and upgraded cases, "cars" contributes to the "cars off the road" metric, arrays used in the HES GUI bar charts (existing and efficient), arrays of enduse cost estimates (existingHouse, and withUpgrades)
  • Returns: sessionId, zip_city, zip_state, BaseCost, newcost, cars, existing (array), efficient (array), existingHome (array), withUpgrades (array)
    • [existing], [efficient]: width, home, heating, cooling, water_heating, major_appliances, lighting, small_appliances
    • [existingHome].[withUpgrades]: Total, Heating, Cooling, HotWater, LargeAppliances, SmallAppliances, Lighting
  • Example

Retrieve Results by End Uses for a Home

retrieveHeatCoolDetailedResults11

  • Retrieves the results for heating and cooling. Corresponds approximately to compare-heat-cool-details in HES website
  • WSDL: session
  • Usage: retrieveHeatCoolDetailedResults11(client_guid, session_id)
  • Parameters:
NameDescriptionTypePossible Values
client_guidUser's API keystring
session_idID number for the session assigned by newSessionint
  • Results:Energy and Costs estimates for heating, cooling and combined; main and auxiliary equipment
  • Returns: totalCost, heatingCost, coolingCost, totalEnergy, heatEnergyTotal, coolEnergyTotal, mainHeatingType, mainHeatingCode, mainHeatingCostFuel, mainHeatingCostElect, mainHeatingCostCirc, mainHeatingEnergyFuel, mainHeatingEnergyElect, mainHeatingEnergyCirc, gasFireplaceCostFuel, gasFireplaceCostElect, gasFireplaceCostCirc, gasFireplaceEnergyFuel, gasFireplaceEnergyElect, gasFireplaceEnergyCirc, mainCoolingType, mainCoolingCostElect, mainCoolingCostCirc, mainCoolingEnergyElect, mainCoolingEnergyCirc, wholeHouseFanCostElect, wholeHouseFanCostCirc, wholeHouseFanEnergyElect, wholeHouseFanEnergyCirc, portableFanCostElect, portableFanCostCirc, portableFanEnergyElect, portableFanEnergyCirc, ceilingFanCostElect, ceilingFanCostCirc, ceilingFanEnergyElect, ceilingFanEnergyCirc, woodStovePercent, mainHeatingPercent, mainCoolingPercent
  • Example

retrieveHeatCoolSummaryResults11

  • Retrieves the summary results for heating and cooling. Corresponds approximately to compare-heat-cool-summary page in HES website.
  • WSDL: session
  • Usage: retrieveHeatCoolSummaryResults11(client_guid, session_id)
  • Parameters:
NameDescriptionTypePossible Values
client_guidUser's API keystring
session_idID number for the session assigned by newSessionint
  • Results: Energy and Costs estimates for heating, cooling and combined; heating by fuel, percent floor area for main heating, main cooling and wood stove.
  • Returns:
    • totalCost, heatingCost, coolingCost, totalEnergy, heatEnergyTotal, coolEnergyTotal ,heatEnergyElect, heatEnergyGas, heatEnergyOil, heatEnergyLpg, woodStovePercent, mainHeatingPercent, mainCoolingPercent
  • Example

retrieveLargeAppDetailedResults11

  • Retrieves detailed results for all "large appliance" equipment, both energy costs and use.
  • WSDL: session
  • Usage: retrieveLargeAppDetailedResults11(client_guid, session_id)
  • Parameters:
NameDescriptionTypePossible Values
client_guidUser's API keystring
session_idID number for the session assigned by newSessionint
  • Results: Energy use and cost, and water usage by large appliances
  • Returns: firstFridgeTotalEnergy, firstFridgeTotalCost, firstFridgeEquipEnergy, firstFridgeEquipCost, firstFridgeWaterUse, firstFridgeWaterEnergy, firstFridgeWaterCost, firstFridgeEnergyUnit, secondFridgeTotalEnergy, secondFridgeTotalCost, secondFridgeEquipEnergy, secondFridgeEquipCost, secondFridgeWaterUse, secondFridgeWaterEnergy, secondFridgeWaterCost, secondFridgeEnergyUnit, thirdFridgeTotalEnergy, thirdFridgeTotalCost, thirdFridgeEquipEnergy, thirdFridgeEquipCost, thirdFridgeWaterUse, thirdFridgeWaterEnergy, thirdFridgeWaterCost, thirdFridgeEnergyUnit, firstFreezerTotalEnergy, firstFreezerTotalCost, firstFreezerEquipEnergy, firstFreezerEquipCost, firstFreezerWaterUse, firstFreezerWaterEnergy, firstFreezerWaterCost, firstFreezerEnergyUnit, secondFreezerTotalEnergy, secondFreezerTotalCost, secondFreezerEquipEnergy, secondFreezerEquipCost, secondFreezerWaterUse, secondFreezerWaterEnergy, secondFreezerWaterCost, secondFreezerEnergyUnit, stoveEnergyUnit, stoveTotalEnergy, stoveTotalCost, stoveEquipEnergy, stoveEquipCost, stoveWaterUse, stoveWaterEnergy, stoveWaterCost, ovenEnergyUnit, ovenTotalEnergy, ovenTotalCost, ovenEquipEnergy, ovenEquipCost, ovenWaterUse, ovenWaterEnergy, ovenWaterCost, clothesDryerEnergyUnit, clothesDryerTotalEnergy, clothesDryerTotalCost, clothesDryerEquipEnergy, clothesDryerEquipCost, clothesDryerWaterUse, clothesDryerWaterEnergy, clothesDryerWaterCost, clothesWasherEnergyUnit, clothesWasherTotalEnergy, clothesWasherTotalCost, clothesWasherEquipEnergy, clothesWasherEquipCost, clothesWasherWaterUse, clothesWasherWaterEnergy, clothesWasherWaterCost, dishWasherEnergyUnit, dishWasherTotalEnergy, dishWasherTotalCost, dishWasherEquipEnergy, dishWasherEquipCost, dishWasherWaterUse, dishWasherWaterEnergy, dishWasherWaterCost, tapsFaucetsTotalEnergy, tapsFaucetsTotalCost, tapsFaucetsEquipEnergy, tapsFaucetsEquipCost, tapsFaucetsWaterUse, tapsFaucetsWaterEnergy, tapsFaucetsWaterCost, poolPumpTotalEnergy, poolPumpTotalCost, poolPumpEquipEnergy, poolPumpEquipCost, poolPumpWaterUse, poolPumpWaterEnergy, poolPumpWaterCost, poolPumpEnergyUnit, spaTotalEnergy, spaTotalCost, spaEquipEnergy, spaEquipCost, spaWaterUse, spaWaterEnergy, spaWaterCost, sumpPumpTotalEnergy, sumpPumpTotalCost, sumpPumpEquipEnergy, sumpPumpEquipCost, sumpPumpWaterUse, sumpPumpWaterEnergy, sumpPumpWaterCost, sumpPumpEnergyUnit, wellPumpTotalEnergy, wellPumpTotalCost, wellPumpEquipEnergy, wellPumpEquipCost, wellPumpWaterUse, wellPumpWaterEnergy, wellPumpWaterCost, wellPumpEnergyUnit, totalCost, totalEquipCost, totalEquipKwh, totalEquipTherms, hotWaterFuel, hotWaterEnergyUnit, totalWaterUse, totalWaterEnergy, totalWaterCost
  • Example

retrieveLargeAppSummaryResults11

  • Retrieves the energy cost results for a limited set of large appliances 
  • WSDL: session
  • Usage: retrieveLargeAppSummaryResults11(client_guid, session_id)
  • Parameters:
NameDescriptionTypePossible Values
client_guidUser's API keystring
session_idID number for the session assigned by newSessionint
  • Results:Energy cost estimates for refrigeration, cooking and clothes and dishwashing, pool, spa and pumps, and total.
  • Returns:firstFridgeCost, secondFridgeCost, thirdFridgeCost, firstFreezerCost, secondFreezerCost, stoveCost, ovenCost, clothesDryerCost, clothesWasherCost, dishwasherCost, hwSinksFaucetsCost, poolCost, spaCost, sumpPumpCost, wellPumpCost, totalCost
  • Example

retrieveLightingDetailedResults11

  • WSDL: session
  • Usage: retrieveLigihtingDetailedResults11(client_guid, session_id)
  • Parameters:
NameDescriptionTypePossible Values
client_guidUser's API keystring
session_idID number for the session assigned by newSessionint
  • Results:
  • Returns:
  • Example

retrieveLightingSummaryResults11

  • WSDL: session
  • Usage: retrieveLightingSummaryResults11(client_guid, session_id)
  • Parameters:
NameDescriptionTypePossible Values
client_guidUser's API keystring
session_idID number for the session assigned by newSessionint
  • Results: An array with number of elements equal to the number of fixture instances. 
  • Returns: rowID, sessionID, roomName, instanceNumber, lightingFixtureEnergy, lightingFixtureCost
  • Example

retrieveMonthlySessionResults11

  • This is part of the tariff function, it is currently deactivated
  • WSDL: session
  • Usage: retrieveMonthlySessionResults11(client_guid, session_id)
  • Parameters:
NameDescriptionTypePossible Values
client_guidUser's API keystring
session_idID number for the session assigned by newSessionint
  • Results:na
  • Returns: na
  • Example

retrieveSessionCompare11 (deprecated)

  • Retrieves pre-calculated results for RECS based climate zone, "a typical home in your area"
  • WSDL: session
  • Usage: retrieveSessionCompare(client_guid, session_id, page) 
  • Parameters:
NameDescriptionTypePossible Values
client_guidUser's API keystring
session_idID number for the session assigned by newSessionint
pageName corresponding to page in GUIstring
  • Results:The method tests whether the page attribute is "compare-1" and if so, retrieves the results of that. Compare-1 was formerly the "landing" page when creating a new session, it shows the regional results for the RECS based climate zones. This is not used in the current design, and for API users the method should be considered deprecated.
  • Return: 

retrieveSmallAppDetailedResults11

  • Retrieves the energy use and cost estimates for small appliances
  • WSDL: session
  • Usage: retrieveSmallAppdetailedResults11(client_guid, session_id)
  • Parameters:
NameDescriptionTypePossible Values
client_guidUser's API keystring
session_idID number for the session assigned by newSessionint
  • Results:by enduse results for entertainment, home office, kitchen, and "other" small appliance
  • Return: please see example
  • Example

retrieveSmallAppSummaryResults11

  • Retrieves energy and cost results for small appliance by category 
  • WSDL: session
  • Usage: retrieveSmallApplianceSummaryResults11(client_guid, session_id)
  • Parameters:
NameDescriptionTypePossible Values
client_guidUser's API keystring
session_idID number for the session assigned by newSessionint
  • Results: Energy and cost estimates for entertainment, home office, kitchen, and "other" enduses
  • Returns: Entertainment_Energy, Entertainment_Cost, Home_Office_Energy, Home_Office_Cost, Miscellaneous_Kitchen_Energy, Miscellaneous_Kitchen_Cost, Other_Appliances_Energy, Other_Appliances_Cost
  • Example

Upgrades

retrieveUpgradesResult11

  • WSDL: session
  • Usage: retrieveUpgradeResults11(client_guid, session_id, page)
  • Parameters:
NameDescriptionTypePossible Values
client_guidUser's API keystring
session_idID number for the session assigned by newSessionint
pagePage description corresponding to the page names in the GUIstringupgrade, upgrade-details, upgrade-recommend
  • Results: varies depending on page selected
  • Returns:
  • Example:

Session Managment

retrieveSessionHistoryByGuid11

  • Retrieves a list of the user's existing sessions from the session_history table
  • WSDL: session
  • Usage: retrieveSessionHistoryByGuid11(client_guid, $session_id, facebookId)
  • Parameters:
NameDescriptionTypePossible Values
client_guidUser's API keystring
session_idID number for the session assigned by newSessionint
facebookIdThe user's facebook IDstring
  • Results: Array
  • Returns:
  • Example

switchSession

  • Changes the session type from quick inputs to detailed and back
  • WSDL: session
  • Usage: switchSession(client_guid, session_id, direction, website_type)
  • Parameters:
NameDescriptionTypePossible Values
client_guidUser's API keystring
session_idID number for the session assigned by newSessionint
directionIndicates session type to switch tostringquick2detailed, detailed2quick
website_typeUsed by GUI, for API will always be zeroint0
  • Results:
  • Returns:
  • Example
  • Note: This is primarily used by the HES GUI and of little use to API users as all inputs are available

Report

retrieveSessionReports11 (deprecated)

  • WSDL: session
  • Usage:retrieveSessionReports11(client_guid, session_id, page, website_type)
  • Parameters:
NameDescriptionTypePossible Values
client_guidUser's API keystring
session_idID number for the session assigned by newSessionint
pageName corresponding to page in GUIstring
website_typeUsed by GUI, for API will always be zeroint
  • Returns:
  • Example:
  • Note: this method is deprecated, use the individual retrieves instead