HES Pro/Con API

Please note that this page is deprecated, the current version is here.

The Session Inputs, as distinct from the API methods, are described in the API save inputs workbook.

newSession

• • Starts a new HES session; session is created based on quick inputs, retrieveSessionById is called to return input array

• Called by:

• Calls: retrieveSessionByID11

• Parameters:

• 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: see retrieveSessionByID

retrieveDetailedSessionResults11

• • Retrieves session results, data corresponds to the "Compare" pages in HES website

• Called by:

• Calls:

• Parameters:

• Results: Gives estimated whole house energy costs % improvement, and emissions for base and upgraded house;  heating, cooling, lg. appliance, sm. appliance and lighting fuel consumption, 5 improvement and emissions also for base and upgraded home.

• Returns:

  • sessionId, zip_city, zip_state, BaseCost, newcost, details (Array)

    • [details]: group, type, exiting, upgrades, savings, percent]

• Example

retrieveHeatCoolDetailedResults11

• • Retrieves the results for heating and cooling. Corresponds approximately to compare-heat-cool-details

• Called by:

• Calls:

• Parameters:

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

• Called by:

• Calls:

• Parameters:

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

• Called by:

• Calls:

• Parameters:

• 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

• Called by:

• Calls:

• Parameters:

• 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

• Called by:

• Calls:

• Parameters:

• Results:

• Returns:

• Example

retrieveLightingSummaryResults11

• Called by:

• Calls:

• Parameters:

• 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

• Called by:

• Calls:

• Parameters:

• Results:na

• Returns: na

• Example

 retrieveSessionHistoryByGuid11

• Retrieve a list of sessions from the session_history table

• Called by:

• Calls:

• Parameters:

• • Results: Array

  • Returns:

  • Example

retrieveSessionById11

• retrieves an existing HES session by id number

• Called by: newSession

• Calls:

• Parameters: Name/ Description / Type / Possible values

• Results: The input settings for the GUI

• Returns:

  • rowid, sortOrder, inputTableName, inputColumnName, formGroup, formForm, formSubForm, forSite, formInputName, formInputID, formInputType, formInputMinimumValue, formInputMaximumValue, formInputZeroAllowd, formInputIsRequired, defaultValue, sessionValue, possibleValues, textLabel

• Example

retrieveSessionCompare11

• • Retrieves pre-calculated results for LBNL's RECS based climate zones

• Called by:

• Calls:

• Parameters:

• 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 probably be considered deprecated.

• Return:

retrieveSessionReports11

• Called by:

• Calls:

• Parameters:

• Results:

• Returns

• Example:

retrieveSessionResults11

• • Returns Compare page results for summary and detailed

• Called by:

• Calls:

• Parameters:

• Results:

• Returns:

• Example:

retrieveSessionUpgrades11

• Called by:

• Calls:

• Parameters:

• Results:

• Return:

• Example

retrieveSmallAppDetailedResults11

• • Retrieves the energy use and cost estimates for small appliances

• Called by:

• Calls:

• Parameters:

• 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

• Called by:

• Calls:

• Parameters:

• 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

retrieveSummarySessionResults11

• • Retrieves summary data, two arrays specific the the Compare page bar charts, these are the data for the top level "compare" page.

• Called by:

• Calls:

• Parameters:

• 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 to 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

retrieveUpgradesResult11

• Called by:

• Calls:

• Parameters:

• Results:

• Returns:

• Example

saveSession11

• • Saves a collection of inputs to the database for a given session, optionally recalculates the session.

• Called by:

• Calls:

• Parameters:

• Results:

• Returns: return code, return text

• Example

switchSession

• Called by:

• Calls:

• Parameters:

• • Notes:

    • direction  quick2detailed, detailed2quick(?- check)

  • website_type  0 (check- Adrian sent code with 1 in this position and the parameter not named. Previously website_type had always been 0)

• Results:

• Returns:

• Example

Deprecated methods in V. 1.1

sessionHistoryManagement

retrieveMessage

cloneSession

importSessionData

importRangeSessionData