Let op: dit is niet een actuele versie
Actuele versie: 01-09-2017

AERIUS Connect API - Handleiding

In het kort
Berekeningen met AERIUS Calculator kunnen worden uitgevoerd met een webservice. Deze webservice gaat uit van het websocket protocol. Dit protocol maakt berichtenverkeer in twee richtingen mogelijk over een internetverbinding. Het formaat voor de gegevensuitwisseling is JSON-RPC. Het websocket protocol, JSON-RPC, en de verschillende API functies worden hieronder nader toegelicht. Deze facstheets beschrijft AERIUS Connect API versie 2

Websocket Protocol
Een webservice maakt gebruik van een communicatie protocol om te communiceren tussen gebruiker en server. AERIUS connect gebruikt hiervoor het websocket protocol. Dit protocol maakt berichtenverkeer in twee richtingen mogelijk over een internetverbinding. Daarnaast werkt het asynchroon en kunnen resultaten in een andere volgorde komen dan de volgorde van opdrachten, hiervoor wordt het id gebruikt om verzoek en antwoord weer aan elkaar te koppelen. Meer informatie over websocket is te vinden op www.websocket.org.

JSON-RPC
Boven op het websocket protocol communiceert de AERIUS connect API op basis van het JSON-RPC protocol. Het JSON-RPC protocol is een specificatie om in JSON (JavaScript Object Notation) RPC (remote procedure calls) uit te voeren. Hierbij wordt als het ware een functie aangeroepen die op de server wordt uitgevoerd. Het JSON-RPC protocol benoemt hoe functienaam, functie argumenten, resultaten en foutmeldingen moeten worden beschreven. Uitgebreidere informatie hierover kan worden gevonden op de website van JSON-RPC: http://www.jsonrpc.org/specification.

Functionaliteit AERIUS Connect API 2
Hieronder volgt een beschrijving van de beschikbare functionaliteit van de AERIUS Connect API versie 2. Het betreft opdrachten voor het valideren, converteren, rekenen en maken van documenten -bijlagen- met AERIUS Calculator. Zie ook factsheets.

De URL van de webservice is:

ws://connect.aerius.nl/connect/2/services

1. Valideren van data bestanden
Deze validator rpc functie controleert op correctheid van de IMAER GML bestanden tegen het IMAER schema. De validator controleert ook op valide domein waarden van sector categorieën en of bepaalde waarden binnen de toegestane grenswaarden vallen.

Functie

validation.validate

Opties

dataType
verplicht
Het type van de invoer. Ondersteunde waarden zijn:
GML: AERIUS IMAER GML
ZIP: ZIP bestand met als inhoud één AERIUS IMAER GML bestand.
contentType
verplicht
De codering van het data object. Ondersteunde waarden zijn:
TEXT: de data is textueel.
BASE64: de data is base 64 gecodeerd. Zip en pdf bestanden zullen altijd base64 gecodeerd moeten zijn, terwijl een GML ook als text kan worden meegegeven.
data
verplicht
De data die gevalideerd moet worden. Dit is een text of base64 representatie van één van bovengenoemde ondersteunde content typen zijn.

Voorbeeld
Voorbeeld van json invoer van een GML als TEXT invoer:

{
  "jsonrpc":"2.0",
  "id":14343,
  "method":"validation.validate",
  "params":{
    "dataType":"GML",
    "contentType":"TEXT",
    "data":"<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?><imaer:FeatureCollectionCalculator ..."
  }
}

Resultaat
De validator geeft via een veld successful de status terug of de validate geslaagd is. Indien de validatie niet geslaagd is wordt een lijst met fouten terug gegeven.

successful
verplicht
De status van de validatie. Als true dan is de GML valide en false als de GML niet valide is. Als de GML niet valide is wordt in errors de fouten weergegeven.
errors
optioneel
De lijst met fouten indien de validatie niet succesvol was. Als de validatie succesvol was is dit veld afwezig.
warnings
optioneel
De lijst met waarschuwingen. Waarschuwingen kunnen ook aanwezig zijn als de validatie succesvol was, maar dit veld is niet aanwezig als er geen waarschuwingen zijn.

Inhoud van errors en warnings:

code De AERIUS error code gekoppeld aan de gemelde fout.
message Een gebruikersvriendelijke omschrijving van het probleem.

Voorbeeld
Voorbeeld van json uitvoer van een validate met een foute GML:

{
  "jsonrpc":"2.0",
  "id":14343,
  "result":{
    "successful":"false",
    "errors": [
        {"code":"5207",
         "message":"Het GML bestand bevat een onbekende RAV code (A1.332). ID: ES.1"
        }
    ]
  }
}

