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 'https://numsolar.com/api/v1/pv-yield?lat=59.33&lng=18.07&tilt=35&azimuth=180&kwp=9.24'
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 -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.
| Route | Without a key | With 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_limitedwithRetry-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_limitedwithRetry-Afteruntil the minute ends. -
Answers of the limited routes carry
X-RateLimit-LimitandX-RateLimit-Remaining; the simulation routes also carryX-RateLimit-Cells-LimitandX-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:
{
"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=86400and anETag; sendIf-None-Matchto 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.