Appearance
DEEL 3 - AERIUS CALCULATOR ALS GEBRUIKER
8 - Aanvullende mogelijkheden: Connect API en QGIS plug-in
Het grootste deel van de gebruikers van AERIUS zal aan AERIUS Calculator genoeg hebben om hun berekeningen uit te voeren. De applicatie is uitgebreid genoeg om zowel ervaren als minder ervaren gebruikers door het proces heen te loodsen en tot een resultaat te komen.
Toch kan het voorkomen dat je als gebruiker niet voldoende uit de voeten kan met de applicatie:
Als je meer dan 5.000 emissiebronnen wilt doorrekenen
Als je wilt rekenen met specifieke rekeninstellingen die niet via de applicatie ondersteund worden
Als je je eigen werkprocessen wilt automatiseren waarbij het wenselijk is om eigen systemen direct aan het rekenhart van AERIUS te kunnen koppelen
Als je rekenresultaten wilt bewerken, zonder betaald GIS pakket
Voor deze gebruikers zijn de Connect API en/of de IMAER plug-in voor QGIS beschikbaar. Dit hoofdstuk gaat op deze aanvullende services in.
8.1 Rekenen met de AERIUS Connect API
AERIUS stelt een API (Application Programming Interface) beschikbaar, waarmee je via een computer interface (API) opdrachten kan uitvoeren zonder gebruik te maken van de gebruikersomgeving (GUI) zoals die beschreven staat in hoofdstuk 7 van dit handboek.
8.1.1 Wat is een API?
API staat voor Application Programming Interface. Een API maakt het mogelijk om afzonderlijke softwareprogramma's of -onderdelen met elkaar te laten communiceren. Het is een software-naar-software interface, onzichtbaar voor gebruikers, en biedt daarom per definitie geen gebruikersomgeving (GUI).
Softwareontwikkelaars kunnen met behulp van een API programmeercode en/of gegevens uitwisselen. De benodigde code wordt uitgevoerd op de server van de AERIUS, die het resultaat vervolgens naar de client stuurt. Op het internet hebben API's meestal als doel om gebruikers (zoals web-ontwikkelaars) toegang te geven tot een aantal voorgedefinieerde procedures, zoals het ophalen, bewerken of opslaan van bepaalde gegevens.
Gebruikers van AERIUS kunnen een zogeheten API-sleutel aanvragen, waarmee het mogelijk wordt om direct via de API te rekenen zonder tussenkomst van de gebruikers applicatie.
8.1.2 De API webservice van AERIUS
De API webservice gaat uit van het HTTP REST protocol en is gedefinieerd met OpenAPI (versie 3.0.1). Dat laatste houdt in dat een aantal zogenoemde yaml bestanden zijn gemaakt volgens deze standaard, die de webservice definiëren. Het formaat voor de gegevensuitwisseling is JSON.
Voor meer uitleg over alle verschillende API functies, verwijzen we naar de AERIUS Connect API documentatie pagina: https://connect.aerius.nl/api/. Op basis van de yaml bestanden, wordt ook automatisch deze documentatie pagina gegenereerd. De verschillende API functies worden hier toegelicht en ook de link naar het betreffende yaml bestand is opgenomen.
LET OP: Via bovenstaande url, kan de API ook uitgeprobeerd worden met automatische voorbeelden. Dit kan handig zijn om een idee te krijgen hoe het werkt, maar het is wel goed te realiseren dat de gegenereerde voorbeelden automatisch alle opties invullen met standaard waardes, en niet alleen de minimaal verplichte velden. Voor sommige gebruikers kan dit verwarrend zijn.
8.1.3 Waarom rekenen via de API?
Direct via de API rekenen in plaats van via de gebruikers applicatie, heeft een aantal voordelen:
Bij direct rekenen via de API, is er geen limiet op het aantal bronnen dat je mag doorrekenen. Gebruikers van de API zijn namelijk niet meer anoniem: je moet een API-sleutel aanvragen en daarmee is je e-mail adres bekend. Daarmee kan de limiet van maximaal 5.000 emissiebronnen doorrekenen, die geldt in de applicatie Calculator, losgelaten worden. Misbruik kan namelijk tegengegaan worden door de API sleutel weer te blokkeren. Direct rekenen via de API sleutel is daarmee een oplossing voor berekeningen met meer dan 5.000 emissiebronnen.
Direct rekenen via de API maakt het mogelijk om een intern werkproces in te richten voor het uitvoeren van AERIUS-berekeningen en voor het verwerken van de resultaten in de organisatie-eigen applicatie architectuur, zonder tussenkomst van de gebruikersschil van Calculator. Het maakt het namelijk mogelijk om direct vanuit eigen client applicatie (bijvoorbeeld eigen GIS) te communiceren met de AERIUS Calculator. Webservices zijn eenvoudig, en te gebruiken door softwareontwikkelaars.
Daarnaast maakt rekenen met de API het mogelijk om te kiezen voor 'Analysis, als alternatief voor 'OwN2000 Calculations'.
Bij OwN2000-Calculations is het rekenresultaat bruikbaar in het kader van toestemmingsverlening voor Natura 2000-activiteiten. Bij het rekenen ben je gebonden aan de regels voor het rekenen voor natuurvergunningen: zo kan je bijvoorbeeld niet rekenen op grotere afstand dan de vaste afstandsgrenswaarde. Rekenen via het OwN2000-endpoint, is inhoudelijk gelijk aan rekenen via de AERIUS applicatie. Ook de export bestanden zijn gelijk: GML of pdf.
Bij Analysis kunnen geavanceerde gebruikers eigen berekeningen uitvoeren die niet per se voldoen aan de voorwaarden voor een formele OwN2000-berekening. Dit kan handig zijn voor analysedoeleinden, maar het is in dit geval niet mogelijk een export te krijgen die ook bruikbaar is voor een aanvraag in het kader van een natuurvergunning. Ook moet je altijd zelf je rekenpunten aanleveren waarop gerekend moet worden.
In dit hoofdstuk richten we ons op het rekenen via het OwN2000-endpoint, omdat dat direct in het verlengde van de Calculator zelf ligt en de enige manier is om een voor een vergunning aanvraag geldige berekening te doen. Voor meer informatie over het rekenen via de Analysis-endpoint, verwijzen we naar de documentatie pagina van Connect zoals hierboven genoemd.
8.1.4 Rekenen via het 'OwN2000-endpoint' in het kort
Om een berekening te doen die bruikbaar is in een vergunningentraject, kies je rekenen via het OwN2000-endpoint. Rekenen via het OwN2000-endpoint gaat als volgt:
Je levert als gebruiker je rekentaak aan (1 of meer situaties) en je kiest de gewenste output (GML of pdf, met of zonder 'bijlage randhexagonen').
Je rekentaak zal gevalideerd worden: als je bijvoorbeeld een pdf Projectberekening wilt, moet de rekentaak wel voldoen aan de criteria voor een projectberekening (geen tijdelijke situaties).
LET OP: als je via de Connect API meerdere situaties van hetzelfde type aanlevert, zullen deze automatisch samengevoegd worden. Bij het aanleveren van twee beoogde situaties in je rekentaak, zal hij dus niet zeggen dat dit niet kan, maar de invoer van de twee beoogde situaties samenvoegen en het zien als 1 beoogde situatie.
Je geeft aan of je wilt rekenen op het OwN2000-grid ('OwN2000_receptors'), OF dat je op eigen rekenpunten ('custom_points') wilt rekenen.
LET OP: Als je kiest voor eigen rekenpunten, moet je deze altijd als apart bestand ook aanleveren. De Connect API kan de rekenpunten niet uit de invoer GML uitlezen, zoals de applicatie dat wel doet.
LET OP: via de Calculator applicatie, kan je in één OwN2000 berekening het rekenen op het OwN2000-grid combineren met het aanvullend rekenen op eventuele eigen rekenpunten (bv in buitenland). De resultaten komen dan ook samen in de pdf. Bij het rekenen via de API voor OwN2000, werkt het niet zo. Rekenen op eigen rekenpunten is een aparte route binnen de API, en dat betekent dat je voor je eigen rekenpunten een extra berekening zal moeten doen. Het resultaat is in dat geval dus ook twee pdf's (eentje voor het grid en eentje voor de eigen rekenpunten), waar het via de applicatie in 1 pdf kan.
Je voert de berekening uit en krijgt de gewenste export. Dit is of een GML met resultaten per situatie, of een pdf.
8.2 De QGIS plugin als ondersteunende functionaliteit
In hoofdstuk 2 is toegelicht dat AERIUS geen GIS functionaliteiten biedt. AERIUS Calculator werkt bewust met GML als uitwisselingsformaat, en wordt expliciet niet ontworpen en onderhouden als instrument voor datatransformatie. Door uit te gaan van IMAER en alleen GML te accepteren, blijft de applicatie generiek, flexibel en gemakkelijker in beheer, en kunnen gebruikers zelf data transformeren op basis van IMAER.
Om gebruikers echter extra te ondersteunen bij de transformatie van GML naar GIS en andersom, is aanvullend op de AERIUS producten een QGIS plugin ontwikkeld namelijk de QGIS IMAER plug-in(verder: QGIS plugin). In de basis kan je hiermee data converteren. Je kan namelijk:
AERIUS-resultaten in een GML, omzetten naar GIS formaat: Resultaten in GML-formaat (GML met resultaten uit AERIUS) kan je importeren en vervolgens inzien, bewerken, analyseren en exporteren in GIS formaat. Je kan tevens de GML weer exporteren als volledige GML.
GIS gegevens over bronnen, omzetten naar GML bronbestand: Je kan invoergegevens in GIS formaat importeren, en vervolgens omzetten naar een bronbestand voor AERIUS (GML). Dit werkt voor generieke bronnen en rijdend verkeer. De GML kan je weer exporteren.
Daarnaast is het met de plug-in mogelijk om GML's die je hebt geïmporteerd of aangemaakt in de plug-in, direct door te rekenen via de Connect API. Je gebruikt de plug-in dan eigenlijk als 'portaal' naar de Connect API. Tevens kan je de plug-in gebruiken om onderliggende GML's uit een pdf halen en deze op te slaan. Overigens kan je dat ook bereiken door een pdf in de Calculator in te laden en de situaties vervolgens als invoerbestanden (GML) te exporteren.
De plug-in bestond eerder voor QGIS 2, en is opnieuw ontwikkeld voor QGIS-versie 3. De QGIS plug-in is het een handige aanvulling als je als gebruiker de resultaten verder wilt bewerken of op een andere manier in je eigen workflow wilt integreren.
Figuur 54: QGIS IMAER plugin toolbar
Onderstaand een overzicht van de totale huidige functionaliteit van de plug-in, in volgorde van de getoonde knoppenbalk:
Zelf GML met brongegevens maken, voor generieke bronnen of rijdend verkeer ('Generate Calculator Input')
Openen AERIUS Calculator resultaten GML ('Import Calculator Results')
Bewerken van resultaten met standaard handelingen (verschil, som, max) (´Relate Calculator Results´)
Toevoegen eigen rekenpunten Connect - Receptor Sets
Berekeningen aanzetten en voortgang zien
De plugin configuratie (o.a. API-key en e-mailadres)
Verwijzing naar Github met alle uitleg
De volledige documentatie over hoe te werken met de QGIS plug-in is (in het Engels) ook direct te vinden op Github[1].
Installatie
De IMAER plug-in voor QGIS wordt gepubliceerd in de QGIS plug-in repository, dus de eenvoudige manier om te installeren is met behulp van de Plugin Manager binnen QGIS. Voor de gevorderde gebruiker is het uiteraard ook mogelijk om de code te clonen vanuit de Github repository en deze handmatig te installeren.
8.3 Samenvatting: wat nu wanneer gebruiken?
Hieronder volgt een schematisch overzicht van het toepassingsbereik van AERIUS Calculator versus de AERIUS Connect API en de IMAER plug-in voor QGIS. Onder de tabel staat een nadere toelichting.
| Calculator vs. Connect | Calculator (via UI) | Connect API | QGIS plug-in |
|---|---|---|---|
| Grootschalige projecten | Max 5.000 bronnen doorrekenen | > 5.000 bronnen doorrekenen | Ja, door berekening via Connect aan te zetten |
| Rekenresultaat opgesplitst naar sector | Nee | Ja | Nee |
| Bepalen hoogste bijdrage van twee doorgerekende bronbestanden | Ja, maar alleen voor 'tijdelijke situaties' | Nee | Ja, via max |
| IMAER validatie-service | Ja | Ja | Ja |
| IMAER conversie-service | Ja | Ja | Nee |
| GML's combineren en als 1 situatie doorrekenen | Ja | Ja | Nee |
| GML terugkrijgen uit AERIUS pdf | Ja, maar wel altijd obv actuele IMAER en EF | Ja | Nee |
| Eerder berekende resultaten inzien | Ja, met behulp van resultaten gml | Nee | Ja |
| Directe communicatie vanuit eigen IT-systeem met rekenhart AERIUS Calculator | Nee | Ja | Nee |
Tabel 10: Toepassingsbereik van Calculator, Connect en IMAER plug-in
Grootschalige projecten: er is voor gekozen om berekeningen met meer dan 5.000 emissiebronnen, niet toe te staan via de applicatie van AERIUS Calculator. Bij dergelijke grote berekeningen is het gewenst dat je als gebruiker een API sleutel aanvraagt, zodat je niet meer anoniem bent. Vervolgens kan je met die API sleutel direct rekenen via de Connect API. Een berekening via de API kan ook via de IMAER plug-in voor QGIS aangezet worden.
Rekenresultaat opgesplitst naar sector. De rekenresultaten kan je via Connect (analysevariant) ook per sector opvragen en worden dan als zodanig in de GML opgenomen.
Bepalen hoogste bijdrage van twee of meer bronbestanden. In de Calculator applicatie wordt automatisch een maximum berekend voor alle 'tijdelijke situaties'. Voor het bepalen van een maximum bij 2 tot 5 willekeurige situaties, kan je ook de IMAER plug-in voor QGIS gebruiken. Op basis van meerdere resultaatbestanden wordt een nieuw resultaatbestand gemaakt door van elke gevonden resultaat punt de hoogste waarde te nemen.
IMAER Validatie-service. Bij inlezen van één of meerdere bestanden in Calculator, wordt automatisch gevalideerd of de invoer voldoet aan IMAER. Via de Connect API validatie service is het mogelijk ook te valideren, zonder dat je de applicatie nodig hebt.
IMAER Conversie-service: Oudere versies (vanaf 1.0) van IMAER GML's worden omgezet naar de meest actuele IMAER-versie. Dat gebeurt ook als je een GML importeert in AERIUS Calculator. Voordeel van de Connect API is dat je die zodanig kunt aansturen dat je meerdere GML's kunt converteren. Bij de nieuwe Calculator kan je tot 6 GML's tegelijk invoeren en converteren.
GML's combineren tot 1 set van bronnen en dan in 1 keer doorrekenen: meerdere GML's kunnen samengevoegd worden tot 1 situatie, door in Calculator in een bestaande situatie nieuwe GML's toe te voegen. In Connect kan dit ook door meerdere GML's van hetzelfde situatietype tegelijk aan te bieden: alle situaties van hetzelfde type worden samengevoegd en als 1 situatie doorgerekend. Als resultaat ontvang je vervolgens één GML met alle bronnen uit de verschillende invoer GML's en de daarbij horende totale emissies van alle bronnen.
GML terugkrijgen uit AERIUS pdf. Aan een AERIUS pdf zijn in de bijlagen losse IMAER GML's gezipt toegevoegd. Ook is het mogelijk om een AERIUS pdf te converteren - via de conversie service- wat resulteert in een losse IMAER GML. Die GML kan je vervolgens weer bewerken en opnieuw aanbieden. Bij het inlezen van een pdf in de applicatie van Calculator, kan je ook eenvoudig de onderliggende GML's weer exporteren. In dat geval is de GML wel automatisch omgezet naar de nieuwe IMAER en worden emissies automatisch berekend op basis van nieuwe emissiefactoren.
Eerder berekende resultaten inzien. Via een rekentaak GML kan een gebruiker in Calculator resultaten opnieuw inladen. Connect is een 'rekenmachine' en biedt niet de mogelijkheid om op kaart eerder uitgevoerde berekeningen te visualiseren. Met de IMAER plug-in voor QGIS is het eveneens mogelijk om resultaten uit AERIUS in te zien.
Directe communicatie vanuit eigen client applicatie (bijv. eigen GIS) communiceren met het rekenhart van AERIUS Calculator. Resultaten van een AERIUS validatie, conversie, en berekening kan je direct in het eigen IT-Systeem bekijken, analyseren en combineren met eigen databronnen.