referenceData-geography belgianCities

Overzicht

Service om de lijst van Belgische gemeenten te raadplegen beschikbaar in de drie landstalen

Wil je een Belgisch adres coderen en de gemeente en postcode valideren op basis van de onvolledige naam van de gemeente? Dan kan je de REST API referenceData/geography oproepen, vrij toegankelijk via het internet.

Functionele beschrijving

De REST-service referenceData/geography biedt, voor de resource belgianCities, volgende functionaliteiten:

• Verkrijgen van een lijst met alle Belgische gemeenten, hoofdgemeenten of niet-gefusioneerde gemeenten
• Verkrijgen van de Belgische gemeenten, hoofdgemeenten of niet-gefusioneerde gemeenten op basis van een - gedeeltelijke of volledige - naam van de gemeente
• Verkrijgen van de Belgische gemeenten, hoofdgemeenten of niet-gefusioneerde gemeenten op basis van een officiële - gedeeltelijke of volledige - postcode van de gemeente
• Verkrijgen van de Belgische gemeenten, hoofdgemeenten of niet-gefusioneerde gemeenten op basis van een officiële - gedeeltelijke of volledige - postcode en van een - gedeeltelijke of volledige - naam van de gemeente
• Verkrijgen van de Belgische gemeenten, hoofdgemeenten of niet-gefusioneerde gemeenten op basis van een gewestcode
• Verkrijgen van de Belgische gemeenten, hoofdgemeenten of niet-gefusioneerde gemeenten op basis van een taalkundige gewestcode
• Verkrijgen van de Belgische gemeenten, hoofdgemeenten of niet-gefusioneerde gemeenten op basis van de NIS-code van de hoofdgemeente

Opmerking: om alleen de actieve gemeenten te verkrijgen, moet je de parameter einddatum van geldigheid opgeven die groter of gelijk is aan de datum van vandaag. Voorbeeld: '?validityEndDate.gte=AAAAMMJJ '

Voor elke Belgische gemeente kan men volgende gegevens verkrijgen:

• NIS-code van de gemeente, als het om een hoofdgemeente gaat
• Officiële Belgische postcode van de gemeente
• Naam van de gemeente, hoofdgemeente of niet-gefusioneerde gemeente, in de drie landstalen Nederlands (= NL), Frans (= FR) en Duits (= DE)
• Het taalregime van de gemeente F, FN, FD, N, NF, DF, FN_NF en NF_FN, waarbij F = Frans, N = Nederlands, D = Duits, FN_NF en NF_FN = tweetalig en FN, FD, NF, DF = faciliteitengemeenten
• De gewestcode BRU (= Brussel Hoofdstedelijk gewest), VLG (= Vlaams gewest) en WAL (= Waals gewest)
• De taalkundige gewestcode NL, FR, DE en BIL (= tweetalig)
• Begindatum van geldigheid
• Einddatum van geldigheid
• De link naar de technische identificatie van de bijbehorende hoofdgemeente, als de gemeente geen hoofdgemeente is
• De link naar technische identificatie

Gezien de REST-service referenceData/geography, voor de resource belgianCities, op de postcodes van de Belgische post gebaseerd is, komen bepaalde codes niet overeen met een gemeente.
Bijvoorbeeld: 1012 = Parlement van de Franse Gemeenschap.

Merk anderzijds op dat

• bepaalde speciale gemeenten geen NIS-code hebben, bijv. Brussel X, Brussel NAVO...
• bij elke niet-gefusioneerde gemeente een hoofdgemeente hoort
• de lijst beperkt wordt tot de hoofdgemeenten door de parameter isMainCity=true toe te passen

Hoewel de service de naam van een gemeente in de drie talen aanbiedt, is het aan te raden de naam van een gemeente uitsluitend in haar taalregime te gebruiken.
Bijvoorbeeld: Antwerpen en niet Anvers, Liège en niet Luik.

Technische beschrijving

Non-securised REST API beschikbaar op het internet.

Doelpubliek

Elke toepassing die Belgische adressen verwerkt en die een postcode, een NIS-code van een gemeente of geldigheidsdata van Belgische gemeenten vereist.

Opmerkingen:

• In het kader van het project BElgian STreets address worden vanaf heden de authentieke bronnen van de adressen beheerd door de gewesten. FOD Beleid en Ondersteuning (Bosa) stelt SOAP- en REST-services ter beschikking voor de consultatie van gemeenten, straten en adressen.
• De REST-API referenceData/geography belgianCities echter is gebaseerd op de gegevens verkregen vanuit het Nationaal Register (en KSZ), waar we enkele verschillen met de authentieke bron van de adressen hebben kunnen noteren. Van zodra deze verschillen zullen opgelost zijn zullen wij deze API hier opheffen.
• De REST-API referenceData/geography belgianCities omvat ook de resources 'countries' en 'belgianStreets', maar deze laatste is sinds 28 maart 2021 niet meer bijgewerkt en dus verouderd.

Integratievoorwaarden

Er zijn geen bijzondere integratievoorwaarden, gezien de service niet beveiligd is.

Voor Angular-toepassingen dient men echter de URL van de toepassing door te sturen om de toegang tot de service te configureren.

Documentatie

• Bosa: documentatie BEST address services
• Swagger file
• Functionele documentatie

Contact

Contact: ReuseOperational@smals.be