Handleiding API ter ondersteuning aangeboden door POM West-Vlaanderen en Provincie West-Vlaanderen versie 08/02/2013 Deze handleiding werd opgesteld door POM West-Vlaanderen & Provincie West-Vlaanderen en mag enkel voor de vooropgestelde doeleinden binnen het project worden gebruikt.
1. Hoe werkt de API? Globaal verloopt het proces van een data-aanvraag als volgt: de externe site maakt een actie; de actie wordt geëncrypteerd; de encryptie wordt samen met een API-sleutel doorgestuurd naar de Economische Kaart; het resultaat wordt teruggestuurd in XML-formaat. actie Geëncrypteerde XML Extern Economische Kaart Om de aanvragen toe te laten, hebben we bij aanvang het IP-adres en domeinnaam van de aanvrager nodig. Aan de hand van deze gegevens bouwt de Economische Kaart een API-sleutel en token (of digitale handtekening). Deze gegevens heeft u nodig om een aanvraag door te sturen. U kan een API-sleutel en een token aanvragen bij: Hannelore Simkens Tel.: 050/40 73 63 E-mail: hannelore.simkens@pomwvl.be Geef uw IP-adres en domeinnaam bij uw aanvraag. 2
2. Procedure Stap 1: actie De externe website heeft altijd toegang tot een vooraf gedefinieerd gedeelte van de website, bijvoorbeeld alle vestigingen van een gemeente. De actie wordt altijd beëindigd met het -teken. Bedrijfsgegevens opvragen Er zijn verschillende mogelijkheden om te filteren: Volledig De externe website kan de volledige lijst met vestigingen aanvragen via de filter 'volledig'. Via vestigingsnummer De externe website kan de gegevens opvragen van 1 vestiging via het vestigingsnummer. De filter is 'vestnr=2159772801'. Het vestigingsnummer is uniek voor elke vestiging. Via ondernemersnummer De externe website kan de gegevens opvragen via het ondernemersnummer. De filter is 'ondnr=0881702779'. Dit kan 1 of meerdere resultaten opleveren. Via activiteitnummer De externe website kan de gegevens opvragen via activiteitnummer. Men kan gebruik maken van de activiteitenlijst om het nummer te bepalen. De filter is 'activiteitnr=22'. Dit kan 1 of meerdere resultaten opleveren. Via activiteitnaam De externe website kan de gegevens opvragen via activiteit-omschrijving. Men kan gebruik maken van de activiteitenlijst. De filter is 'activiteit=restaurants'. Dit kan 1 of meerdere resultaten opleveren. Deze actie zoekt niet enkel in de activiteitnamen maar ook in de activiteitomschrijving (extra info) van een bedrijf. Activiteitenlijst opvragen U kan de volledige activiteitenlijst opvragen door de volgende actie door te sturen: 'activiteitenlijst'. 3
Stap 2: De actie encrypteren Om te verhinderen dat het voor iedereen leesbaar is, wordt de aanvraag niet vrij verstuurd. De actie (meestal een filter) moet versleuteld worden aan de hand van een digitale handtekening. Deze digitale handtekening of token wordt aangeleverd door de POM West-Vlaanderen. Voor de encryptie-functie is er een PHP-versie beschikbaar. De encryptie gebeurt aan de hand van een aangeleverde functie die jullie toevoegen in de website: encrypt([actie], [token]); Voorbeeld: encrypt('vestnr=2159772801 ', 'ditiseenvoorbeeldtoken') Resultaat van het voorbeeld: 6HMSyGD17zR2OvYeA6WPlEAHhhfRzXLalPNazTNlXbs%3D 4
Stap 3: Aanvraag doorsturen De geëncrypteerde actie wordt samen met de API-sleutel doorgestuurd op volgende manier: www.economischekaart.be/[gemeente]/api/request.php?api=[api sleutel]&actie=[geëncrypteerde actie ] Voorbeeld: www.economischekaart.be/brugge/api/request.php?api=mijnsleutel&actie=6hmsygd17zr2ovyea6wpleahh hfrzxlalpnaztnlxbs%3d Deze aanvraag moet verstuurd worden van op het aangeleverde IP en domein. 5
Stap 4: XML-data wordt teruggestuurd Aan de hand van de doorgestuurde actie worden de gegevens opgehaald. Dit kan 1 of meerdere vestigingen zijn. Formaat van de XML: <?xml version="1.0"?> <xml> <vestiging> <vestigingsnr>2159772801</vestigingsnr> <ondernemersnr>0881702779</ondernemersnr> <bedrijfsnaam>provinciale Ontwikkelingsmaatschappij West- Vlaanderen</bedrijfsnaam> <straat>koning Leopold III-Laan</straat> <huisnr>66</huisnr> <bisnr></bisnr> <busnr></busnr> <postcode>8200</postcode> <gemeente>brugge</gemeente> <tel>050 40 31 66</tel> <fax>050 71 94 06</fax> <email>pom@west-vlaanderen.be</email> <website>http://www.pomwvl.be</website> <activiteitomschrijving></activiteitomschrijving> <activiteit1nr>22</activiteit1nr> <activiteit1omschrijving>openbaar Bestuur</activiteit1omschrijving> <activiteit2nr></activiteit2nr> <activiteit2omschrijving></activiteit2omschrijving> <activiteit3nr></activiteit3nr> <activiteit3omschrijving></activiteit3omschrijving> <x>3.184015899119</x> <y>51.193284046287</y> <openingsuren></openingsuren> <openingsurenomschrijving></openingsurenomschrijving> <foto1>gemeentes/brugge/fotos/1279531067.jpg</foto1> <foto2></foto2> <foto3></foto3> <foto4></foto4> <foto5></foto5> </vestiging> </xml> Om de foto's op te halen plaatst u volgend adres voor het pad van foto 1 zodat u volgende URL hebt: http://www.economischekaart.be/brugge/gemeentes/brugge/fotos/1279531067.jpg 6