2. Converteren van data bestanden
De converter rpc functie converteert GML bestanden (oudere versie IMAER) naar de laatste versie van de IMAER. Het te converteren bestand wordt eerst gevalideerd, zoals de validator dat doet. Als dit geen problemen oplevert wordt het bestand omgezet naar een GML van de laatste versie van IMAER.

Functie

conversion.convert

Opties

dataType
verplicht
Het type van de invoer. Ondersteunde waarden zijn:
GML: AERIUS IMAER GML
ZIP: ZIP bestand met als inhoud één AERIUS IMAER GML bestand.
contentType
verplicht
De codering van het data object. Ondersteunde waarden zijn:
TEXT: de data is textueel.
BASE64: de data is base 64 gecodeerd. Zip en pdf bestanden zullen altijd base64 gecodeerd moeten zijn, terwijl een GML ook als text kan worden meegegeven.
data
verplicht
De data die gevalideerd moet worden. Dit is een text of base64 representatie van één van bovengenoemde ondersteunde content typen zijn.

Voorbeeld
Voorbeeld van json invoer van een GML als TEXT invoer:

{
  "jsonrpc":"2.0",
  "id":0,
  "method":"conversion.convert",
  "params":{
    "dataType":"GML",
    "contentType":"TEXT",
    "data":"<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?><imaer:FeatureCollectionCalculator ..."
  }
}

Resultaat
De functie convert geeft via een veld successful de status terug of de conversie geslaagd is. Indien de conversie niet geslaagd is wordt een lijst met fouten teruggegeven. Als de conversie wel geslaagd is wordt het geconverteerde bestand in het veld data teruggegeven.

successful
verplicht
De status van de conversie. Als het true is dan is de GML valide en false als de GML niet valide is. Als de GML niet valide is wordt in errors de fouten weergegeven.
dataType
optioneel
Het type van het resultaat. Het data type is GML of -indien de invoer ZIP was- ZIP. Dit veld is alleen gezet als de conversie succesvol was.
contentType
optioneel
De codering van het data object. Het content type is gelijk aan het type van het invoer bestand. Dit veld is alleen gezet als de conversie succesvol was.
data
optioneel
De data van het geconverteerde bestand. Het bestand is van het data- en content type zoals in andere velden aangegeven. Dit veld is alleen gezet als de conversie succesvol was.
errors
optioneel
De lijst met fouten indien de validatie niet succesvol was. Als de validatie succesvol was is dit veld afwezig.
warnings
optioneel
De lijst met waarschuwingen. Waarschuwingen kunnen ook aanwezig zijn als de validatie succesvol was, maar dit veld is niet aanwezig als er geen waarschuwingen zijn.

Voorbeeld
Voorbeeld van json uitvoer van een geslaagde conversie:

{
  "jsonrpc":"2.0",
  "id":14343,
  "result":{
    "successful":"true",
    "dataType":"GML",
    "contentType":"TEXT",
    "data":"<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?><imaer:FeatureCollectionCalculator ..."
  }
}

3. Rekenen: resultaten via email.
De rpc functie rekenen voert een AERIUS berekening uit en stuurt het resultaat via het opgegeven e-mail adres terug. Als de invoer niet gevalideerd kon worden dan wordt dit op dezelfde manier teruggegeven als bij de functie validatie. Als resultaat aangeeft dat het succesvol was, dan is de rekenopdracht aangeboden aan AERIUS Calculator. De gebruiker kan dan de verbinding verbreken. Wanneer de rekenopdracht is afgerond, ontvangt de gebruiker een email. De email bevat een downloadlink die gebruikt kan worden om de rekenresultaten te downloaden.

Functie

calculation.calculateAndEmail

Opties

email
verplicht
Het e-mail adres waar de resultaten naar toe gestuurd moeten worden.
options
verplicht
De rekenopties waarmee gerekend moet worden. Zie rekenoptie tabel.
data
verplicht
Een lijst van 1 of meerdere bronbestanden die samen de invoer van de berekening vormen.

Reken opties
De volgende velden zijn ondersteund voor het options veld.

