Child pages
  • Postcode Service API handleiding BE

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.


Inhoudsopgave

Table of Contents

Inleiding

Deze handleiding beschrijft de functionaliteiten van de Postcode service API voor België en hoe u deze kunt gebruiken.

Contactgegevens TIG voor technische vragen

Wij kunnen het snelst reageren via ons ticketsysteem, stuur een e-mail naar:

servicedesk@tig.nl of gebruik deze link voor uitleg om via ons systeem een ticket aan te maken.

U kunt ook telefonisch uw vraag stelen via onze HQ in Amsterdam op 020 - 21 81 001 (directe technische ingang).

Installatie

Installatiestappen

De volgende gegevens zijn ter demo beschikbaar gesteld. Indien u uw eigen client_id en secure_code heeft ontvangen dient u deze te gebruiken. Mocht u niet in bezit zijn van deze gegevens dan kunt u deze bij TIG opvragen. Onderstaande gegevens kunnen gebruikt worden om de functionaliteit uit te proberen:

  • client_id = 1177
  • secure_code = 9SRLYBCALURPE2B

Deze gegevens bevatten wel een limiet. Zodra dit limiet bereikt is, is het nog wel mogelijk om een testaccount op te vragen. Neem contact op met TIG als u een test account wenst te ontvangen.

Verschillende endpoints

Er zijn twee verschillende manieren om gebruik te maken van onze Belgische Postcode service. De onefield methode en de twofield methode.

De onefield methode toont een auto-fill veld waar een straatnaam (deels) ingevuld kan worden. Deze wordt aangevuld met de resultaten vanuit onze API. Wanneer de gebruiker een straat selecteert wordt automatisch de postcode en plaats ingevuld.

De twofield methode toont twee auto-fill velden. Veld 1 verwacht een postcode óf gemeente. Deze wordt aangevuld wanneer de gebruiker een deel van zijn/haar postcode of gemeente intypt. Hierna wordt het tweede auto-fill veld zichtbaar. Hier kan de gebruiker zijn/haar straatnaam deels invullen en deze dan uit de dropdown selecteren.

Authenticatie

Authenticatie gaat met behulp van headers. De volgende headers dienen meegestuurd te worden met de call om een succesvolle aanroep te doen. Mochten de credentials invalide zijn of niet correct meegestuurd worden, dan toont de service een 401 Unauthorized error.

X-Client_Id1177
X-Secure_Code9SRLYBCALURPE2B
X-Domain (optioneel)https://tig.nl/

Onefield

JSON calls
Voorbeeld call:
https://postcode-be.tig.nl/api/be/v2/find?street=Koningin%20Maria%20Hen

Response success:

[{"label":"Koningin Maria Henriettelaan - Leopoldsburg","type":"Street","city":"Leopoldsburg","postcode":"3970","street":"Koningin Maria Henriettelaan"},
{"label":"Koningin Maria-Hendrikalaan - Vorst","type":"Street","city":"Vorst","postcode":"1190","street":"Koningin Maria-Hendrikalaan"},
{"label":"Koningin Maria Hendrikaplein - Gent","type":"Street","city":"Gent","postcode":"9000","street":"Koningin Maria Hendrikaplein"}]

Response failure:
{"result":false,"error":"Street not found"}

Voorbeeld PHP-bestand
Om de postcode service in uw omgeving te integreren is hier een eenvoudig voorbeeld in PHP weergeven:

Code Block
<?php
$client_id = 1177;
$secure_code = "9SRLYBCALURPE2B";
$straat = urlencode("Koningin Maria Hen");
/** Voor de authenticatie **/
$opts = [
    "http" => [
        "method" => "GET",
        "header" => "X-Secure_Code:" . $secure_code . "\r\n" .
            "X-Client_Id:" . $client_id . "\r\n" .
            "X-Domain:" . "https://tig.nl/"
    ]
];
$context = stream_context_create($opts);

$postcodePlaats =
file_get_contents("http://postcode-be.tig.nl/api/be/v2/find?street=$straat", false, $context);
						
header('Content-Type: application/json');
echo $postcodePlaats; 

Voorbeeld front-end code

Om de werking van onze postcode service uit te proberen kunt u het volgende bestand gebruiken:

View file
namepostcode-be.zip
height150

Twofield (BETA)

JSON calls
Voorbeeld call voor zipcode / gemeente veld:

(zipcodezone kan gebruikt worden voor een postcode óf gemeente/plaats)

https://postcode-be.tig.nl/api/be/v2/postcode-find?zipcodezone=1060

Response success:

[{"postcode":"1060","plaats":"Brussel"},
{"postcode":"1060","plaats":"Elsene"},
{"postcode":"1060","plaats":"Sint-gillis"},
{"postcode":"1060","plaats":"Ukkel"},
{"postcode":"1060","plaats":"Vorst"},
{"postcode":"1060","plaats":"Saint-Gilles"}]

Response failure:

[]

Voorbeeld call voor straat:

https://postcode-be.tig.nl/api/be/v2/street-find?zipcode=1060&city=Ukkel&street=Rue

Response success:

[{"straat":"Rue Camille Lemonnier"},
{"straat":"Rue Joseph Stallaert"}]

Response Failure:

[]

Voorbeeldcode

View file
namepostcode-be-
twofields
examples.zip
height150

Voorbeeld front-end code


Versioning van de API
Aanpassingen in de TIG API gaat volgens versioning. Nieuwe functionaliteiten in de API wordt beschikbaar gemaakt volgens onze versioning URI standaard:
https://postcode-be.tig.nl/api/{country}/{version}/{method}?parameters 

Bij elke API wijziging wordt dit nummer verhoogd. Nieuwe wijzigingen worden waar mogelijk altijd backward compatible uitgevoerd. Wanneer een script de postcode velden in een bepaalde volgorde verwacht, of maximaal een bepaald aantal velden, zal dit in de oude versie altijd ongewijzigd blijven. Hierdoor blijft het script zonder problemen werken.

Back-up
Wij adviseren u de installatie altijd eerst op een testomgeving uit te voeren en een back-up te maken van uw omgeving voor u begint.

Veelgestelde vragen

  • Is het mogelijk om meerdere servers gebruik te laten maken van de API?
    Ja, het is mogelijk om meerdere ip-addressen toe te voegen aan uw account voor eigen gebruik (zonder wederverkoop). Neem hiervoor contact op met de technische afdeling van TIG via servicedesk@tig.nl of per telefoon op 020 - 21 81 001.
  • Is het mogelijk om de database ook zelf in house te hebben en als back-up te gebruiken?
    Ja, neem hiervoor contact op met sales@tig.nl of per telefoon op 020 - 21 81 000.
  • Wat is het maximaal aantal requests dat ik naar de API kan uitvoeren?
    Dit is afhankelijk van uw contract, standaard is 10 requests / seconden. Neem telefonisch contact op met uw accountmanager op telefoonnummer 020 - 21 81 000.
  • Als ik ondersteuning nodig ehb, op welke tijdstippen kan ik TIG bereiken?
  • Het hele jaar door, 365/7/24, ook op feestdagen op telefoonnummer 020 - 21 81 001.

Technische vereisten

Om gebruik te maken van de postcode service API dient uw omgeving te voldoen aan de minimale technische verseisten:

  • Basiskennis JSON encoding/decoding.

Release notes

V 1.4.0

Authenticatie via headers, versioning, database improvements

V 1.3.0

Twofield methodes toegevoegd

V 1.2.1

Laravel update

V 1.1.0

Initiële release


knowledge-base-article-footer