Hoe werkt een API en hoe kun je de reisafstanden API gebruiken in een declaratieformulier of hoe bouw je je eigen online tool?
In dit artikel leg ik stap voor stap uit hoe het werkt en hoe je zoiets bouwt. En om tijd te besparen of als je je niet wilt verdiepen hoe het werkt, kun je de code ook direct downloaden en installeren zonder technische kennis.
API staat voor Application Programming interface. Oftewel een manier om informatie tussen twee applicaties of systemen uit te wisselen. Hoewel veel applicaties een ander doel hebben of anders geprogrammeerd zijn, zijn er een paar universele programmeertechnieken om gegevens uit te wisselen tussen verschillende applicaties. De meest voorkomende applicaties zijn websites. Iedere website kun je beschouwen als een aparte applicatie. Hoewel de reisafstanden.nl API ook voor andere applicaties geschikt is, ga ik in dit artikel een koppeling leggen tussen een website en de API van reisafstanden.nl.
Uiteraard weet je wat een website is. Maar om de API te begrijpen moet je even beseffen hoe een website is opgebouwd. Een website bestaat uit 3 onderdelen. De structuur, de opmaak en de interactiemogelijkheden. Allemaal is het gewoon tekst, maar als dit tekstbestand wordt geopend in een browser en wordt herkend als webpagina, maakt de browser ze op als webpagina zoals je gewend bent.
De structuur is opgebouwd in zogeheten HTML. Wellicht herken je dat van bestanden met als laatste deel .html in plaats van .txt of .docx of .xlsx (voor tekst, MS Word en MS Excel bestanden).
De opmaak heet de Style. Dat kan in aparte bestanden staan, maar kan ook in een .html-bestand zijn opgenomen.
De interactie heet het Script. Ook dit kan in een apart bestand worden opgenomen maar ook in het .html-bestand staan.
Om het eindresultaat straks eenvoudig downloadbaar te maken, zal ik het nu allemaal in 1 document plaatsen.
We gaan een webpagina maken met een titel, een formulier waar iemand een postcode en huisnummer kan invoeren voor het beginadres en een postcode en huisnummer met het eindadres. Daarnaast komt er een knop waarop de gebruiker kan klikken om de route op te zoeken en uiteraard wordt de uitkomst weergegeven.
We beginnen bij het opmaken van een .html-bestand. Open een programma om tekstbestanden mee te bewerken. Dit kan in programma’s speciaal voor coderen als Visual Studio, Sublime Text en Notepad++, maar kan ook gewoon in je kladblok in windows of teksteditor op je macbook.
De standaard tegenwoordig is HTML5 en de basis om mee te beginnen is als volgt:
<!DOCTYPE html>
<html>
<head>
</head>
<body>
</body>
</html>
De termen die je zit staan zijn ’tags’. We gaan zo inhoud met andere tags toevoegen tussen de head-tags en de body-tags. In de body komt de structuur van de pagina. In de head komt de style en in ons geval ook de scripts. Een tag heeft meestal een openende tag (<body>) en een afsluitende tag (</body>) met de slash (/) voor het woord.
Als je webpagina geopend hebt staat op het tabblad in de browser de titel van de webpagina. Deze voeg je toe in de head tussen twee ’title’-tags. Als volgt:
<head>
<title>reisafstanden.nl declaratieformulier</title>
</head>
Ook willen we op de pagina zelf beginnen met een titel. Deze plaats je in de body met een ‘h3’-tag. (h1 en h2 kunnen ook, maar die zijn iets groter). Dit doe je als volgt:
<body>
<h3>reisafstanden.nl declaratieformulier</h3>
</body>
Sla het bestand nu op als declaratie.html. Wanneer je in de verkenner dit bestand opent, zal automatisch een browser worden geopend en kun je je nieuwe pagina zien.
Zoals gezegd willen we de mogelijkheid om postcodes en huisnummers van het begin- en eindpunt in te vullen. Hiervoor gebruiken we het ‘input’ tag voor. Een input tag heeft in tegenstelling tot de meeste tags geen afsluitende tag.
Om 4 invulmogelijkheden te hebben, voegen we 4 input-tags toe. Zoals volgt:
<body>
<h3>reisafstanden.nl declaratieformulier</h3>
<input>
<input>
<input>
<input>
</body>
Wanneer je het bestand nu opslaat en de webpagina opnieuw bekijkt zie je dat er 4 invulvelden zijn toegevoegd. Dit is alleen voor een gebruiker nog niet overzichtelijk.
Een eenvoudige manier om de pagina intuïtiever te maken voor de gebruiker is om een ‘placeholder’-attribuut toe te voegen in de input-tags. Een attribuut is informatie dat je meegeeft aan een tag waarmee de browser kan omgaan of je later in je script kan gebruiken. Het placeholder-attribuut in een input-tag geeft de tekst weer die moet worden weergegeven als er niets is ingevuld in het invulveld en deze ook niet geselecteerd is. In ons geval gebruiken we dit als volgt:
<body>
<h3>reisafstanden.nl declaratieformulier</h3>
<input placeholder="Postcode">
<input placeholder="Huisnummer">
<input placeholder="Postcode">
<input placeholder="Huisnummer">
</body>
Om straks in het script te kunnen bepalen wat het startadres is en wat het eindadres voegen we het id-attribuut toe aan de verschillende input-tags. Een ‘id’ is een naam waarmee we tags kunnen identificeren.
Als volgt:
<body>
<h3>reisafstanden.nl declaratieformulier</h3>
<input id="startpc" placeholder="Postcode">
<input id="startnr" placeholder="Huisnummer">
<input id="eindpc" placeholder="Postcode">
<input id="eindnr" placeholder="Huisnummer">
</body>
Voor nog een betere opmaak voegen we labels toe en splitsen we wat regels op. Hiervoor gebruiken we de label-tag en de br-tag (<br> staat voor ‘break’). De label-tag voegen we nu alleen toe aan de postcodes, omdat we de postcode en het huisnummer op dezelfde regel laten staan. Het wordt dan als volgt:
<body>
<h3>reisafstanden.nl declaratieformulier</h3>
<label for="startpc">Vertrek</label>
<br>
<input id="startpc" placeholder="Postcode">
<input id="startnr" placeholder="Huisnummer">
<br>
<label for="eindpc">Aankomst</label>
<br>
<input id="eindpc" placeholder="Postcode">
<input id="eindnr" placeholder="Huisnummer">
</body>
Dan hebben we nog een knop nodig om de opdracht te activeren. Hiervoor voegen we een button-tag toe. Deze knop geven de het onclick-attribuut mee. Dit attribuut geeft aan welk script moet worden gestart als er op de knop geklikt wordt. Dit script bouwen we zo. Het ziet er dan als volgt uit:
<body>
<h3>reisafstanden.nl declaratieformulier</h3>
<label for="startpc">Vertrek</label><br>
<input id="startpc" placeholder="Postcode">
<input id="startnr" placeholder="Huisnummer">
<br>
<label for="eindpc">Aankomst</label><br>
<input id="eindpc" placeholder="Postcode">
<input id="eindnr" placeholder="Huisnummer">
<br><br>
<button onclick="verstuur()">Verstuur</button>
</body>
De structuur staat nu en we hebben een knop waarop kan worden gedrukt. Als dat wordt gedaan, wordt de functie ‘verstuur()’ gestart. Deze functie komt te staan in het script. Deze gaan we zo maken. Eerst een hele korte introductie van het script.
De basis
Een script voeg je toe met een script tag. Dit script voeg ik in dit geval voor een verbeterd overzicht toe aan de head, maar in sommige gevallen is het beter om dit onderaan de body toe te voegen. Voor de uitvoering van het script maakt dit echter niets uit.
Je kunt verschillende soorten script hier toevoegen, zoals visual basic en javascript. De meest gebruikte vorm in webpagina’s op dit moment is javascript, dus dat is wat wij ook gaan doen.
Een voorbeeld wat je met een script kunt doen is een pop-up bericht wanneer iemand ergens op drukt. Je kunt een script direct starten als de pagina wordt geladen of alleen iets starten wanneer een gebruiker op een knop drukt of een andere actie uitvoert. Voor dit laatste, plaats je het script in een functie (function) zodat je dit kunt aanroepen. Als we bijvoorbeeld in de functie ‘verstuur()’ de pop-up met een bericht willen toevoegen ziet dat er als volgt uit.
<head>
<title>reisafstanden declaratieformulier</title>
<script>
function verstuur(){
alert('dit is een bericht')
}
</script>
</head>
Hulp
Nu is het zo dat niet alle scripts even goed in alle verschillende browsers werken. Daarnaast zijn sommige scripts best complex te lezen en te maken. Om deze twee zaken te vergemakkelijken hebben programmeurs bibliotheken gemaakt met heel veel functies, die veel complexiteit van je overnemen. Eén van de meest gebruikte bibliotheken is Jquery. Om gebruik te maken van deze functies voeg je een script-tag toe met een src (source)-attribuut. In dit attribuut geef je de url op van waar het script staat. Dit kan een eigen bestandje zijn dat op je eigen computer is opgeslagen, maar kan ook een script zijn van internet. Dat laatste gaan we doen. Om zo de API van reisafstanden.nl eenvoudiger aan te roepen gaan we de bibliotheek van Jquery toevoegen vanuit de website code.jquery.com. Dat ziet er dan als volgt uit:
<head>
<title>reisafstanden declaratieformulier</title>
<script src="https://code.jquery.com/jquery-3.4.1.min.js"></script>
<script>
function verstuur(){
alert('dit is een bericht')
}
</script>
</head>
Om via de API een berekening op te vragen moeten we uiteraard de postcodes en huisnummers meegeven. We gaan nu de functie verstuur() aanpassen zodat deze gegevens in variabelen worden geplaatst. Variabelen zijn namen waaraan je waarden kunt toekennen. Zo noemen we ‘startpc’ de postcode van het startpunt, ‘startnr’ is het huisnummer van het startpunt en we gebruiken ook ‘eindpc’ en ‘eindnr’. Omdat we de input-tags ook het id-attribuut hebben meegegeven, kunnen we de waarden eenvoudig ophalen. Gebruik makend van de functies van jquery ziet dat er als volgt uit:
<script>
function verstuur(){
startPc = $('#startpc').val()
eindPc = $('#eindpc').val()
startNr = $('#startnr').val()
eindNr = $('#eindnr').val()
}
</script>
Een korte uitleg over het script.
Om te controleren of de waardes die je hebt ingevuld in de invulvelden daadwerkelijk zo worden opgehaald laten we ze even in een zin tonen in een pop-up bericht. Tekst en waarden voeg je toe met een + teken. Dit ziet er dan als volgt uit (let op, alles is hoofdlettergevoelig):
<script>
function verstuur(){
startPc = $('#startpc').val()
eindPc = $('#eindpc').val()
startNr = $('#startpc').val()
eindNr = $('#eindnr').val()
alert('het startpunt is ' + startPc + ' ' + startNr + ' en het eindpunt is ' + eindPc + ' ' + eindNr)
}
</script>
Om het even heel simpel te zeggen, de API van reisafstanden.nl is gewoon een webpagina. Als je de juiste url hebt en deze opent in de browser ontvang je alle informatie.
De URL in de simpelste vorm is als volgt opgebouwd:
https://www.reisafstanden.nl/API/?contenttype=json&token=12345678abcdefghijk&startpc=1234VB&startnr=12&eindpc=9988XX&eindnr=56
Een korte uitleg
https://www.reisafstanden.nl/API/? Is het begin van de url en is bij iedere aanroep altijd gelijk.
Met de contenttype geef je aan op welke manier je de informatie wilt ontvangen. Je hebt hier de opties voor XML, json, jsonp of credits. Json staat voor JavaScript Object Notation. Omdat we gebruik maken van javascript is dit in ons geval de keuze. Meer informatie over de andere opties vind je terug in de documentatie.
De token heb je nodig om gebruik te kunnen maken van de API en deze ontvang je wanneer je een account hebt aangemaakt en vind je terug bij je account gegevens.
De startpc,startnr,eindpc en eindnr zijn de postcodes en huisnummers.
Bouw de url op
We hebben net de postcode en huisnummergegevens opgehaald uit de invulvelden, dus is het nu tijd om deze gegevens niet in een pop-up te tonen, maar om de url op te bouwen. Dit doen we op dezelfde manier als we net het bericht in de popup hebben opgebouwnd. Tekst aan elkaar plakken met een +. Dat ziet er dan zo uit:
function verstuur(){
startPc = $('#startpc').val()
eindPc = $('#eindpc').val()
startNr = $('#startnr').val()
eindNr = $('#eindnr').val()
token = '12345678abcdefghijk'
url = 'https://www.reisafstanden.nl/API/?contenttype=json&token=' + token + '&startpc=' + startPc + '&startnr=' + startNr + '&eindpc=' + eindPc + '&eindnr=' + eindNr
alert('de url is ' + url)
}
Disclaimer
De code die hier getoond wordt is altijd in te zien door de gebruiker. Wees dus voorzichtig met het plaatsen van zo’n token in de code. Dit kan uiteraard als het een interne website is, waar niemand anders bij kan, of je kunt de code eerst via een andere API eerst ophalen met bijvoorbeeld autorisatie. Mocht dit laatste te complex worden en wil je toch meerdere mensen toegang geven tot deze website, kan reisafstanden.nl ook de token voor jou koppelen aan een IP-adres of aan een domein (bijvoorbeeld: www.bedrijfA.nl). Zodat de token alleen vanuit hier gebruikt kan worden. Mocht je token dan gekopieerd worden, is het niet te gebruiken.
Gebruik maken van de API
Nu komt de magie ;-). Je hoeft niet in je browser naar de nieuw opgebouwde url te gaan om de gegevens van de website op te halen. Dat doen we door een script. We gaan ook nu gebruik maken van de eenvoud van jquery. We roepen een GET-functie aan naar de url en we ontvangen dan informatie terug. Deze informatie stoppen we in een functie om er iets mee te doen. Voor nu is de actie om de informatie eerst weer in een pop-up bericht om te zien of het werkt. De code ziet er dan als volgt uit:
function verstuur(){
startPc = $('#startpc').val()
eindPc = $('#eindpc').val()
startNr = $('#startnr').val()
eindNr = $('#eindnr').val()
token = '12345678abcdefghijk'
url = 'https://www.reisafstanden.nl/API/?contenttype=json&token=' + token + '&startpc=' + startPc + '&startnr=' + startNr + '&eindpc=' + eindPc + '&eindnr=' + eindNr
$.get(url,function(antwoord){
alert(antwoord)
})
}
Wanneer je een juiste token en correcte postcodes hebt ingevoerd ziet het antwoord er (wanneer je het ordent) ongeveer als volgt uit:
{
"versie": "1.7.0",
"startpc": "1234VB",
"startnr": "12",
"eindpc": "9988XX",
"eindnr": "56",
"startCoordinaten": "52.1309408,5.1917055",
"eindCoordinaten": "51.6617124,5.6321956",
"respons": 200,
"reistijdSeconden": 3605,
"afstandMeters": 84843,
"pontInRoute": 0,
"disclaimer": "Opgevraagde routes worden op eigen risico aangewend. Reisafstanden.nl is nimmer aansprakelijk voor schade in verband met het gebruik van de data.",
"responsText": "Succes"
}
Het antwoord dat je hebt ontvangen is tekst en het is lastig om hier de waardes uit op te halen. Gelukkig is het antwoord in Javascript Object Notation (JSON) geschreven. Wat maakt dat we er eenvoudig de tekst om kunnen zetten (Parse) naar een object die we daarna eenvoudig kunnen uitlezen.
Om snel de ‘afstand in meters’ te tonen voegen we het volgende toe:
function verstuur(){
startPc = $('#startpc').val()
eindPc = $('#eindpc').val()
startNr = $('#startnr').val()
eindNr = $('#eindnr').val()
token = '12345678abcdefghijk'
url = 'https://www.reisafstanden.nl/API/?contenttype=json&token=' + token + '&startpc=' + startPc + '&startnr=' + startNr + '&eindpc=' + eindPc + '&eindnr=' + eindNr
$.get(url,function(antwoord){
routeObject = JSON.parse(antwoord)
alert(routeObject.afstandMeters)
})
}
Nu willen we natuurlijk antwoord niet in een pop-up bericht, maar gewoon ergens op het scherm. Hiervoor bouwen we eerst weer in de body van het bestand een tabel, waar de gegevens in kunnen worden getoond. Deze tabel plaatsen we onder de knop en gesplitst met een streep. Dit gaat zo:
<body>
<h3>reisafstanden.nl declaratieformulier</h3>
<label for="startpc">Vertrek</label><br>
<input id="startpc" placeholder="Postcode">
<input id="startnr" placeholder="Huisnummer">
<br>
<label for="eindpc">Aankomst</label><br>
<input id="eindpc" placeholder="Postcode">
<input id="eindnr" placeholder="Huisnummer">
<br><br>
<button onclick="verstuur()">Verstuur</button>
<hr>
<h3>Het resultaat</h3>
<table>
<tr>
<td>Afstand</td>
<td id="afstand"></td>
</tr>
<tr>
<td>Reistijd</td>
<td id="tijd"></td>
</tr>
</table>
</body>
Korte uitleg
Zoals je ziet heb ik twee td-tags een id-attribuut gegeven. Zo kunnen we de informatie daar eenvoudig in plaatsen. Dat doen we als volgt:
function verstuur(){
startPc = $('#startpc').val()
eindPc = $('#eindpc').val()
startNr = $('#startnr').val()
eindNr = $('#eindnr').val()
token = '12345678abcdefghijk'
url = 'https://www.reisafstanden.nl/API/?contenttype=json&token=' + token + '&startpc=' + startPc + '&startnr=' + startNr + '&eindpc=' + eindPc + '&eindnr=' + eindNr
$.get(url,function(antwoord){
routeObject = JSON.parse(antwoord)
$('#afstand').html(routeObject.afstandMeters)
$('#tijd').html(routeObject.reistijdSeconden)
})
}
We zijn er bijna qua berekening. Hoewel meters misschien nog eenvoudig in je hoofd om te zetten is naar Kilometers, is dat bij seconden wat lastiger. Dus voor het gebruikersgemak rekenen we het eerst om voordat we het tonen. Het volgende:
function verstuur(){
startPc = $('#startpc').val()
eindPc = $('#eindpc').val()
startNr = $('#startnr').val()
eindNr = $('#eindnr').val()
token = '12345678abcdefghijk'
url = 'https://www.reisafstanden.nl/API/?contenttype=json&token=' + token + '&startpc=' + startPc + '&startnr=' + startNr + '&eindpc=' + eindPc + '&eindnr=' + eindNr
$.get(url,function(antwoord){
routeObject = JSON.parse(antwoord)
kilometers = (routeObject.afstandMeters/1000).toFixed(1) + ' KM'
tijdInMinuten = (routeObject.reistijdSeconden/60).toFixed(1) + ' minuten'
$('#afstand').html(kilometers)
$('#tijd').html(tijdInMinuten)
})
}
Korte uitleg
We delen de afstandin Meters door 1000, ronden het af naar 1 cijfer achter de komma (toFixed) en zetten er weer een tekst “KM” achter.
Hetzelfde geldt voor de tijd in minuten, maar dan delen we door 60.
Voila!
Een werkende API. Het ziet er nog niet zo mooi uit, maar het werkt en je kunt het op alle manieren die je wilt vormgeven.
Je kunt het volledige script ook hier downloaden. De opmaak heb ik hierin al sterk verbeterd door gebruik te maken van styling en van de style library Bootstrap. Het principe van Bootstrap is hetzelfde als Jquery, maar dan vooral gericht op styling.
Mocht je vragen hebben, of wil je hulp bij het bouwen van je eigen Reisafstanden.nl API, neem gerust contact op. Wil je zelf aan de slag met nog meer mogelijkheden, bekijk dan hier de documentatie.
Succes!