calculationType
verplicht
Type van de berekening. De volgende opties worden ondersteund:
NBWET
Rekent voor een nb wet vergunning.
NATURE_AREA
Rekent in een straal als gezet in de optie range alle receptoren die in die straal in een natuurgebied liggen.
RADIUS
Rekent alle receptoren in de straal van de bronnen als gezet in de optie range.
CUSTOM_POINTS
Rekent de eigen punten opgegeven in de meegegeven GML. Indien meerdere GML bestanden worden opgegeven worden alle punten uit alle GML bestanden berekend.
year
verplicht
Het rekenjaar waarvoor gerekend moet worden. Dit wordt gebruikt om specifieke emissies waarden bij dat jaar te bepalen. Hoewel het rekenjaar ook in de meta data van de GML kan worden opgegeven, moet het rekenjaar via deze optie worden opgegeven en wordt een rekenjaar in de GML niet meegenomen.
substances
verplicht
De lijst met emitterende stoffen waarvoor gerekend moet worden. De ondersteunde stoffen zijn:
NH3, NOX
Bij NOx wordt automatisch ook NO2 meeberekend, indien er voor de bron NO2 waarden zijn.
range
optioneel verplicht
Geeft de straal van de bronnen tot waar gerekend moet worden. Deze optie is verplicht voor de reken opties: NATURE_AREA en RADIUS. Voor de andere opties heeft dit veld geen effect.
tempProject
optioneel
Als true dan wordt de berekening als een een tijdelijk project gedaan.
tempProjectYears
optioneel verplicht
Als tempProject op true is gezet moet hier het aantal jaren van het tijdelijke project worden opgegeven.
researchArea
optioneel
Als true dan wordt de berekening gedaan op een onderzoeksgebied. Het onderzoeksgebied wordt bepaald door die databestanden waarbij in de opties researchArea op true is gezet. Zie ook tabel data gegevens. Bij een onderzoeksgebiedberekening moet tenminste 1 databestand zijn aangemerkt als onderzoeksgebied en tenminste 1 die het databestand aangeeft dat moet gebruikt worden om de emissie effecten te bereken. De bronnen in het databestand dat is aangemerkt als onderzoeksgebied moeten ook in het databestand worden geplaatst om de emissie effecten te berekenen.

Data opties
In het data veld wordt een lijst van data bestanden meegegeven. Per databestand worden de volgende velden ondersteund.

dataType
verplicht
Het type van de invoer. Ondersteunde waarden zijn:
GML: AERIUS IMAER GML
ZIP: ZIP bestand met als inhoud één AERIUS IMAER GML bestand.
contentType
verplicht
De codering van het data object. Ondersteunde waarden zijn:
TEXT: de data is textueel.
BASE64: de data is base 64 gecodeerd. Zip en pdf bestanden zullen altijd base64 gecodeerd moeten zijn, terwijl een GML ook als text kan worden meegegeven.
data
verplicht
De data die gevalideerd moet worden. Dit is een text of base64 representatie van een van boven genoemde ondersteunde content typen zijn.
researchArea
optioneel
Indien een onderzoeksgebied berekening wordt gedaan, wordt via dit veld aangegeven dat dit databestand gebruikt moet worden voor het bepalen van het onderzoeksgebied of om de emissie effecten te berekenen. Indien true wordt dit databestand gebruikt om het onderzoeksgebied te bepalen. Indien false of weggelaten dan wordt dit databestand meegenomen in de berekening van het emissie effect.

Voorbeeld
Voorbeeld van json invoer van een GML als TEXT invoer:

{
  "jsonrpc":"2.0",
  "id":0,
  "method":"calculation.calculateAndEmail",
  "params":{
    "email":"aerius@example.com",
    "options":{
      "calculationType":"NBWET",
      "year":2015,
      "substances":["NOX","NH3"]
    },
    "data":[{
        "dataType":"GML",
        "contentType":"TEXT",
        "data":"<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?><imaer:FeatureCollectionCalculator ..."
    }]
  }
}

4. Bijlage documenten via email
De rpc functie documenten voert een AERIUS berekening uit, maakt een bijlage document en stuurt dit document via het opgegeven e-mail adres terug. Er zijn 2 opties. De eerste is met 1 situatie invoer bronnen en de tweede is met 2 situaties invoer bronnen. Bij de tweede optie wordt een vergelijkingsbijlage document gemaakt, waarin het verschil tussen de beide situaties wordt weergeven. Als de rekenoptie NBWET wordt gebruikt wordt een "Vergunningsbijlage" document aangemaakt. Daarin wordt de meta data van de eerste GML van de proposed bronnen set gebruikt. Volgende metadata velden (IMAER) zijn dan verplicht: projectName; corporation; reference; description; streetAddress; postcode; city

