Skip to main content

​
Battery Estimate Savings API Documentation

​
Overview

This endpoint calculates estimated annual savings for battery storage systems. It supports both standard rate plan optimization and wholesale market participation (LEAP programs in CAISO or NYISO).

​
Authentication

Requires API Key authentication via ApiKeyGuard.

​
Path Parameters

ParameterTypeRequiredDescription
idstringYesHome ID (UUID)

​
Request Body

FieldTypeRequiredDescription
daysnumberYesNumber of days to simulate per month
solarCapacitynumber | nullNoSolar panel capacity in kW. Set to null if no solar
maxCapacityKiloWattHoursnumberYesMaximum battery capacity in kWh
chargingPowerKiloWattsnumberYesMaximum charging power in kW
dischargingPowerKiloWattsnumberYesMaximum discharging power in kW
chargingEfficiencynumberYesCharging efficiency (0-1). Typical value: 0.95
dischargingEfficiencynumberYesDischarging efficiency (0-1). Typical value: 0.95
currentSOCnumberYesCurrent state of charge (0-1). Typical value: 0.5
minPreferredSOCnumberYesMinimum preferred state of charge (0-1)
maxPreferredSOCnumberYesMaximum preferred state of charge (0-1)
monthsnumber[] | nullNoArray of month indices (0-11) to include. If null, all 12 months are included

​
Request Examples

​
Standard Rate Plan Example

{
  "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]
}

​
Response

The response structure depends on whether leap is set:

​
Standard Rate Plan Response (leap = null)

FieldTypeDescription
optimizedCostnumberAnnual optimized cost ($)
baselineCostnumberAnnual baseline cost ($)
dollarsSavednumberAnnual dollars saved ($)
percentageSavednumberPercentage saved (0-1)
carbonSavednumberCarbon emissions saved (kg CO2)
carbonReductionnumberCarbon reduction percentage (0-1)
capacityRevenueundefinedAlways undefined for standard rate plans
lmpRevenueundefinedAlways undefined for standard rate plans
totalRevenueundefinedAlways undefined for standard rate plans
monthsarrayArray of monthly results. Each month contains:
months[].monthnumberMonth index (0-11)
months[].monthStrstringMonth name (e.g., “January”)
months[].totalCostnumberMonthly optimized cost
months[].baselineCostnumberMonthly baseline cost
months[].savingsnumberMonthly savings
months[].stats.dollarsSavednumberMonthly dollars saved
months[].stats.percentageSavednumberMonthly percentage saved
months[].stats.carbonSavednumberMonthly carbon saved
months[].stats.carbonReductionnumberMonthly carbon reduction
months[].daysarrayArray of daily results within the month
months[].days[].time.monthnumberMonth index
months[].days[].time.monthStrstringMonth name
months[].days[].time.daynumberDay of month
months[].days[].time.dayOfWeekStrstringDay of week name
months[].days[].totalCostnumberDaily optimized cost
months[].days[].baselineCostnumberDaily baseline cost
months[].days[].optimizedCarbonnumberDaily optimized carbon emissions
months[].days[].baselineCarbonnumberDaily baseline carbon emissions
months[].days[].stats.dollarsSavednumberDaily dollars saved
months[].days[].stats.percentageSavednumberDaily percentage saved

​
Response Examples

​
Standard Rate Plan Response Example

{
  "optimizedCost": 1200.50,
  "baselineCost": 1800.75,
  "dollarsSaved": 600.25,
  "percentageSaved": 0.333,
  "carbonSaved": 450.5,
  "carbonReduction": 0.15,
  "capacityRevenue": undefined,
  "lmpRevenue": undefined,
  "totalRevenue": undefined,
  "months": [
    {
      "month": 0,
      "monthStr": "January",
      "totalCost": 95.50,
      "optimizedCost": 95.50,
      "baselineCost": 145.25,
      "savings": 49.75,
      "stats": {
        "dollarsSaved": 49.75,
        "percentageSaved": 0.342,
        "carbonSaved": 35.2,
        "carbonReduction": 0.12
      },
      "days": [
        {
          "time": {
            "month": 0,
            "monthStr": "January",
            "day": 1,
            "dayOfWeekStr": "Monday"
          },
          "totalCost": 3.15,
          "baselineCost": 4.75,
          "optimizedCarbon": 2.1,
          "baselineCarbon": 2.5,
          "stats": {
            "dollarsSaved": 1.60,
            "percentageSaved": 0.337
          }
        }
      ],
      "input": { ... }
    }
  ]
}

​
Error Responses

​
400 Bad Request

Missing required home data 
{
  "statusCode": 400,
  "message": "Home rate plan ID is required"
}
or 
{
  "statusCode": 400,
  "message": "Home zipcode is required"
}

​
404 Not Found

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

​
Notes

  • The home must have a zipcode and ratePlanId configured
  • Battery capacity and power ratings should match the physical system specifications
  • Efficiency values typically range from 0.90 to 0.98 for modern lithium-ion batteries
  • State of charge values are normalized (0 = empty, 1 = full)
  • Results are annualized based on the number of days simulated per month