Skip to main content
WattShift’s Estimate Savings endpoints enable you to calculate potential cost savings and optimization opportunities for HVAC systems and battery storage systems. These endpoints help you understand the financial impact of different optimization strategies before implementing them.

​
Overview

The Estimate Savings feature provides two main capabilities:
  1. HVAC Estimate Savings: Calculate potential savings from optimizing HVAC temperature setpoints and operation schedules
  2. Battery Estimate Savings: Calculate potential savings from battery storage optimization, including wholesale market participation
Both endpoints support detailed analysis with hourly data for monthly calculations or annualized estimates for long-term planning. In these guide examples, {homeId} is the home ID returned as id by onboarding. The API reference labels the same path parameter {id}.

​
HVAC Estimate Savings

The HVAC Estimate Savings endpoint helps you understand how optimizing your HVAC system’s temperature setpoints and operation can reduce energy costs.

​
Request Parameters

Required Fields:
  • type: Calculation type - "monthly" or "annual"
  • mode: HVAC mode - "AUTO", "COOL", "HEAT", or "OFF"
Optional Configuration:
  • targetTemp: Target temperature in Fahrenheit (default: 72)
  • targetCoolSetpoint: Cooling setpoint (default: targetTemp + 1)
  • targetHeatSetpoint: Heating setpoint (default: targetTemp - 1)
  • minTemp: Minimum allowed temperature (default: 70)
  • maxTemp: Maximum allowed temperature (default: 74)
  • heatTransferCoefficient: Heat transfer coefficient (default: 1)
  • irradianceCoefficient: Solar irradiance coefficient (default: 0.5)
  • coolingRate: Cooling rate multiplier (default: 1)
  • heatingRate: Heating rate multiplier (default: 1)
  • days: Number of days to simulate (default: 1)
Monthly Type:
  • start: Start time configuration - either {month: number} (1-12) or {startTime: Date}
Annual Type:
  • months: Array of month indices (1-12) to include. If null, all 12 months are included

​
Key Features

  • Monthly Analysis: Get detailed hourly data showing temperature profiles, energy consumption, and cost savings
  • Annual Estimates: Get annualized savings projections for long-term planning
  • Flexible Configuration: Customize target temperatures, setpoints, and HVAC modes
  • Weather Integration: Automatically fetch outdoor temperature data from weather service

​
Use Cases

  • Pre-Purchase Analysis: Estimate potential savings before installing a smart thermostat
  • Optimization Strategy: Compare different temperature setpoint strategies
  • Energy Efficiency Programs: Demonstrate potential savings to customers
  • Seasonal Planning: Analyze savings across different months of the year

​
API Endpoint

POST /v1/homes/{homeId}/hvac/estimate_savings
For detailed API documentation, see the HVAC Estimate Savings API Reference.

​
Quick Example

Calculate monthly savings with optimized temperature setpoints: 
{
  "type": "monthly",
  "targetTemp": 72,
  "targetCoolSetpoint": 73,
  "targetHeatSetpoint": 71,
  "minTemp": 70,
  "maxTemp": 74,
  "mode": "AUTO",
  "start": {
    "month": 7
  },
  "days": 1
}
Calculate annual savings across all months: 
{
  "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]
}
The response includes:
  • Percentage and dollar savings
  • Hourly temperature and consumption data (for monthly type)
  • Baseline vs. optimized comparisons
  • Energy consumption metrics (for annual type)

​
Battery Estimate Savings

The Battery Estimate Savings endpoint helps you calculate potential savings from battery storage systems through time-of-use rate arbitrage.

​
Request Parameters

Required Fields:
  • days: Number of days to simulate per month
  • maxCapacityKiloWattHours: Maximum battery capacity in kWh
  • chargingPowerKiloWatts: Maximum charging power in kW
  • dischargingPowerKiloWatts: Maximum discharging power in kW
  • chargingEfficiency: Charging efficiency (0-1), typical value: 0.95
  • dischargingEfficiency: Discharging efficiency (0-1), typical value: 0.95
  • currentSOC: Current state of charge (0-1), typical value: 0.5
  • minPreferredSOC: Minimum preferred state of charge (0-1)
  • maxPreferredSOC: Maximum preferred state of charge (0-1)