Bij alle andere rekenopties wordt een "Bijlage voor eigen gebruik" aangemaakt. De metadata is dan niet verplicht, maar als er metadata in de eerste GML van de proposed bronnen set aanwezig is wordt deze wel gebruikt.

Als de invoer niet gevalideerd kon worden dan wordt dit in op dezelfde manier teruggegeven als bij functie validatie. Als resultaat aangeeft dat het succesvol was, dan is opdracht aangeboden aan AERIUS Calculator. De gebruiker kan dan de verbinding verbreken. Wanneer het document is aangemaakt, ontvangt de gebruiker een email. De email bevat een downloadlink die gebruikt kan worden om het document te downloaden.

Functie

report.calculateReportAndEmail

Opties

email
verplicht
Het e-mail adres waar het document naar toe gestuurd moeten worden.
options
verplicht
De rekenen opties waarmee gerekend moet worden. Zie rekenoptie tabel.
current
optioneel
Een lijst van 1 of meerdere bronbestanden die samen de invoer van de huidige situatie representeert. Als deze bronnenlijst is meegegeven wordt een vergelijkingsdocument gemaakt.
proposed
verplicht
Een lijst van 1 of meerdere bronbestanden die samen de invoer van de voorgestelde of nieuwe situatie representeren.

Reken opties
De volgende velden zijn ondersteund voor het options veld.

calculationType
verplicht
Type van de berekening. De volgende opties worden ondersteund:
NBWET
Rekent voor een nb wet vergunning en maakt een "Vergunningsbijlage" document.
NATURA_AREA
Rekent in een straal als gezet in de optie range alle receptoren die in die straal in een natuurgebied liggen en maakt een "Bijlage voor eigen gebruik" document.
RADIUS
Rekent alle receptoren in de straal van de bronnen als gezet in de optie range en maakt een "Bijlage voor eigen gebruik" document.
CUSTOM_POINTS
Rekent de eigen punten opgegeven in de meegegeven GML. Indien meerdere GML bestanden worden opgegeven worden alle punten uit alle GML bestanden berekend en maakt een "Bijlage voor eigen gebruik" document.
year
verplicht
Het rekenjaar waarvoor gerekend moet worden. Dit wordt gebruikt om specifieke emissies waarden bij dat jaar te bepalen. Hoewel het rekenjaar ook in de meta data van de GML kan worden opgegeven, moet het rekenjaar via deze optie worden opgegeven en wordt een rekenjaar in de GML niet meegenomen.
substances
verplicht
De lijst met emitterende stoffen waarvoor gerekend moet worden. De ondersteunde stoffen zijn:
NH3, NOX
Bij NOx wordt automatisch ook NO2 meeberekend, indien er voor de bron NO2 waarden zijn.
range
optioneel verplicht
Geeft de straal van de bronnen tot waar gerekend moet worden. Deze optie is verplicht voor de reken opties: NATURA_AREA en RADIUS. Voor de andere opties heeft dit veld geen effect.
tempProject
optioneel
Als true dan wordt de berekening als een een tijdelijk project gedaan.
tempProjectYears
optioneel verplicht
Als tempProject op true is gezet moet hier het aantal jaren van het tijdelijke project worden opgegeven.

Data opties
In het data veld wordt een lijst van data bestanden meegegeven. Per databestand worden de volgende velden ondersteund.

dataType
verplicht
Het type van de invoer. Ondersteunde waarden zijn:
GML: AERIUS IMAER GML
ZIP: ZIP bestand met als inhoud één AERIUS IMAER GML bestand.
contentType
verplicht
De codering van het data object. Ondersteunde waarden zijn:
TEXT: de data is textueel.
BASE64: de data is base 64 gecodeerd. Zip en pdf bestanden zullen altijd base64 gecodeerd moeten zijn, terwijl een GML ook als text kan worden meegegeven.
data
verplicht
De data die gevalideerd moet worden. Dit is een text of base64 representatie van een van boven genoemde ondersteunde content typen zijn.

Voorbeeld
Voorbeeld van json invoer van een GML als TEXT invoer:

{
  "jsonrpc":"2.0",
  "id":0,
  "method":"report.calculateReportAndEmail",
  "params":{
    "email":"aerius@example.com",
    "options":{
      "calculationType":"NBWET",
      "year":2015,
      "substances":["NOX","NH3"]
    },
    "proposed":[{
        "dataType":"GML",
        "contentType":"TEXT",
        "data":"<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?><imaer:FeatureCollectionCalculator ..."
    }]
  }
}

Gerelateerde factsheets

Factsheet

Factsheet
639-2924
Voor
  • Connect
Type
Algemeen