Reference · for developers

REST API

Three endpoints cover the work: /economics turns kWh and cost into NPV and payback, /estimate runs the full pipeline from a roof, and /geocode turns an address into coordinates. Authenticate every call with the X-API-Key header. The examples use the demo key .

Not a developer? The drop-in widget needs no code, paste one snippet.

POST

/economics

Pass the annual generation and the system cost. Set country to use local tariffs, or pass import_price and export_price (per kWh) to set your own. Returns economics (currency, net_capex, annual_savings_year1, simple_payback_years, discounted_payback_years, npv, irr, lifetime_savings) plus co2_saved_year1_kg and lifetime_generation_kwh.

curl -X POST https://solarapi-api.157.90.161.30.sslip.io/economics \
  -H "X-API-Key: " \
  -H "Content-Type: application/json" \
  -d '{
    "annual_generation_kwh": 4200,
    "system_cost": 6500,
    "country": "GB"
  }'

const res = await fetch("https://solarapi-api.157.90.161.30.sslip.io/economics", {
  method: "POST",
  headers: {
    "X-API-Key": "",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    annual_generation_kwh: 4200,
    system_cost: 6500,
    country: "GB",
  }),
})
if (!res.ok) throw new Error(`Economics failed: ${res.status}`)
const { economics } = await res.json()
console.log(`Payback ${economics.simple_payback_years} yr · NPV ${economics.npv} ${economics.currency}`)

import requests

res = requests.post(
    "https://solarapi-api.157.90.161.30.sslip.io/economics",
    headers={"X-API-Key": ""},
    json={
        "annual_generation_kwh": 4200,
        "system_cost": 6500,
        "country": "GB",
    },
)
res.raise_for_status()
econ = res.json()["economics"]
print(f"Payback: {econ['simple_payback_years']} years")
print(f"NPV: {econ['npv']} {econ['currency']}")

import type { EconomicsRequest, EconomicsResponse } from "@solar-api/types"

const body: EconomicsRequest = {
  annual_generation_kwh: 4200,
  system_cost: 6500,
  country: "GB",
}
const res = await fetch("https://solarapi-api.157.90.161.30.sslip.io/economics", {
  method: "POST",
  headers: { "X-API-Key": "", "Content-Type": "application/json" },
  body: JSON.stringify(body),
})
if (!res.ok) throw new Error(`Economics failed: ${res.status}`)
const { economics }: EconomicsResponse = await res.json()
console.log(`Payback ${economics.simple_payback_years} yr · NPV ${economics.npv}`)

Response · 200 OK

application/json

{
  "economics": {
    "currency": "GBP",
    "net_capex": 6500,
    "annual_savings_year1": 712,
    "simple_payback_years": 9.1,
    "discounted_payback_years": 11.4,
    "npv": 4880,
    "irr": 0.097,
    "lifetime_savings": 19240,
    "price_source": "country_default"
  },
  "co2_saved_year1_kg": 525,
  "lifetime_generation_kwh": 99120,
  "attribution": "Estimates by solar-api.dev"
}

POST

/estimate

Give a roof and the endpoint sizes a system, models the yield, and runs the economics. Locate it with lat/lon, or omit them and pass a country to estimate from that country's centroid (a request with neither is rejected). Size it with one of kwp, panel_count, or usable_roof_m2. Set country, tilt, azimuth, and battery. Choose the engine: fast for screening or precise for a closer model. Returns system, yield (annual_kwh, monthly_kwh), economics, and co2.

curl -X POST https://solarapi-api.157.90.161.30.sslip.io/estimate \
  -H "X-API-Key: " \
  -H "Content-Type: application/json" \
  -d '{
    "lat": 51.5,
    "lon": -0.12,
    "kwp": 4,
    "country": "GB",
    "tilt": 35,
    "azimuth": 180,
    "battery": false,
    "engine": "fast"
  }'