Optional Fields:
  • solarCapacity: Solar panel capacity in kW. Set to null if no solar
  • months: Array of month indices (1-12) to include. If null, all 12 months are included

​
Key Features

  • Standard Rate Optimization: Calculate savings from time-of-use rate arbitrage
  • Solar Integration: Include solar generation in calculations
  • Detailed Breakdowns: Get monthly and daily savings breakdowns
  • Carbon Impact: Calculate carbon emissions reductions

​
Use Cases

  • Battery ROI Analysis: Evaluate return on investment for battery storage systems
  • Solar + Battery Planning: Optimize solar and battery sizing together
  • Energy Arbitrage: Calculate savings from charging during low-rate periods and discharging during high-rate periods
  • Seasonal Analysis: Compare battery performance across different months

​
API Endpoint

POST /v1/homes/{homeId}/battery/estimate_savings
For detailed API documentation, see the Battery Estimate Savings API Reference.

​
Quick Example

Calculate annual savings with standard rate optimization: 
{
  "days": 1,
  "solarCapacity": 5.0,
  "maxCapacityKiloWattHours": 13.5,
  "chargingPowerKiloWatts": 5.0,
  "dischargingPowerKiloWatts": 5.0,
  "chargingEfficiency": 0.95,
  "dischargingEfficiency": 0.95,
  "currentSOC": 0.5,
  "minPreferredSOC": 0.2,
  "maxPreferredSOC": 0.9,
  "months": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12]
}
For a home without solar, set solarCapacity to null: 
{
  "days": 1,
  "solarCapacity": null,
  "maxCapacityKiloWattHours": 13.5,
  "chargingPowerKiloWatts": 5.0,
  "dischargingPowerKiloWatts": 5.0,
  "chargingEfficiency": 0.95,
  "dischargingEfficiency": 0.95,
  "currentSOC": 0.5,
  "minPreferredSOC": 0.2,
  "maxPreferredSOC": 0.9,
  "months": null
}
The response includes:
  • Annual savings and costs
  • Monthly and daily breakdowns with detailed statistics
  • Carbon emissions reductions
  • Optimized vs. baseline comparisons

​
Prerequisites

Before using the Estimate Savings endpoints, ensure onboarding is completed successfully. When a request asks for ratePlanId, use the selected ratePlans[].id from /v1/utility/get; ratePlans[].rateID is the semantic tariff reference.

​
Understanding the Results

​
HVAC Results

Monthly Response:
  • Percentage Saved: The percentage reduction in energy costs (0-1 scale)
  • Dollars Saved: Total dollar amount saved over the analysis period
  • Temperature Data: Hourly indoor temperatures showing optimization strategy
  • Consumption Data: Hourly energy consumption comparing baseline vs. optimized
  • Setpoint List: Array of setpoint temperatures for each hour
Annual Response:
  • Dollars Saved: Annual dollar amount saved
  • Percentage Saved: Annual percentage saved (0-1 scale)
  • Optimized Energy: Annual optimized energy consumption (kWh)
  • Baseline Energy: Annual baseline energy consumption (kWh)
  • Energy Reduction: Annual energy reduction (kWh)

​
Battery Results

  • Annual Savings: Total dollars saved and percentage saved
  • Carbon Impact: Carbon emissions saved (kg CO2) and reduction percentage
  • Monthly Breakdowns: Detailed monthly results with:
    • Monthly costs and savings
    • Daily breakdowns within each month
    • Statistics for dollars saved, percentage saved, and carbon impact
  • Optimized vs. Baseline: Compare optimized costs and consumption with baseline scenarios

​
Best Practices

  1. Start with Annual Estimates: Use annual calculations for high-level planning, then drill down with monthly analysis for specific periods
  2. Compare Scenarios: Run multiple calculations with different parameters to compare strategies:
    • Different temperature setpoints for HVAC
    • Different battery sizes or configurations
    • With and without solar generation
    • Different months or seasonal periods
  3. Month Indices: Note that month indices are 1-12 (January = 1, December = 12) for both HVAC and Battery endpoints
  4. Battery Specifications: For battery calculations, use accurate specifications matching your physical system:
    • Capacity (kWh)
    • Charging/discharging power (kW)
    • Efficiency ratings
    • State of charge preferences