referenceData-geography countries

Aperçu

Service qui permet de consulter la liste des pays disponibles en quatre langues (FR, NL, DE et EN)

Vous voulez encoder une adresse en validant le pays et son code ISO à partir d'un nom incomplet du pays alors vous pouvez appeler l'API REST referenceData/geography, accessible librement depuis internet.

Description fonctionnelle

Le service REST referenceData/geography offre, pour la ressource countries, les fonctionnalités suivantes :

• Obtenir les données d'un pays sur base du code INS de ce pays
• Obtenir la liste des pays ou une sélection de ceux-ci basée sur des critères de recherche

Pour chaque pays, on peut avoir les informations suivantes :

• Code INS du pays
• Nom du pays en 4 langues (FR, NL, DE et EN)
• Code du pays en 2 lettres (norme ISO-3166-1), conseillé pour spécifier une adresse
• Code du pays en 3 lettres (norme ISO-3166-1), conseillé pour spécifier une nationalité
• Code du pays en 3 chiffres maximum (norme ISO-3166-1), utile pour identifier les pays n'utilisant pas l'alphabet latin
• Statut: actif ou pas (selon que la date de fin de validité est supérieure ou inférieure à la date du jour)
• Nom des habitants en 4 langues (FR, NL, DE et EN)
• Date de début de validité
• Date de fin de validité

Ce service REST referenceData/geography, pour la ressource countries, étant basé sur les codes INS des pays, certains territoires, bien qu’ils aient un code ISO, ne sont pas repris dans ce service car ils n’ont pas de code INS de pays.
Exemples : Iles Feroé, Jersey, Mayotte…

D’autre part, nous remarquerons que

• certains codes INS n'ont pas de code ISO correspondant :
  Tchécoslovaquie, Kosovo, Jerusalem, OTAN, SHAPE, Apatride…
• certains pays n’ont pas de code ISO propre mais ont celui du pays auquel ils sont l’entité :
  Iles Canaries (ESP), Madère (P)...
• certaines entités ont un code ISO propre, différent du pays principal :
  La Guadeloupe (GP) et La Martinique (MQ) n'ont pas le code ISO de la France (FR)
• le nom des habitants d’un pays est donné au masculin singulier :
  Français, Espagnol, Belge, Guadeloupéen, Groenlandais…
• le nom des habitants d’un pays ne correspond pas à leur nationalité, cette dernière n'est pas fournie par ce service :
  un Guadeloupéen a la nationalité française, un Groenlandais a la nationalité danoise
• certains codes INS ont été créés pour satisfaire des besoins business :
  'Apatride', 'Pas encore définitivement établi', 'Rayé pour l'étranger', 'En mer', 'Indéterminé', 'd'origine', 'Réfugié', 'Indéterminé', 'SHAPE' et 'OTAN'

Description technique

API REST non sécurisée disponible sur internet.

Public cible

Toute application qui traite des adresses internationales et qui nécessite un code INS, un code pays selon la norme ISO-3166-1 et/ou des dates de validité des pays.

Remarques : 

• Il existe une source authentique des codes pays, sous la tutelle du SPF Affaires étrangères, cogérée par le SPF Économie et BOSA DT, et disposant d'un comité d’utilisateurs, d'une structure de gouvernance et de procédures de gouvernance.
  Le SPF Stratégie et Appui (BOSA) offre le service SOAP Country pour consulter cette source authentique des codes pays.
  Dans ce cas, il faut prendre contact directement avec eux via le site Statbel.
  
  L'API REST referenceData/geography countries est quant à elle basée sur les données issues du Registre National (et BCSS), où nous avons pu noter quelques données différentes avec la source authentique des codes pays. Dès que ces différences seront résorbées, et que BOSA offrira une API REST de Country, nous déprécierons cet API ci.
   
• L'API REST referenceData/geography countries offre aussi les ressources 'belgianCities' et 'belgianStreets', mais cette dernière ressource est dépréciée et n'est plus mise à jour depuis le 28 mars 2021.

Conditions d'intégration

Le service n’étant pas sécurisé, il n’y a pas de conditions d’intégration particulières.

Cependant pour les applications Angular il faudra transmettre l'URL de l'application afin de configurer son accès au service.

Documentation

• Documentation fonctionnelle
• Liste des codes pays norme ISO-3166-1
• BOSA : API REST Country sur la source authentique des codes pays
• Fichier Swagger

Contact

Contact : ReuseOperational@smals.be