const res = await fetch("https://solarapi-api.157.90.161.30.sslip.io/estimate", {
  method: "POST",
  headers: {
    "X-API-Key": "",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    lat: 51.5,
    lon: -0.12,
    kwp: 4,
    country: "GB",
    tilt: 35,
    azimuth: 180,
    battery: false,
    engine: "fast",
  }),
})
if (!res.ok) throw new Error(`Estimate failed: ${res.status}`)
const data = await res.json()
console.log(`Annual yield: ${data.yield.annual_kwh} kWh`)
console.log(`Payback: ${data.economics.simple_payback_years} years`)

import requests

res = requests.post(
    "https://solarapi-api.157.90.161.30.sslip.io/estimate",
    headers={"X-API-Key": ""},
    json={
        "lat": 51.5,
        "lon": -0.12,
        "kwp": 4,
        "country": "GB",
        "tilt": 35,
        "azimuth": 180,
        "battery": False,
        "engine": "fast",
    },
)
res.raise_for_status()
data = res.json()
print(f"Annual yield: {data['yield']['annual_kwh']} kWh")
print(f"Payback: {data['economics']['simple_payback_years']} years")

import type { EstimateRequest, EstimateResponse } from "@solar-api/types"

const body: EstimateRequest = {
  lat: 51.5, lon: -0.12, kwp: 4, country: "GB",
  tilt: 35, azimuth: 180, battery: false, engine: "fast",
}
const res = await fetch("https://solarapi-api.157.90.161.30.sslip.io/estimate", {
  method: "POST",
  headers: { "X-API-Key": "", "Content-Type": "application/json" },
  body: JSON.stringify(body),
})
if (!res.ok) throw new Error(`Estimate failed: ${res.status}`)
const data: EstimateResponse = await res.json()
console.log(`${data.yield.annual_kwh} kWh/yr · NPV ${data.economics.npv} ${data.economics.currency}`)

Response · 200 OK

application/json

{
  "system": { "kwp": 4, "panel_count": 10, "tilt": 35, "azimuth": 180 },
  "yield": {
    "annual_kwh": 3960,
    "monthly_kwh": [120, 180, 320, 430, 510, 540, 560, 500, 380, 250, 140, 100],
    "specific_yield": 990,
    "estimate_method": "pvgis"
  },
  "economics": {
    "currency": "GBP",
    "annual_savings_year1": 712,
    "simple_payback_years": 9.1,
    "npv": 4880,
    "irr": 0.097
  },
  "co2_saved_year1_kg": 495,
  "attribution": "Estimates by solar-api.dev"
}

GET

/geocode

Turn an address into coordinates before you call /estimate. Pass q for the query and an optional country to bias the results.

curl "https://solarapi-api.157.90.161.30.sslip.io/geocode?q=10+Downing+Street&country=GB" \
  -H "X-API-Key: "

const params = new URLSearchParams({ q: "10 Downing Street", country: "GB" })
const res = await fetch(`https://solarapi-api.157.90.161.30.sslip.io/geocode?${params}`, {
  headers: { "X-API-Key": "" },
})
if (!res.ok) throw new Error(`Geocode failed: ${res.status}`)
const { results } = await res.json()
const [top] = results
console.log(`${top.label}: ${top.lat}, ${top.lon}`)

import requests

res = requests.get(
    "https://solarapi-api.157.90.161.30.sslip.io/geocode",
    headers={"X-API-Key": ""},
    params={"q": "10 Downing Street", "country": "GB"},
)
res.raise_for_status()
top = res.json()["results"][0]
print(f"{top['label']}: {top['lat']}, {top['lon']}")

const params = new URLSearchParams({ q: "10 Downing Street", country: "GB" })
const res = await fetch(`https://solarapi-api.157.90.161.30.sslip.io/geocode?${params}`, {
  headers: { "X-API-Key": "" },
})
if (!res.ok) throw new Error(`Geocode failed: ${res.status}`)
const { results }: { results: { label: string; lat: number; lon: number }[] } = await res.json()
const [top] = results
console.log(`${top.label}: ${top.lat}, ${top.lon}`)

Auth

Send your key in the X-API-Key header on every request. Magic-link sessions and key rotation live in Authentication.