HVAC Estimate Savings API Documentation

Overview

This endpoint calculates estimated cost savings for HVAC systems based on optimization strategies. It supports two calculation types:

Monthly: Returns detailed hourly data for a specific time period
Annual: Returns annualized savings estimates

Authentication

Requires API Key authentication via ApiKeyGuard.

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Home ID (UUID)

Request Body

Base Fields

Field	Type	Required	Default	Description
`type`	enum	Yes	-	Calculation type: `"monthly"` or `"annual"`
`targetTemp`	number (Fahrenheit)	No	72	Target temperature in Fahrenheit
`targetCoolSetpoint`	number (Fahrenheit)	No	`targetTemp + 1`	Target cooling setpoint in Fahrenheit
`targetHeatSetpoint`	number (Fahrenheit)	No	`targetTemp - 1`	Target heating setpoint in Fahrenheit
`minTemp`	number (Fahrenheit)	No	70	Minimum allowed temperature in Fahrenheit
`maxTemp`	number (Fahrenheit)	No	74	Maximum allowed temperature in Fahrenheit
`heatTransferCoefficient`	number	No	1	Heat transfer coefficient for thermal modeling
`irradianceCoefficient`	number	No	0.5	Solar irradiance coefficient
`coolingRate`	number	No	1	Cooling rate multiplier
`heatingRate`	number	No	1	Heating rate multiplier
`mode`	enum	Yes	-	HVAC mode: `"AUTO"`, `"COOL"`, `"HEAT"`, or `"OFF"`
`days`	number	No	1	Number of days to simulate

Monthly Type Specific Fields

Field	Type	Required	Description
`start`	object	No	Start time configuration. Either `{month: number}` or `{startTime: Date}`
`startTime`	Date (ISO string)	No	Deprecated - Use `start` object instead. Start time for the calculation

Annual Type Specific Fields

Field	Type	Required	Description
`months`	number[] \| null	No	Array of month indices (0-11) to include. If null, all 12 months are included

Request Examples

Monthly Calculation Example

{
  "type": "monthly",
  "targetTemp": 72,
  "targetCoolSetpoint": 73,
  "targetHeatSetpoint": 71,
  "minTemp": 70,
  "maxTemp": 74,
  "heatTransferCoefficient": 1,
  "irradianceCoefficient": 0.5,
  "coolingRate": 1,
  "heatingRate": 1,
  "mode": "AUTO",
  "start": {
   1
  },
  "days": 1,
}

Annual Calculation Example

{
  "type": "annual",
  "targetTemp": 72,
  "minTemp": 70,
  "maxTemp": 74,
  "mode": "AUTO",
  "days": 1,
  "months": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12]
}

Response

The response structure depends on the type parameter.

Monthly Response

Field	Type	Description
`zipcode`	string	Home zipcode
`percentageSaved`	number	Percentage of cost saved (0-1)
`dollarsSaved`	number	Total dollars saved
`optimizedCost`	number	Total cost with optimization
`baselineCost`	number	Total cost without optimization (baseline)
`outdoorTemp`	number[]	Array of outdoor temperatures for each hour (Fahrenheit)
`temperatureData`	number[]	Array of optimized indoor temperatures for each hour (Fahrenheit)
`hvacConsumption`	number[]	Array of optimized HVAC consumption for each hour (kWh)
`baselineTemperatureData`	number[]	Array of baseline indoor temperatures for each hour (Fahrenheit)
`baselineHvacConsumption`	number[]	Array of baseline HVAC consumption for each hour (kWh)
`length`	number	Number of data points (hours)
`setPointList`	number[]	Array of setpoint temperatures for each hour (Fahrenheit)

Annual Response

Field	Type	Description
`zipcode`	string	Home zipcode
`leapRevenue`	number \| undefined	LEAP revenue (if applicable)
`dollarsSaved`	number	Annual dollars saved
`percentageSaved`	number	Annual percentage saved (0-1)
`optimizedCost`	number	Annual optimized cost
`baselineCost`	number	Annual baseline cost
`optimizedEnergy`	number	Annual optimized energy consumption (kWh)
`baselineEnergy`	number	Annual baseline energy consumption (kWh)
`energyReduction`	number	Annual energy reduction (kWh)
`annualDollarsSaved`	number	Same as `dollarsSaved` (for compatibility)
`annualPercentageSaved`	number	Same as `percentageSaved` (for compatibility)
`annualOptimizedCost`	number	Same as `optimizedCost` (for compatibility)
`annualBaselineCost`	number	Same as `baselineCost` (for compatibility)
`annualOptimizedConsumption`	number	Same as `optimizedEnergy` (for compatibility)
`annualBaselineConsumption`	number	Same as `baselineEnergy` (for compatibility)
`annualEnergyReduction`	number	Same as `energyReduction` (for compatibility)

