{ "openapi": "3.0.3", "info": { "title": "SolarPulse", "version": "1.0", "description": "Rooftop solar production estimate, utility electricity rates and 25-year financial analysis for any US address, from NASA POWER climatology (2001-2020), EIA Form 861 2024 via PUDL, LBNL Tracking the Sun 2024 via OEDI, and HIFLD retail service territories. All three routes accept query parameters and return structured JSON. Billed at $0.10 per successful call; errors (400, 401, 404, 503) are never billed.\n" }, "servers": [ { "url": "https://solarpulse.waltsoft.net/v1", "description": "SolarPulse production API" } ], "security": [ { "ApiKeyAuth": [] } ], "paths": { "/estimate": { "get": { "operationId": "getSolarEstimate", "summary": "Rooftop solar estimate \u2014 system size, production, utility rate, cost and payback", "description": "Returns system size (DC kW, panels), monthly and annual production from NASA POWER climatology, the serving utility's EIA-861 2024 residential rate, installed cost from LBNL Tracking the Sun 2024, simple payback, 25-year savings and the 2026 federal credit status. Billed at $0.10.\n", "parameters": [ { "name": "address", "in": "query", "description": "US street address, e.g. \"200 W Washington St, Phoenix AZ 85003\"", "schema": { "type": "string", "example": "200 W Washington St, Phoenix AZ 85003" } }, { "name": "lat", "in": "query", "description": "Latitude (decimal degrees). Requires lon. Must be US location (17\u201372).", "schema": { "type": "number", "example": 33.4483 } }, { "name": "lon", "in": "query", "description": "Longitude (decimal degrees). Requires lat.", "schema": { "type": "number", "example": -112.0764 } }, { "name": "monthly_kwh", "in": "query", "description": "Monthly household electricity usage in kWh (50\u201310000). Alternative to monthly_bill.", "schema": { "type": "number", "example": 1100 } }, { "name": "monthly_bill", "in": "query", "description": "Monthly electricity bill in USD (10\u20133000). Alternative to monthly_kwh.", "schema": { "type": "number", "example": 150 } }, { "name": "system_kw", "in": "query", "description": "Specific system size to model in kW DC (1\u201325). Omit to let the API size it.", "schema": { "type": "number", "example": 8.0 } }, { "name": "tilt", "in": "query", "description": "Roof tilt in degrees from horizontal (0\u201360). Default 20.", "schema": { "type": "number", "example": 20 } } ], "responses": { "200": { "description": "Solar estimate", "content": { "application/json": { "schema": { "type": "object", "required": [ "location", "system", "usage", "production", "electricity", "cost", "financials", "data_sources", "generated_at" ], "properties": { "location": { "type": "object", "properties": { "input": { "type": "string" }, "matched_address": { "type": "string" }, "lat": { "type": "number", "example": 33.44983 }, "lon": { "type": "number", "example": -112.07676 }, "county": { "type": "string" }, "county_fips": { "type": "string" }, "state": { "type": "string" } } }, "system": { "type": "object", "properties": { "size_kw_dc": { "type": "number", "example": 8.5 }, "panels_approx": { "type": "integer" }, "panel_watts": { "type": "integer" }, "tilt_deg": { "type": "integer" }, "orientation": { "type": "string" }, "sized_to": { "type": "string" }, "usage_offset_pct": { "type": "integer" } } }, "usage": { "type": "object", "properties": { "monthly_kwh": { "type": "integer" }, "basis": { "type": "string" } } }, "production": { "type": "object", "properties": { "annual_kwh": { "type": "integer", "example": 15215 }, "specific_yield_kwh_per_kw": { "type": "integer" }, "peak_sun_hours": { "type": "number" }, "monthly_kwh": { "type": "array", "items": { "type": "integer" } }, "uncertainty": { "type": "string" } } }, "electricity": { "type": "object", "properties": { "utility": { "type": "string" }, "eia_id": { "type": "integer" }, "rate_cents_per_kwh": { "type": "number", "example": 14.2 }, "rate_basis": { "type": "string" }, "state_average_cents_per_kwh": { "type": "number" }, "state_trend_pct_per_year": { "type": "number" }, "state_trend_period": { "type": "string" }, "utility_lookup": { "type": "string" } } }, "cost": { "type": "object", "properties": { "installed_price_usd_per_watt": { "type": "number", "example": 2.95 }, "price_range_usd_per_watt": { "type": "array", "items": { "type": "number" } }, "price_basis": { "type": "string" }, "gross_cost_usd": { "type": "integer", "example": 25075 }, "federal_tax_credit_usd": { "type": "integer", "example": 0 }, "federal_tax_credit_note": { "type": "string" }, "state_and_utility_incentives": { "type": "string" }, "net_cost_usd": { "type": "integer" } } }, "financials": { "type": "object", "properties": { "first_year_savings_usd": { "type": "integer" }, "simple_payback_years": { "type": "number", "example": 11.8 }, "savings_25yr_usd": { "type": "integer" }, "net_benefit_25yr_usd": { "type": "integer" }, "trend_scenario": { "type": "object" }, "lifetime_cost_per_kwh_usd": { "type": "number" }, "production_25yr_kwh": { "type": "integer" }, "assumptions": { "type": "array", "items": { "type": "string" } } } }, "data_sources": { "type": "array", "items": { "type": "string" } }, "generated_at": { "type": "string", "format": "date-time" } } } } } }, "400": { "description": "Invalid or missing parameter. Not billed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401" } } } }, "402": { "description": "No API key sent (x402 pay-per-call challenge)." }, "404": { "description": "Location not found, or no EIA rate data for this state. Not billed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Public data source temporarily unavailable. Not billed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/irradiance": { "get": { "operationId": "getSolarIrradiance", "summary": "Solar irradiance and PV yield from NASA POWER climatology", "description": "Returns monthly and annual GHI, plane-of-array irradiance, optimal tilt, air temperature and PV yield per installed kW from NASA POWER 2001-2020 climatology. Billed at $0.10.\n", "parameters": [ { "name": "lat", "in": "query", "description": "Latitude (decimal degrees). Must be a US location (17\u201372). Requires lon.", "schema": { "type": "number", "example": 33.4483 } }, { "name": "lon", "in": "query", "description": "Longitude (decimal degrees). Must be a US location (-180 to -64). Requires lat.", "schema": { "type": "number", "example": -112.0764 } }, { "name": "address", "in": "query", "description": "US street address (alternative to lat/lon).", "schema": { "type": "string", "example": "200 W Washington St, Phoenix AZ 85003" } }, { "name": "tilt", "in": "query", "description": "Panel tilt in degrees (0\u201360). Default 20.", "schema": { "type": "number", "example": 20 } } ], "responses": { "200": { "description": "Solar irradiance data", "content": { "application/json": { "schema": { "type": "object", "required": [ "location", "array", "annual", "monthly", "climatology", "data_sources", "generated_at" ], "properties": { "location": { "type": "object", "properties": { "input": { "type": "string" }, "matched_address": { "type": "string" }, "lat": { "type": "number" }, "lon": { "type": "number" }, "county": { "type": "string" }, "county_fips": { "type": "string" }, "state": { "type": "string" } } }, "array": { "type": "object", "properties": { "tilt_deg": { "type": "integer" }, "orientation": { "type": "string" } } }, "annual": { "type": "object", "properties": { "ghi_kwh_m2_day": { "type": "number", "example": 5.52 }, "plane_of_array_kwh_m2_day": { "type": "number" }, "peak_sun_hours": { "type": "number" }, "optimal_tilt_deg": { "type": "integer" }, "plane_of_array_at_optimal_tilt_kwh_m2_day": { "type": "number" }, "mean_air_temp_c": { "type": "number" }, "pv_yield_kwh_per_kw_year": { "type": "integer", "example": 1790 } } }, "monthly": { "type": "array", "items": { "type": "object", "properties": { "month": { "type": "string" }, "ghi_kwh_m2_day": { "type": "number" }, "plane_of_array_kwh_m2_day": { "type": "number" }, "mean_air_temp_c": { "type": "number" }, "mean_daily_max_c": { "type": "number" }, "pv_kwh_per_kw": { "type": "integer" } } } }, "climatology": { "type": "string" }, "resolution_note": { "type": "string" }, "pv_model": { "type": "string" }, "data_sources": { "type": "array", "items": { "type": "string" } }, "generated_at": { "type": "string", "format": "date-time" } } } } } }, "400": { "description": "Invalid or missing parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401" } } } }, "402": { "description": "No API key sent (x402 pay-per-call challenge)." }, "404": { "description": "Location not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "NASA POWER unavailable. Not billed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/rates": { "get": { "operationId": "getElectricityRates", "summary": "Residential electricity rates and utility data for a US ZIP, address or point", "description": "Returns the utilities serving a US location (from HIFLD retail service territories), each utility's EIA-861 2024 average residential rate and typical monthly usage, plus the state average and 10-year rate trend. Accepts ZIP code, street address, or lat/lon. Billed at $0.10.\n", "parameters": [ { "name": "zip", "in": "query", "description": "5-digit US ZIP code, e.g. 85003.", "schema": { "type": "string", "example": "85003" } }, { "name": "address", "in": "query", "description": "US street address (alternative to zip).", "schema": { "type": "string", "example": "200 W Washington St, Phoenix AZ 85003" } }, { "name": "lat", "in": "query", "description": "Latitude. Requires lon.", "schema": { "type": "number", "example": 33.4483 } }, { "name": "lon", "in": "query", "description": "Longitude. Requires lat.", "schema": { "type": "number", "example": -112.0764 } } ], "responses": { "200": { "description": "Electricity rate data", "content": { "application/json": { "schema": { "type": "object", "required": [ "location", "residential_rate_cents_per_kwh", "typical_monthly_bill_usd", "utilities_in_area", "data_sources", "generated_at" ], "properties": { "location": { "type": "object", "properties": { "input": { "type": "string" }, "matched_address": { "type": "string" }, "lat": { "type": "number" }, "lon": { "type": "number" }, "county": { "type": "string" }, "county_fips": { "type": "string" }, "state": { "type": "string" } } }, "likely_utility": { "type": "object", "nullable": true, "properties": { "name": { "type": "string" }, "eia_id": { "type": "integer" }, "ownership": { "type": "string" }, "role": { "type": "string" }, "residential_cents_per_kwh": { "type": "number" }, "avg_monthly_kwh": { "type": "integer" }, "residential_customers": { "type": "integer" } } }, "residential_rate_cents_per_kwh": { "type": "number", "example": 14.2 }, "rate_basis": { "type": "string" }, "typical_monthly_usage_kwh": { "type": "integer" }, "usage_basis": { "type": "string" }, "typical_monthly_bill_usd": { "type": "integer" }, "utilities_in_area": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "eia_id": { "type": "integer" }, "ownership": { "type": "string" }, "residential_cents_per_kwh": { "type": "number" }, "avg_monthly_kwh": { "type": "integer" } } } }, "utility_lookup": { "type": "string" }, "state": { "type": "object", "properties": { "average_cents_per_kwh": { "type": "number" }, "trend_pct_per_year": { "type": "number" }, "trend_period": { "type": "string" } } }, "data_year": { "type": "integer" }, "notes": { "type": "array", "items": { "type": "string" } }, "data_sources": { "type": "array", "items": { "type": "string" } }, "generated_at": { "type": "string", "format": "date-time" } } } } } }, "400": { "description": "Invalid or missing parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or inactive API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401" } } } }, "402": { "description": "No API key sent (x402 pay-per-call challenge)." }, "404": { "description": "Location not found, or no EIA rate data for this state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Public data source temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key" } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "string" } } }, "Error401": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer", "example": 401 }, "message": { "type": "string", "example": "Invalid or inactive API key" } } } } } } } }