referenceData-geography countries

Overzicht

Service om de lijst met landen te raadplegen beschikbaar in vier talen (NL, FR, DE en EN)

Wil je een adres coderen door het land en de ISO-code te valideren op basis van de onvolledige naam van het land? Dan kan je hiertoe de referenceData/geography REST API oproepen die gratis toegankelijk is via het internet.

Functionele beschrijving

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

• Verkrijgen van de gegevens van een land op basis van de NIS-code van dit land
• Verkrijgen van de lijst met landen of een selectie hiervan op basis van zoekcriteria

Voor elk land kan men de volgende informatie verkrijgen:

• NIS-landencode
• Naam van het land in vier talen (NL, FR, DE en EN)
• Code van het land in twee letters (norm ISO-3166-1), aanbevolen om een adres te specificeren
• Code van het land in drie letters (norm ISO-3166-1), aanbevolen om een nationaliteit te specificeren
• Code van het land in maximaal drie cijfers (norm ISO-3166-1), nuttig om de landen te identificeren die geen Latijns alfabet gebruiken
• Status: actief of niet-actief (naargelang de einddatum van de geldigheid later of vroeger valt dan de huidige datum)
• Naam van de inwoners in vier talen (NL, FR, DE en EN)
• Begindatum van de geldigheid
• Einddatum van de geldigheid

Gezien de REST-service referenceData/geography voor de resource countries gebaseerd is op de NIS-codes van landen, kunnen bepaalde grondgebieden, hoewel ze een ISO-code hebben, niet geconsulteerd worden via deze service, omdat ze geen NIS-landencode hebben.
Voorbeelden: Faeröereilanden, Jersey, Mayotte...

Anderzijds merken we op dat

• bepaalde NIS-codes geen bijbehorende ISO-code hebben:
  Tsjecho-Slowakije, Kosovo, Jeruzalem, NAVO, SHAPE, Apatride...
• bepaalde landen geen eigen ISO-code hebben, maar diegene van het land waartoe ze behoren:
  Canarische eilanden (ESP), Madeira (P)...
• bepaalde entiteiten een eigen ISO-code hebben die verschilt van het hoofdland:
  Guadeloupe (GP) en Martinique (MQ) hebben niet de ISO-code van Frankrijk (FR)
• de naam van een inwoner van een land in het mannelijk enkelvoud wordt gegeven:
  Fransman, Spanjaard, Belg, Guadelouper, Groenlander...
• de naam van een inwoner van een land niet overeenkomt met zijn nationaliteit gezien deze laatste niet verschaft wordt door deze service:
  een Guadelouper heeft de Franse nationaliteit, een Groenlander heeft de Deense nationaliteit
• bepaalde NIS-codes aangemaakt werden om te beantwoorden aan businessbehoeften:
  ’Apatride’, ‘Nog niet definitief vastgelegd’, ’Afgevoerd voor het buitenland’, ‘Op zee’, ‘Onbepaald’, ‘van oorsprong’, ’Vluchteling’, ’Onbepaald’, ‘SHAPE’ en 'NAVO'

Technische beschrijving

Non-securised REST API beschikbaar op het internet.

Doelpubliek

Elke toepassing die internationale adressen verwerkt en die een NIS-code, een landencode volgens de norm ISO-3166-1 en/of geldigheidsdata van landen vereist.

Opmerkingen:

• Er bestaat een authentieke bron van landcodes onder toezicht van FOD Buitenlandse Zaken, gezamenlijk beheerd door FOD Economie en BOSA DT, die beschikt over een gebruikerscomité, en een structuur en procedures voor 'governance'.
  FOD Beleid en Ondersteuning (BOSA) biedt de SOAP-service Country aan om deze authentieke bron van landcodes te consulteren. In dat geval dient u rechtstreeks met hen contact op te nemen via de site Statbel.
  
  De REST-API referenceData/geography countries echter is gebaseerd op de gegevens verkregen vanuit het Nationaal Register (en KSZ), waar we enkele verschillen met de authentieke bron van de landencodes hebben kunnen noteren. Van zodra deze verschillen zullen opgelost zijn, en BOSA een REST-API Country zal aanbieden, zullen wij deze API hier opheffen.
   
• De REST-API referenceData/geography countries omvat ook de resources 'belgianCities' 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 zal men echter de URL van de toepassing dienen door te sturen om de toegang tot de service te configureren.

Documentatie

• Functionele documentatie
• Lijst met landencodes norm ISO-3166-1
• BOSA: authentieke bron landencodes REST Country-service
• Swagger file

Contact

Contact: ReuseOperational@smals.be