# PVGIS, zonnestroom per plek

Het Photovoltaic Geographical Information System van het Joint Research Centre rekent voor elke coördinaat uit hoeveel zonlicht er valt en wat een zonnepaneelsysteem oplevert: per jaar, per maand, per uur, voor een vaste of meedraaiende opstelling, en een typisch meteorologisch jaar. Het rekent met stralingsdata uit satellietbeelden (PVGIS-SARAH3 voor Europa). Er is een webtool en een API zonder registratie. Let op: robots.txt verbiedt alle geautomatiseerde bezoekers; de Open Data Index roept PVGIS daarom zelf niet aan.

- Uitgever: Joint Research Centre (Europese Commissie)
- Gebied: Wereld · Laagste detail: punt (coördinaat)
- Periode: verschilt per stralingsdatabase (niet vastgesteld) · Ververst: elke paar jaar
- Toegang: Open · Licentie: Niet vastgesteld (geen eigen licentie op de PVGIS-pagina's; EU-inhoud valt volgens de legal notice van de Commissie onder CC BY 4.0 tenzij anders vermeld)
- Koppelsleutels: coördinaten (breedte, lengte)
- Status: grijs
- URL: https://joint-research-centre.ec.europa.eu/photovoltaic-geographical-information-system-pvgis_en

## Wat kun je ermee?
- **Loont zonnepanelen in jouw straat?.** Vul in de webtool je adres, dakhelling en oriëntatie in. PVcalc geeft de jaaropbrengst (E_y, kWh) en de straling op het paneel (H(i)_y, kWh/m²).
- **Zomer tegen winter.** De maanduitvoer laat zien hoe ongelijk zonnestroom over het jaar valt. Handig bij verhalen over salderen en netcongestie.
- **Oost-west of zuid?.** Reken dezelfde plek door met aspect -90, 0 en 90 (oost, zuid, west). Oost-west levert minder per jaar maar spreidt de opbrengst over de dag.
- **Noord tegen zuid in Nederland.** Vergelijk een paar plaatsen met dezelfde instellingen. Zet ze naast de gemeten zonnestraling van de KNMI-stations.

## Zo verwerk je het
1. **Begin in de webtool.** De webtool doet dezelfde berekeningen als de API, met een kaart om een punt te kiezen en downloads als CSV of JSON.
   `https://re.jrc.ec.europa.eu/pvg_tools/en/tools.html`
2. **Eén berekening met de API.** Alleen GET. Verplicht zijn lat, lon, peakpower (kW) en loss (systeemverlies in procent).
   `https://re.jrc.ec.europa.eu/api/v5_3/PVcalc?lat=52.09&lon=5.12&peakpower=1&loss=14&outputformat=json`
3. **Kies de tool.** PVcalc (netgekoppeld systeem), SHScalc (los systeem met accu), MRcalc (maandstraling), DRcalc (dagprofiel), seriescalc (uurreeks), tmy (typisch meteojaar) en printhorizon (horizon).
4. **Hou je aan de limieten.** Maximaal 30 aanroepen per seconde per IP, daarboven 429. Aanroepen vanuit de browser (AJAX) worden geweigerd. Gebruik bij voorkeur outputformat=json.

## Interessante koppelingen
- Halen de panelen wat ze zouden kunnen? → [cbs-statline](https://www.opendataindex.nl/bron/cbs-statline.md) via gemeente (coördinaat van de kern). Deel de echte productie uit CBS 85005NED door het opgestelde vermogen en zet dat naast de PVGIS-opbrengst per kWp voor die plek. Let op panelen die midden in het jaar zijn geplaatst.
- Zonnepotentie per adres → [pdok-bag](https://www.opendataindex.nl/bron/pdok-bag.md) via coördinaten van het pand. Neem de coördinaat van een pand uit de BAG en reken de opbrengst uit. Voor dakhelling en schaduw heb je wel een hoogtemodel nodig.

## Vergelijkbare bronnen
- [knmi-daggegevens](https://www.opendataindex.nl/bron/knmi-daggegevens.md): De KNMI meet de zonnestraling op zijn weerstations, dag voor dag (De Bilt sinds juli 1957). Geen opbrengstberekening, wel echte metingen.
- [era5](https://www.opendataindex.nl/bron/era5.md): Heranalyse met straling per uur op een raster van ongeveer 30 km, wereldwijd en sinds 1940. Vraagt een account.
- [cbs-statline](https://www.opendataindex.nl/bron/cbs-statline.md): Het CBS telt hoeveel zonnestroom er echt is opgewekt en hoeveel panelen er liggen (bijvoorbeeld tabel 85005NED), per gemeente.

## Waar je op moet letten
- **robots.txt verbiedt bots.** re.jrc.ec.europa.eu heeft 'Disallow: /' voor alle user-agents. De API is wel bedoeld voor programma's (non-interactive service). Wij roepen hem niet zelf aan en tonen hier geen eigen PVGIS-cijfers.
- **Een berekening, geen meting.** PVGIS rekent met satellietstraling, een modelpaneel en het systeemverlies dat jij opgeeft. Echte opbrengst hangt ook af van schaduw, vervuiling en de omvormer.
- **Licentie niet expliciet.** Op de PVGIS-pagina's staat geen eigen licentie. De algemene legal notice van de Commissie noemt CC BY 4.0 voor EU-inhoud tenzij anders vermeld. Vermeld PVGIS en de JRC als bron.
- **Versies wisselen.** Het adres zonder versienummer gaf sinds 25 september 2024 PVGIS 5.2, voor een beperkte tijd; 5.1 is weg. Zet de versie altijd in de URL (v5_3).

## API (REST (GET; JSON, CSV, EPW))

- Basis: https://re.jrc.ec.europa.eu/api/v5_3
- Toegang: Geen sleutel of account volgens de documentatie. Alleen GET; aanroepen vanuit de browser (AJAX/CORS) worden geweigerd. (uit de beschrijving)
- Formaten: json, csv, basic, epw
- Filteren: Geen querytaal: één punt en de eigenschappen van het systeem als queryparameters; elke aanroep is een berekening.; 

### Endpoints
- `GET /PVcalc`: Opbrengst van een netgekoppeld systeem (vast of met volgsysteem): per maand en per jaar (E_y in kWh), met verliezen; optioneel optimale hoek en stroomprijs.
- `GET /SHScalc`: Los systeem met accu: hoe vaak de accu leeg of vol is (peakpower hier in W, niet kW).
- `GET /MRcalc`: Straling per maand over de jaren (horirrad, optrad, mr_dni, avtemp …; minstens één nodig).
- `GET /DRcalc`: Gemiddeld dagprofiel per maand (month verplicht, 0 = alle maanden).
- `GET /seriescalc`: Uurreeks van straling (en met pvcalculation=1 de PV-opbrengst) over een reeks jaren, in UTC.
- `GET /tmy`: Typisch meteorologisch jaar (periode ≥ 10 jaar); ook als EnergyPlus-EPW.
- `GET /printhorizon`: Horizonprofiel (hoogte van de horizon per richting) op een punt.

### Parameters
- `lat / lon`: Decimale graden (zuid en west negatief). Verplicht. (uit de beschrijving)
- `peakpower`: Piekvermogen in kW (PVcalc, seriescalc) of W (SHScalc). (uit de beschrijving)
- `loss`: Systeemverlies in procent (14 is gangbaar). Verplicht bij PVcalc. (uit de beschrijving)
- `angle / aspect`: Hellingshoek t.o.v. horizontaal en richting: 0 = zuid, 90 = west, -90 = oost. Standaard 0 en 0. (uit de beschrijving)
- `optimalinclination / optimalangles`: Laat PVGIS de beste hoek (en richting) kiezen; overschrijft angle/aspect. (uit de beschrijving)
- `mountingplace / pvtechchoice`: free of building; crystSi (standaard), crystSi2025, CIS, CdTe, Unknown. (uit de beschrijving)
- `raddatabase`: Stralingsdatabase: PVGIS-SARAH3 (Europa, Afrika, Azië), PVGIS-ERA5, PVGIS-SARAH …; zonder kiest PVGIS op locatie. (uit de beschrijving)
- `startyear / endyear`: Periode voor seriescalc, MRcalc en tmy; standaard de hele database. (uit de beschrijving)
- `usehorizon / userhorizon`: Schaduw van de horizon meenemen (standaard 1) of zelf hoogtes opgeven. (uit de beschrijving)
- `outputformat`: csv (standaard, met uitleg), json (aanbevolen), basic (alleen getallen), epw (alleen tmy). (uit de beschrijving)
- `pvprice / systemcost / interest / lifetime`: Stroomprijs per kWh uitrekenen uit installatiekosten, rente en levensduur (standaard 25 jaar). (uit de beschrijving)

### Velden in het JSON-antwoord (voor zover de documentatie ze noemt) (4)
`inputs` object, `outputs` object, `outputs.totals.fixed.E_y` getal, `meta` object

### Limieten en valkuilen
- 30 aanroepen per seconde per IP; daarboven 429. Bij drukte wacht de server tot 4–5 seconden en geeft dan 529 (Site is overloaded). (uit de beschrijving)
- Alleen GET (anders 405). HEAD op een tool geeft 204 om te zien of die bestaat. (uit de beschrijving)
- robots.txt van re.jrc.ec.europa.eu is 'Disallow: /'. Open Data Index roept de API daarom niet automatisch aan; alles hier komt uit de JRC-documentatie. (getest)
- Het oude pad /api/ zonder versie geeft PVGIS 5.2 'voor beperkte tijd' (sinds 25 sep 2024); 5.1 is weg. Zet altijd v5_3 (of v5_2) in de url. (uit de beschrijving)
- Let op de eenheid van peakpower: kW bij PVcalc en seriescalc, W bij SHScalc. (uit de beschrijving)
- Waarden buiten het bereik geven een JSON-foutmelding met het toegestane bereik. (uit de beschrijving)


## Voorbeelden met echte cijfers (1)

Per voorbeeld de bevinding, de peildatum en de aanroep die precies deze cijfers ophaalt.

- **Zonnestraling op een plat vlak in De Bilt (KNMI-metingen): gemiddeld 1.038 kWh per m² per jaar in 1996–2025, 8% meer dan in 1958–1987** (2025). Tabel daggegevens. [Voorbeeld](https://www.opendataindex.nl/voorbeeld/knmi-zonnestraling-de-bilt)
  - `curl -d "stns=260&vars=Q&start=19580101&end=20251231&fmt=json" https://www.daggegevens.knmi.nl/klimatologie/daggegevens`