Response Examples

Monthly Response Example

{
  "zipcode": "60601",
  "percentageSaved": 0.15,
  "dollarsSaved": 12.50,
  "optimizedCost": 70.83,
  "baselineCost": 83.33,
  "temperatureData": [72, 72.5, 73, 73.2, 73.5, 73.3, 73, 72.5, 72, 72, 72, 72, ...],
  "hvacConsumption": [0.5, 0.8, 1.2, 1.5, 1.8, 1.6, 1.3, 0.9, 0.6, 0.4, 0.3, 0.2, ...],
  "baselineTemperatureData": [72, 72, 72, 72, 72, 72, 72, 72, 72, 72, 72, 72, ...],
  "baselineHvacConsumption": [0.3, 0.5, 0.9, 1.2, 1.5, 1.4, 1.1, 0.7, 0.4, 0.3, 0.2, 0.2, ...],
  "length": 24,
  "setPointList": [73, 73, 73, 73, 73, 73, 73, 73, 73, 73, 73, 73, ...],
}

Annual Response Example

{
  "zipcode": "60601",
  "leapRevenue": undefined,
  "dollarsSaved": 450.25,
  "percentageSaved": 0.18,
  "optimizedCost": 2047.14,
  "baselineCost": 2497.39,
  "optimizedEnergy": 12500.5,
  "baselineEnergy": 15200.8,
  "energyReduction": 2700.3,
  "annualDollarsSaved": 450.25,
  "annualPercentageSaved": 0.18,
  "annualOptimizedCost": 2047.14,
  "annualBaselineCost": 2497.39,
  "annualOptimizedConsumption": 12500.5,
  "annualBaselineConsumption": 15200.8,
  "annualEnergyReduction": 2700.3,
  "latencySeconds": 15.32
}

Error Responses

400 Bad Request

Missing required home data

{
  "statusCode": 400,
  "message": "Home zipcode is required"
}

{
  "statusCode": 400,
  "message": "Home rate plan ID is required"
}

404 Not Found

Home not found

{
  "statusCode": 404,
  "message": "Home not found"
}

500 Internal Server Error

Optimization failed

{
  "statusCode": 500,
  "message": "Optimization failed"
}

{
  "statusCode": 500,
  "message": "Invalid response structure"
}

Notes

The home must have a zipcode and ratePlanId configured
If outdoorTemp is not provided, temperatures are fetched from a weather service
The start field accepts either a month index (1-12) or a specific start time
For annual calculations, results are normalized to a full year (365 days)

Enumerations

EstimateSavingsType

Value	Description
`"monthly"`	Calculate monthly savings with hourly data
`"annual"`	Calculate annual savings estimates

WsHvacMode

Value	Description
`"AUTO"`	Automatic mode (both heating and cooling)
`"COOL"`	Cooling only
`"HEAT"`	Heating only
`"OFF"`	HVAC system off

API Documentation

Endpoints

Hvac estimate savings

HVAC Estimate Savings API Documentation

Overview

Authentication

Path Parameters

Request Body

Base Fields

Monthly Type Specific Fields

Annual Type Specific Fields

Request Examples

Monthly Calculation Example

Annual Calculation Example

Response

Monthly Response

Annual Response

Response Examples

Monthly Response Example

Annual Response Example

Error Responses

400 Bad Request

404 Not Found

500 Internal Server Error

Notes

Enumerations

EstimateSavingsType

WsHvacMode

API Documentation

Endpoints

​HVAC Estimate Savings API Documentation

​Overview

​Authentication

​Path Parameters

​Request Body

​Base Fields

​Monthly Type Specific Fields

​Annual Type Specific Fields

​Request Examples

​Monthly Calculation Example

​Annual Calculation Example

​Response

​Monthly Response

​Annual Response

​Response Examples

​Monthly Response Example

​Annual Response Example

​Error Responses

​400 Bad Request

​404 Not Found

​500 Internal Server Error

​Notes

​Enumerations

​EstimateSavingsType

​WsHvacMode

HVAC Estimate Savings API Documentation

Overview

Authentication

Path Parameters

Request Body

Base Fields

Monthly Type Specific Fields

Annual Type Specific Fields

Request Examples

Monthly Calculation Example

Annual Calculation Example

Response

Monthly Response

Annual Response

Response Examples

Monthly Response Example

Annual Response Example

Error Responses

400 Bad Request

404 Not Found

500 Internal Server Error

Notes

Enumerations

EstimateSavingsType

WsHvacMode