API Reference

Base URL: https://elovane-api.smarttechinvest.com

Authentication

Pass your API key via the X-API-Key header on every request (except /v1/signup and /v1/login).

POST/v1/calculate

Run the full solar ROI analysis pipeline: sizing, credits, NPV, LCOE, payback, TOU arbitrage, sequencing, and Monte Carlo.

Parameters

Name	Type	Required	Description
annualProductionPerKW	body	required	kWh produced per kW of solar capacity per year (location-dependent)
annualConsumptionKWh	body	required	Total annual household electricity consumption in kWh
utilityRate	body	required	Current utility rate in $/kWh (e.g. 0.15)
state	body	optional	Two-letter state code for incentive lookup
roofAreaSqFt	body	optional	Available roof area in square feet
systemCostPerWatt	body	optional	$/watt installed cost (default: 2.77)
analysisYears	body	optional	Analysis period in years (default: 25)
discountRate	body	optional	Discount rate for NPV (default: 0.04)
enableMonteCarlo	body	optional	Run Monte Carlo simulation on utility rates (default: false)
monteCarloIterations	body	optional	Number of Monte Carlo iterations (default: 1000)
systems	body	optional	Systems to evaluate: solar, battery, heat_pump, water_heater

Response

{
  "data": {
    "sizing": { "optimalSizeKW": 7.14, "annualProductionKWh": 10000 },
    "credits": {
      "federalITC": 6426, "stateCredits": 1000,
      "utilityRebates": 0, "totalCredits": 7426
    },
    "npv": { "npv25Year": 18420, "irr": 0.124 },
    "lcoe": { "solarLCOE": 0.062, "utilityLCOE": 0.15 },
    "payback": { "simplePaybackYears": 8.2, "discountedPaybackYears": 9.4 },
    "sequencing": {
      "optimalOrder": ["solar", "battery", "heat_pump"],
      "reasoning": "Solar first maximizes ITC credit base..."
    }
  },
  "meta": { "timestamp": "...", "source": "elovane-api", "version": "0.1.0" }
}

Error Codes

400 Missing required fields
400 Invalid input values
429 Rate limit exceeded

POST/v1/sensitivity

Run sensitivity analysis on key assumptions (discount rate, utility escalation, system cost).

Parameters

Name	Type	Required	Description
annualProductionPerKW	body	required	kWh produced per kW of solar capacity per year
annualConsumptionKWh	body	required	Total annual electricity consumption in kWh
utilityRate	body	required	Current utility rate in $/kWh

Response

{
  "data": {
    "baseCase": { "npv": 18420, "paybackYears": 8.2 },
    "discountRate": [
      { "value": 0.02, "npv": 24100 },
      { "value": 0.06, "npv": 13800 }
    ],
    "utilityEscalation": [
      { "value": 0.03, "npv": 14200 },
      { "value": 0.08, "npv": 28600 }
    ]
  },
  "meta": { "timestamp": "...", "source": "elovane-api" }
}

Error Codes

400 Missing required fields
429 Rate limit exceeded

POST/v1/compare

Compare electrification options across different configurations.

Parameters

Name	Type	Required	Description
scenarios	body	required	Array of calculation inputs to compare (2-5 scenarios)

Response

{
  "data": {
    "scenarios": [
      { "label": "Solar only", "npv": 18420, "paybackYears": 8.2 },
      { "label": "Solar + Battery", "npv": 22100, "paybackYears": 9.8 }
    ],
    "recommendation": "Solar + Battery provides the highest 25-year NPV..."
  },
  "meta": { "timestamp": "...", "source": "elovane-api" }
}

Error Codes

400 Invalid scenarios
429 Rate limit exceeded

GET/v1/solar/:state

Get solar production estimates and irradiance data for a state.

Parameters

Name	Type	Required	Description
state	path	required	Two-letter state code (e.g., CA, TX, NY)

Response

