Solar yield and simulation API

Two free JSON APIs for installer tools, AI agents and anyone who compares roofs and batteries.

  • PV yield API (/api/v1/pv-yield): annual and monthly solar yield in kWh per kWp for any point in Sweden, any tilt and azimuth, the local optimum, and a tilt × azimuth matrix. Answers in milliseconds.
  • Simulation API (/api/v1/simulation): one year, hour by hour, of a house's energy flows and electricity bill, with and without a battery. Compare battery sizes and strategies in one call.

The third API, the PDF generation API, is for partners with a key only.

Quick start

Base URL: https://numsolar.com. Every answer is JSON (UTF-8). No key and no sign-up are needed:

curl
curl 'https://numsolar.com/api/v1/pv-yield?lat=59.33&lng=18.07&tilt=35&azimuth=180&kwp=9.24'
JavaScript (browser or Node 18+)
const url = new URL("https://numsolar.com/api/v1/pv-yield");
url.search = new URLSearchParams({lat: 59.33, lng: 18.07, tilt: 35, azimuth: 180, kwp: 9.24}).toString();
const res = await fetch(url);
if (!res.ok) throw new Error((await res.json()).error.message);
const data = await res.json();
console.log(data.annual_kwh, "kWh a year");

Machine-readable description of both APIs: /api/v1/simulation/openapi.json (OpenAPI 3.1; the same document is at /api/v1/pv-yield/openapi.json).

API keys

No key is needed. An API key gives higher limits: ask contact@numsolar.com. Send it in the x-api-key header on every call:

curl
curl -H 'x-api-key: YOUR_KEY' 'https://numsolar.com/api/v1/pv-yield/matrix?lat=59.33&lng=18.07'

A wrong key gets 401 invalid_api_key: it does not fall back to the free limits. Keep the key on your server; do not put it in browser code.

Limits

The limits count per client IP address without a key, and per key with one. The count restarts at the start of each clock minute (:00), so two minutes can meet at a boundary.

RouteWithout a keyWith a key
GET /api/v1/pv-yield + POST /batch (together) 60 a minute 600 a minute
GET /api/v1/pv-yield/matrix 10 a minute 60 a minute
POST /api/v1/simulation + /battery-strategies: requests 10 a minute 100 a minute
The same: cells 50 a minute 500 a minute
/meta, openapi.json not limited not limited
  • A batch counts as its number of items (at most 50).
  • A simulation is 1 cell. A battery-strategies call is sizes × strategies cells (at most 25). Cells count only when the simulation runs: a refused, invalid or busy call costs no cells, but it counts as a request.
  • Over a limit: 429 rate_limited with Retry-After (the seconds until the next clock minute).
  • Failed calls count too: after 10 failed calls in a minute from one IP (a wrong key, a body that is not valid JSON or larger than 2 MB), every call of that IP gets 429 rate_limited with Retry-After until the minute ends.
  • Answers of the limited routes carry X-RateLimit-Limit and X-RateLimit-Remaining; the simulation routes also carry X-RateLimit-Cells-Limit and X-RateLimit-Cells-Remaining. A 400, 413 or 401 answer has no such headers.

Errors

Every error of /api/v1 has the same shape. field is there only when one field is wrong:

422 Unprocessable Entity
{
  "error": {
    "code": "invalid_parameter",
    "field": "lat",
    "message": "lat is required: a number of degrees between -90 and 90"
  }
}

The codes of each API: PV yield, simulation. A path or a method that does not exist gets 404.

Caching and CORS

  • PV yield answers do not change for a dataset version. They have Cache-Control: public, max-age=86400 and an ETag; send If-None-Match to get a 304.
  • CORS is open on /api/v1 (Access-Control-Allow-Origin: *, preflight included): call the free APIs from a browser.

Data and licence

The PV yield numbers contain PVGIS data (European Commission, Joint Research Centre), CC BY 4.0. Every PV yield answer has an attribution line: keep it when you show the numbers.

Changelog

  • 2026-11-05, Security limits: Ten failed calls a minute (a wrong key, a body that is not valid JSON or too large) from one IP give 429 for that IP until the minute ends. PDF generation API: input files only from public https links (port 443, at most 3 redirects, 100 MB); results always go to a new folder pdf-generation-api/<id>/.
  • 2026-11-05, Docs refresh: New reference: one page per API, the PDF generation API documented, examples taken from real answers, the error lists complete (busy, invalid_json, body_too_large), Retry-After for each 503. No change to the API itself.
  • 2026-10-09, Simulation API v1: POST /api/v1/simulation and /api/v1/simulation/battery-strategies: the four battery strategies and electricity-provider battery programs.
  • 2026-10-07, PV yield dataset se-2026.10: The first PV yield dataset: PVGIS 5.3, 1 306 cells over the Sweden bounding box 55.0–69.5 N, 10.5–24.5 E, Hay–Davies sky.