API documentatie
- Frank Wambacq
- Inge Borghmans
- jeroen.devlieghere
- Evelien Dheer
De beschikbare API’s
Het verenigingsregister kent 2 API’s voor externe afnemers:
De publieke API - Deze API biedt een subset van de verenigingsdata aan, enkel de gegevens die publieke mogen gemaakt worden. Met deze API kan je enkel data lezen, je kan hier niets mee aanpassen.
De Beheer API - Met deze API kan je alle gegevens ophalen uit het verenigingsregister, ook de beschermde. Deze API biedt zowel lees- als schrijf- mogelijkheden aan. Deze API wordt naar buiten gebracht als een MAGDA dienst.
Publieke API [voor iedereen]
Staging omgeving
Productie omgeving
Mogelijkheden
Zoeken naar een vereniging op basis van naam, postcode, gemeente..
De publiek beschikbare detailgegevens van een vereniging opvragen
Opvragen van de mogelijke waarden van codelijsten
Mutatiedienst voor het ondersteunen van lokale data synchronisatie
De publieke API bevat een selectie van de verenigingsgegevens uit het register. Je krijgt volgende gegevens/verenigingen niet te zien:
vertegenwoordigersgegevens (persoonsdata)
verenigingen die gestopt zijn
feitelijke verenigingen die zich “uitgeschreven” hebben uit de publieke datastroom
Toegang
Publiek beschikbaar maar een API Key is wel vereist voor publiek zoeken en publiek detail. Het ophalen van de mogelijke waarden en de API documentatie zijn vrij beschikbaar.
De API Key kan je aanvragen in onze CRM Toepassing. De API Key kan je gebruiken als request header vr-api-key of als parameter in de URL
Als request header
curl
--request GET
--url 'https://publiek.verenigingen.test-vlaanderen.be/v1/verenigingen/V0001001'
--header 'vr-api-key: api-key'Als Path parameter
GET <Publiek URL>/v1/verenigingen/<vCode>?vr-api-key=<apikey>Beheer API [voor instanties die toegang hebben tot alle gegevens en gegevens mogen bewerken]
De beheer API is beschikbaar via MAGDA. Gebruik onderstaande linken voor de MAGDA documentatie en voor het interesseformulier om aan te sluiten op het Verenigingsloket (met als bouwsteen het Verenigingsregister):
Mogelijkheden:
Registreren van een nieuwe vereniging
Wijzigen van de gegevens van een vereniging
Zoeken naar een vereniging op basis van naam, postcode, gemeente
Alle gegevens van een vereniging opvragen
Historiek opvragen van een vereniging
Gebruik van de Publieke API
vCode: formaat
De unieke identificatie van een vereniging is de vCode. Dit is een code die begint met de letter V (van Vereniging) gevolgd door 7 cijfers. Die cijfers hebben geen betekenis en worden gewoon sequentieel toegekend, startend vanaf 1001. Voorbeeld: V0001042.
Zoek opdrachten
De publieke API bevat een ZOEK functionaliteit. Deze zoek functionaliteit is een elastic search implementatie. De zoekcriteria kan je dus samenstellen zoals je bij elastic search zou doen. (zie algemene syntax) Hierbij enkele voorbeelden:
Query | Wat is het resultaat? |
|---|---|
q=* | Alle verenigingen in het verenigingsregister |
q=vereniging | Alle verenigingen die ergens de tekst vereniging in een zoekveld hebben staan. Dat kan in de naam zijn, maar evengoed in een ander veld dat beschikbaar is in de zoek resultaten |
q=naam:vereniging | Alle verenigingen die het woord vereniging in hun naam hebben. Het moet wel degelijk het volledige woord zijn dat er in zit: “Vereniging van zoekers” zal teruggevonden worden, maar “Zoekvereniging” niet. |
q=naam:*bal* | Alle verenigingen die ergens in hun naam het woord bal hebben. In dit geval kan het ook in het midden van het woord zitten. Zo zal ook de vereniging met naam “voetbalclub de sjotters” in de resultaten aanwezig zijn |
q=doelgroep.minimumleeftijd:<=16 | alle verenigingen die een waarde hebben in het veld |
q=naam:vereniging AND locaties.postcode:9000 | Je kan 2 criteria combineren met |
q=locaties.postcode:(1234 OR 5678) | Je kan filteren op verschillende mogelijke waarden door deze tussen haakjes te plaatsen en te scheiden door |
Codelijsten
Om deze functionaliteit te gebruiken, heb je geen API Key nodig.
Codelijsten = lijsten met mogelijke waarden voor een bepaald veld, kunnen opgevraagd worden via de publieke API. Het formaat van de API call = https://<publieke URL>/v1/<Code>, zoals bijvoorbeeld https://publiek.verenigingen.staging-vlaanderen.be/v1/hoofdactiviteitenVerenigingsloket. De codelijsten die je nu kan opvragen zijn:
Hoofdactiviteiten Verenigingsloket, code= hoofdactiviteitenVerenigingsloket
Werkingsgebieden, code = werkingsgebieden
Mutatiedienst
Als afnemer van de data van het verenigingsregister, kan je er voor kiezen om de data steeds rechtstreeks en real-time op te vragen. In sommige omstandigheden kan het echter beter uitkomen om de data ook lokaal te synchroniseren, naar een eigen CRM of databank bijvoorbeeld. Om de regelmatige synchronisatie van data te ondersteunen is er deze mutatiedienst. Deze geeft je immers aan welke verenigingen (vCodes) gewijzigd zijn sinds de laatste keer dat je de synchronisatie hebt uitgevoerd.
Om deze mutatiedienst te begrijpen, is het belangrijk om te weten dat elke wijziging in VR gebeurt op basis van gebeurtenissen (events). Elk event krijgt een uniek, oplopend nummer, genaamd sequence. Wanneer je lokaal synchroniseert, dan heb je alle wijzigingen mee tot een bepaalde sequence. Die moet je dan onthouden. Met de mutatiedienst kan je alle vCodes opvragen die gewijzigd zijn sinds die laatste sequence.
Voorbeeld:
Bij opstart neem je alle gegevens over en zoek je naar de hoogste sequence sinds dat moment. Dat kan je doen door deze API call:
GET <publiekURL>/v1/verenigingen/mutaties/sinds=0Deze call geeft je ALLE verenigingen weer samen met hun hoogste sequence. Voorbeeld:
Deze lijst is oplopend gesorteerd op sequence. De hoogste sequence is de allerlaatste in de rij. Onthou deze waarde als maxSequence. In dit voorbeeld is dat dus 34881.
Bij de volgende synchronisatie vraag je alle vCodes op die gewijzigd zijn sinds je vorige synchronisatie. Hierbij gebruik je maxSequence zoals je de vorige keer hebt opgeslagen.
Je krijgt nu de lijst van verenigingen waarvan de hoogste sequence strikt groter is dan 34881. Dat zijn dus de verenigingen die gewijzigd zijn sinds je laatste synchronisatie.
De mutatiedienst geeft enkel aan dat er IETS is gewijzigd aan die vCode, niet wat er juist is gewijzigd. Om dat te weten te komen, kan je 2 dingen doen:
de detail gegevens van de vereniging opvragen en vergelijken met de gegevens die je lokaal hebt gesynchroniseerd - opgelet: het kan zijn dat er gegevens zijn gewijzigd die je niet lokaal synchroniseert.
de historiek opvragen van de vereniging (enkel via MAGDA API op te vragen) - daar krijg je de lijst van alle wijzigingen, inclusief wie de wijziging geïnitieerd heeft en wanneer die uitgevoerd is.