{
  "data": {
    "state": "CA",
    "avgIrradiance": 5.82,
    "avgProductionPerKW": 1580,
    "topCounties": [
      { "county": "Imperial", "irradiance": 6.41 },
      { "county": "Riverside", "irradiance": 6.12 }
    ]
  },
  "meta": { "timestamp": "...", "source": "nrel-pvwatts" }
}

Error Codes

400 Invalid state code
404 State not found

GET/v1/incentives/:state

Get federal and state-level solar incentives and rebates.

Parameters

Name	Type	Required	Description
state	path	required	Two-letter state code

Response

{
  "data": {
    "federal": { "itcRate": 0.30, "description": "Federal Investment Tax Credit (IRS Section 25D)" },
    "state": [
      { "name": "CA Solar Initiative", "type": "rebate", "amount": 1000, "unit": "flat" }
    ],
    "utility": []
  },
  "meta": { "timestamp": "...", "source": "dsire" }
}

Error Codes

400 Invalid state code
404 No incentive data

GET/v1/costs

Get current system cost estimates (solar, battery, heat pump).

Parameters

Name	Type	Required	Description
system	query	optional	Filter by system type: solar, battery, heat_pump

Response

{
  "data": {
    "solar": { "costPerWatt": 2.77, "source": "NREL ATB 2025" },
    "battery": { "costPerKWh": 350, "source": "NREL ATB 2025" },
    "heatPump": { "costPerUnit": 4500, "source": "EnergyStar" }
  },
  "meta": { "timestamp": "...", "source": "nrel-atb" }
}

GET/v1/states

List all available states with solar data coverage.

Response

{
  "data": [
    { "code": "AL", "name": "Alabama", "slug": "alabama" },
    { "code": "AK", "name": "Alaska", "slug": "alaska" },
    ...
  ],
  "meta": { "timestamp": "..." }
}

GET/v1/zip/:zip

Look up location data for a U.S. ZIP code.

Parameters

Name	Type	Required	Description
zip	path	required	5-digit U.S. ZIP code

Response

{
  "data": {
    "zip": "90210",
    "city": "Beverly Hills",
    "state": "CA",
    "county": "Los Angeles",
    "latitude": 34.09,
    "longitude": -118.41
  },
  "meta": { "timestamp": "..." }
}

Error Codes

400 Invalid ZIP code
404 ZIP not found

GET/v1/rates

Get current financing and inflation rates.

Response

{
  "data": {
    "solarLoanRate": 0.059,
    "inflationRate": 0.031,
    "source": "FRED / BLS CPI"
  },
  "meta": { "timestamp": "..." }
}

GET/v1/freshness

Check data freshness across all pipeline sources.

Response

{
  "data": {
    "sources": [
      { "name": "nrel-pvwatts", "lastSync": "2026-03-01", "status": "fresh" },
      { "name": "dsire", "lastSync": "2026-02-15", "status": "fresh" },
      { "name": "eia", "lastSync": "2026-01-20", "status": "stale" }
    ]
  },
  "meta": { "timestamp": "..." }
}

POST/v1/signup

Create an account and receive an API key.

Parameters

Name	Type	Required	Description
name	body	required	User display name
email	body	required	Email address
password	body	required	Password (min 8 characters)

Response

{
  "data": {
    "message": "Account created",
    "apiKeyPrefix": "elv_live...",
    "apiKey": "elv_live_a1b2c3d4..."
  },
  "meta": { "timestamp": "..." }
}

Error Codes

400 Invalid input
409 Email already registered

POST/v1/login

Authenticate with email and password.

Parameters

Name	Type	Required	Description
email	body	required	Email address
password	body	required	Password

Response

{
  "data": {
    "token": "eyJ...",
    "user": { "name": "Jane", "email": "jane@example.com", "tier": "free" }
  },
  "meta": { "timestamp": "..." }
}

Error Codes

401 Invalid credentials

Rate Limiting

Requests that exceed your plan limit return 429 Too Many Requests with a Retry-After header indicating seconds until the limit resets.

Plan	Requests/Day	Monte Carlo
Free	50	No
Pro ($19/mo)	500	Yes
Developer ($39/mo)	1,000	Yes
API Business ($99/mo)	10,000	Yes