API Adresse — Autocomplétion par code postal (Classic)

Support DQE
Support DQE
  • Mise à jour
Autocomplétion en entonnoir - API Standard

Autocomplétion d'adresse en trois étapes utilisant l'API classique. CP trouve les villes correspondantes à partir d'un code postal ou d'un nom de ville ; ADR retourne les voies de la ville sélectionnée ; COMPL récupère les options de sous-bâtiment après sélection de la voie.

Casse de sortie - La casse suit la norme postale du pays concerné.

Recherche de ville (CP)

Première étape de l'approche en entonnoir. Retourne les villes et codes postaux correspondants à partir d'un code postal partiel ou d'un nom de ville. L'IDLocalite de chaque résultat alimente l'étape suivante : ADR.

Requête

CP prend en charge à la fois GET et POST.

{SERVER_ADDRESS} et {LICENCE_CODE} sont fournis par DQE lors de la création du compte. Contactez votre chargé de compte DQE pour obtenir ces identifiants.
GEThttps://{SERVER_ADDRESS}/CP/?CodePostal={POSTAL_CODE}&Alpha=True&Pays={COUNTRY_CODE}&Licence={LICENCE_CODE}

Exemple cURL

France - Recherche par code postal

curl "https://{SERVER_ADDRESS}/CP/?CodePostal=75008&Alpha=True&Pays=FRA&Licence={LICENCE_CODE}"
POSThttps://{SERVER_ADDRESS}/CP/

Envoyez tous les paramètres dans le corps de la requête avec Content-Type: application/x-www-form-urlencoded. L'adresse du serveur reste dans l'URL.

Exemple cURL

curl -X POST "https://{SERVER_ADDRESS}/CP/" \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "CodePostal=75008" \ -d "Alpha=True" \ -d "Pays=FRA" \ -d "Licence={LICENCE_CODE}"

Paramètres

Paramètre Valeur Description Obl. / Opt.
Licence {LICENCE_CODE} Votre clé de licence DQE ou jeton OAuth2. Contactez le support si vous n'en avez pas encore. Obligatoire
CodePostal {POSTAL_CODE} Saisie de code postal ou de nom de ville. Obligatoire
Pays {COUNTRY_CODE} Code pays ISO 3166-1 alpha-3 pour la portée de la recherche d'adresse. Exemple : FRA ou GBR. Obligatoire
Alpha True Envoyez toujours True. Paramètre obligatoire. Obligatoire
Instance {INSTANCE} Non renvoyé dans les résultats de cet endpoint - peut être omis sans risque. Optionnel
Etendue Y ou N Active la recherche dès 2 caractères saisis dans le code postal. Par défaut : N. Optionnel
NbMax {NB} Nombre maximum de suggestions de localité retournées. Optionnel
Filter {FILTER} Contrôle le type de résultats retournés. Lorsqu'il est omis, la réponse inclut les codes postaux, les voies (le cas échéant) et les entrées CEDEX.
1 = code postal et CEDEX uniquement · 2 = code postal et voie (sans CEDEX) · 3 = code postal uniquement · 4 = une suggestion par code postal et ville (Malaisie uniquement)
Optionnel
Langue {LANGUAGE} Filtre les résultats par langue/script. JPN : JP = Kanji · JK = Katakana · EN = Romanisé. HKG : EN · ZH. THA : EN · TH. Voir Guide des langues. Optionnel
France et Belgique : un code postal peut correspondre à plusieurs communes (regroupement fragmenté). CP retournera une ligne de résultat par commune.

Réponse

En cas de succès, l'API retourne un objet JSON. Les clés sont des numéros de rang de "1" à "n", chacun étant associé à un dictionnaire de champs d'adresse.

Schéma de réponse variable - Lorsque IDVoie est renseigné, Voie apparaît dans le JSON. Lorsque seule une ville est retournée, Voie est absent. Utilisez un IDVoie non vide pour détecter le schéma applicable.
Ordre des résultats - Les résultats sont classés par pertinence, et non par ordre croissant de code postal. Lorsqu'un code postal exact est saisi et correspond à une seule ville, un seul résultat est retourné. Lorsqu'un code postal partiel est saisi avec Etendue=Y, les résultats sont classés par densité de population (ville la plus peuplée en premier). Lorsqu'un nom de ville est saisi (exact ou partiel), les correspondances exactes apparaissent en premier, suivies d'un classement par pertinence des mots-clés.
Champ Description France International
Province Code ISO de l'état ou de la région administrative (ex. 17 pour le Japon). String (50) String (50)
IDLocalite Identifiant unique de ville (code INSEE pour la France). String (20) String (20)
Pays Code pays ISO 3166-1 alpha-3. String (3) String (3)
Instance Champ interne. String String
CodePostal Code postal de l'adresse. String (10) String (10)
SousLocalite Sous-localité (quartier, arrondissement, banlieue). Vide String (50)
LieuDit Lieu-dit ou hameau (France) ou champ équivalent de niveau quartier (international). Disponibilité variable selon les pays. String (38) String (50)
Localite Nom de ville. String (38) String (50)
Latitude Coordonnées géographiques de la localité trouvée. Non disponible pour tous les pays - voir couverture. String String
Longitude Coordonnées géographiques de la localité trouvée. Non disponible pour tous les pays - voir couverture. String String
IDVoie Identifiant unique de voie. Renseigné uniquement lorsque le code postal correspond à une voie spécifique. Lorsqu'il est présent, vous pouvez ignorer ADR et transmettre directement IDVoie à COMPL. String (20) String (20)
Voie Nom de voie. Présent dans la réponse uniquement lorsque IDVoie est renseigné. String (38) String (150)
NbNumero Nombre total de numéros de rue sur la voie trouvée. Renseigné uniquement lorsque IDVoie est présent ; vide sinon. String String
ListeNumero Liste de numéros de rue valides pour la voie trouvée, séparés par des points-virgules. Contient toujours tous les numéros lorsqu'elle est présente ; vide lorsque IDVoie est absent. String (1024) String (1024)
Numero Numéro de rue complet, complément inclus (bis, ter, etc.). String (38) String (38)
TypeVoie Type de voie (ex. RUE, AVENUE, BOULEVARD). Non retourné pour tous les jeux de données internationaux. String (20) String (20)
Complement Information d'adresse complémentaire. Vide String (50)
Entreprise Nom d'entreprise associé à l'adresse. String (38) String (38)
Cedex Indicateur CEDEX : 1 = adresse CEDEX, 0 = non CEDEX. String (1) String (1)
Region1 Libellé ISO de l'état ou de la région administrative (ex. ISHIKAWA pour le Japon). Non disponible String (50)
Region2 Comté ou niveau administratif équivalent. Non disponible String (50)
Region3 Comté ou équivalent (niveau alternatif). Non disponible String (50)
Region4 Information régionale ou administrative complémentaire. Non disponible String (50)

Exemple de réponse

Exemple de réponse - France (75008 Paris)
{ "1": { "Province": "*", "IDLocalite": "75108", "NbNumero": "", "Pays": "FRA", "IDVoie": "", "Cedex": "0", "Numero": "", "TypeVoie": "", "Instance": "", "ListeNumero": "", "CodePostal": "75008", "SousLocalite": "", "LieuDit": "", "Latitude": "48.8775112171854", "Localite": "PARIS", "Longitude": "2.31760169076841", "Complement": "", "Entreprise": "" } }
Exemple de réponse - Japon (108-6390)
{ "1": { "Cedex": "0", "CodePostal": "108-6390", "Complement": "", "Entreprise": "", "IDLocalite": "402574_1086390", "IDVoie": "", "Instance": "0", "Latitude": "", "LieuDit": "", "ListeNumero": "", "Localite": "ミナトク", "Longitude": "", "NbNumero": "", "Numero": "", "Pays": "JPN", "Province": "13", "SousLocalite": "", "TypeVoie": "", "Region1": "トウキョウト" } }

Erreurs

HTTP Type d'erreur Corps de la réponse
200 Licence manquant ou vide {} - résultat vide, aucune erreur levée
401 Licence incorrect ou expiré unauthorized_client
400 Paramètre CodePostal manquant Bad Request Parameters * not allowed
400 Faute de frappe dans le nom du paramètre (ex. codepostal au lieu de CodePostal) Bad Request Parameters * not allowed
200 Code ISO Pays non reconnu (ex. AAA) {} - résultat vide, aucune erreur levée
401 Format de pays invalide (ex. FRAN au lieu de FRA) unauthorized_country

Tester l'API

Cliquez sur le bouton ci-dessous pour tester ce endpoint en direct dans votre navigateur.

Ouvrir la console

Recherche de voie (ADR)

Deuxième étape de l'approche en entonnoir. À partir d'un IDLocalite issu de CP et d'un nom de voie partiel, retourne les voies correspondantes. L'IDVoie de chaque résultat alimente l'étape finale : COMPL.

Requête

ADR prend en charge à la fois GET et POST.

{SERVER_ADDRESS} et {LICENCE_CODE} sont fournis par DQE lors de la création du compte. {CITY_ID} est obtenu à partir du champ IDLocalite de la réponse CP lorsque l'utilisateur sélectionne une ville. Contactez votre chargé de compte DQE pour obtenir ces identifiants.
La valeur Adresse doit être encodée en URL - ex. l'églisel%27%C3%A9glise.
GEThttps://{SERVER_ADDRESS}/ADR/?IDLocalite={CITY_ID}&Adresse={INPUT}&Pays={COUNTRY_CODE}&Licence={LICENCE_CODE}

Exemple cURL

France - IDLocalite de l'étape CP précédente

curl "https://{SERVER_ADDRESS}/ADR/?IDLocalite=75108&Adresse=bienfaisance&Pays=FRA&Licence={LICENCE_CODE}&Taille=38&Version=1.1"
POSThttps://{SERVER_ADDRESS}/ADR/

Envoyez tous les paramètres dans le corps de la requête avec Content-Type: application/x-www-form-urlencoded. L'adresse du serveur reste dans l'URL.

Exemple cURL

curl -X POST "https://{SERVER_ADDRESS}/ADR/" \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "IDLocalite=75108" \ -d "Adresse=bienfaisance" \ -d "Pays=FRA" \ -d "Licence={LICENCE_CODE}"

Paramètres

Paramètre Valeur Description Obl. / Opt.
Licence {LICENCE_CODE} Votre clé de licence DQE ou jeton OAuth2. Contactez le support si vous n'en avez pas encore. Obligatoire
IDLocalite {CITY_ID} Identifiant de ville retourné par CP dans le champ IDLocalite. Limite la recherche de voie à la ville sélectionnée. Obligatoire
Adresse {INPUT} Nom de voie partiel saisi par l'utilisateur. Obligatoire
Pays {COUNTRY_CODE} Code pays ISO 3166-1 alpha-3 pour la portée de la recherche d'adresse. Exemple : FRA ou GBR. Obligatoire
Taille {LENGTH} Longueur maximale des caractères pour les champs d'adresse retournés. S'applique uniquement aux adresses en caractères latins. Par défaut : 38. Minimum recommandé : 32. Optionnel
Instance {INSTANCE} Non renvoyé dans les résultats de cet endpoint - peut être omis sans risque. Optionnel
Version=1.1 1.1 Lorsqu'il est défini à 1.1, renseigne le champ LieuDit pour les petites villes. Sans cela, les noms de petites villes apparaissent entre crochets dans le champ Localite. Optionnel
Langue {LANGUAGE} Filtre les résultats par langue/script. JPN : JP = Kanji · JK = Katakana · EN = Romanisé. HKG : EN · ZH. THA : EN · TH. Voir Guide des langues. Optionnel

Réponse

En cas de succès, l'API retourne un objet JSON. Les clés sont des numéros de rang de "1" à "n", chacun étant associé à un dictionnaire de champs de voie.

Champ Description France International
label Chaîne prête à afficher pour une liste déroulante d'autocomplétion. Les nombres entre [crochets] indiquent que le numéro n'a pas été trouvé dans les données de référence. Voir Champ label - affichage uniquement pour des notes d'utilisation.
N'utilisez label que pour remplir la liste déroulante de suggestions - jamais pour stocker l'adresse. Voir le guide d'intégration →
Non disponible String (255)
IDVoie
aussi : CodeVoie
Identifiant unique de voie. Utilisé en entrée de COMPL. String (20) String (20)
Voie Nom de voie. String (38) String (150)
Saisie Forme normalisée de la voie saisie. Peut différer de la saisie d'origine en casse ou en formatage. String (255) String (255)
TypeVoie Type de voie (ex. RUE, AVENUE, BOULEVARD). Non retourné pour tous les jeux de données internationaux. String (20) String (20)
Numero
aussi : Num
Numéro de rue complet, complément inclus (bis, ter, etc.). String (38) String (38)
NumSeul Numéro de rue seul, sans complément (bis, ter, etc.). Non disponible String (4)
NbNumero
aussi : Nbnumero
Lorsque le numéro recherché n'est pas trouvé ou est manquant, retourne le nombre total de numéros de rue valides pour cette voie. Les deux clés (NbNumero / Nbnumero) désignent la même valeur. Peut être une chaîne vide lorsque non applicable. String String
ListeNumero Liste de numéros de rue valides, séparés par des points-virgules. Contient tous les numéros lorsqu'aucun numéro n'a été saisi ou que le numéro saisi n'est pas trouvé ; contient uniquement le numéro trouvé sinon. String (1024) String (1024)
valid_num Indicateur de validité du numéro de rue. 1 si le numéro existe dans les données de référence, 0 sinon. Retourne une chaîne vide pour certaines adresses internationales où la validation au niveau du numéro n'est pas disponible. Non disponible Integer
CodePostal Code postal de l'adresse. String (10) String (10)
Localite Nom de ville. String (38) String (50)
IDLocalite Identifiant unique de ville (code INSEE pour la France). String (20) String (20)
SousLocalite Sous-localité (quartier, arrondissement, banlieue). Non disponible String (50)
LieuDit Lieu-dit. Renseigné lorsque Version=1.1 est défini dans la requête. Peut être renseigné pour les adresses internationales. String (38) String (50)
Province Code ISO de l'état ou de la région administrative (ex. 17 pour le Japon). Non disponible String (50)
Region1 Libellé ISO de l'état ou de la région administrative (ex. ISHIKAWA pour le Japon). Non disponible String (50)
Region2 Comté ou niveau administratif équivalent. Non disponible String (50)
Region3 Comté ou équivalent (niveau alternatif). Non disponible String (50)
Region4 Information régionale ou administrative complémentaire. Non disponible String (50)
Suburb Banlieue ou quartier. Non disponible String (50)
Thoroughfare Voie dépendante. Non disponible Royaume-Uni uniquement
Complement Information d'adresse complémentaire (nom du bâtiment, étage, etc.). Disponibilité variable selon les pays - voir le guide d'intégration. Vide String (50)
Complement2 Seconde ligne de sous-bâtiment. Renseignée pour certaines adresses internationales lorsqu'un identifiant de bâtiment et un identifiant de sous-bâtiment (étage, appartement, suite) sont disponibles en tant qu'entrées distinctes, et pour certaines adresses CEDEX organisationnelles. Non disponible String (50)
Entreprise Nom d'entreprise associé à l'adresse. String (38) String (38)
Cedex Indicateur CEDEX : 1 = adresse CEDEX, 0 = non CEDEX. String (1) String (1)
Latitude Coordonnées géographiques de l'adresse trouvée. Non disponible pour tous les pays - voir couverture. String String
Longitude Coordonnées géographiques de l'adresse trouvée. Non disponible pour tous les pays - voir couverture. String String
Roudis Code Roudis. String Non disponible
Pays Code pays ISO 3166-1 alpha-3. String (3) String (3)
Instance Champ interne. String String

Retourné avec Version=1.1

Voie sélectionnée sans numéro ? Voir le guide d'intégration →

Exemple de réponse

Exemple de réponse - France (Rue de la Bienfaisance, 75008 Paris)
{ "1": { "IDLocalite": "75108", "Saisie": "bienfaisance", "Pays": "FRA", "IDVoie": "1454259", "Voie": "RUE DE LA BIENFAISANCE", "Roudis": "", "ListeNumero": "1;2;3;3B;4;6;7;7B;8;9;10;12;12B;15;16;17;19;20;21;23;25;26;27;28;29;30;32;33;34;35;36;37;39;40;41;42;43;44;45;46;47;48;50;51;52;52B;54", "Numero": "", "TypeVoie": "RUE", "Instance": "", "Cedex": "0", "Num": "", "CodePostal": "75008", "NbNumero": "47", "Longitude": "2.316451", "LieuDit": "", "Latitude": "48.876526", "Localite": "PARIS", "CodeVoie": "1454259", "Complement": "", "Entreprise": "" } }
Exemple de réponse - Japon (三田, 108-6390)
{ "1": { "label": "〒108-6390 東京都港区三田", "valid_num": 1, "Num": "", "Numero": "", "ListeNumero": "", "Nbnumero": 0, "NbNumero": 0, "NumSeul": "", "Saisie": "三田", "Pays": "JPN", "Complement": "", "Voie": "三田", "CodeVoie": "558203", "IDVoie": "558203", "IDLocalite": "402573", "Instance": 1, "CodePostal": "108-6390", "Localite": "港区", "Province": "13", "LieuDit": "", "Longitude": "", "Latitude": "", "Region1": "東京都", "Region2": "港区", "Region3": "", "Suburb": "", "TypeVoie": "" } }

Erreurs

HTTP Type d'erreur Corps de la réponse
200 Licence manquant ou vide {} - résultat vide, aucune erreur levée
401 Licence incorrect ou expiré unauthorized_client
400 IDLocalite manquant Bad Request Parameters * not allowed
400 Adresse manquant Bad Request Parameters * not allowed
400 Pays manquant Bad Request Parameters * not allowed
400 Faute de frappe dans le nom du paramètre (ex. faute sur Adresse ou IDLocalite) Bad Request Parameters * not allowed

Tester l'API

Cliquez sur le bouton ci-dessous pour tester ce endpoint en direct dans votre navigateur.

Ouvrir la console

Bâtiment (COMPL)

Dernière étape de l'approche en entonnoir. À partir d'un IDVoie et d'un Numero issus d'ADR, retourne une liste de suggestions de sous-bâtiment : noms de bâtiments, numéros d'étage, noms d'entreprises, numéros d'appartement.

Requête

COMPL prend en charge à la fois GET et POST.

{SERVER_ADDRESS} et {LICENCE_CODE} sont fournis par DQE lors de la création du compte. {STREET_ID} est obtenu à partir du champ IDVoie de la réponse ADR lorsque l'utilisateur sélectionne une voie. Contactez votre chargé de compte DQE pour obtenir ces identifiants.
GEThttps://{SERVER_ADDRESS}/COMPL/?IDVoie={STREET_ID}&IDNum={NUM}&Pays={COUNTRY_CODE}&Licence={LICENCE_CODE}

Exemple cURL

France - IDVoie de l'étape ADR précédente

curl "https://{SERVER_ADDRESS}/COMPL/?IDVoie=2408474&IDNum=1&Pays=FRA&Licence={LICENCE_CODE}"

Lorsque l'utilisateur n'a pas saisi de numéro de rue, transmettez un paramètre IDNum vide : &IDNum=

POSThttps://{SERVER_ADDRESS}/COMPL/

Envoyez tous les paramètres dans le corps de la requête avec Content-Type: application/x-www-form-urlencoded. L'adresse du serveur reste dans l'URL.

Exemple cURL

curl -X POST "https://{SERVER_ADDRESS}/COMPL/" \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "IDVoie=2408474" \ -d "IDNum=1" \ -d "Pays=FRA" \ -d "Licence={LICENCE_CODE}"

Paramètres

Paramètre Valeur Description Obl. / Opt.
Licence {LICENCE_CODE} Votre clé de licence DQE ou jeton OAuth2. Contactez le support si vous n'en avez pas encore. Obligatoire
IDVoie {STREETID} Identifiant unique de voie retourné par ADR dans le champ IDVoie. Obligatoire
IDNum {STREETNUMBER} Numéro de rue sélectionné par l'utilisateur - correspond au champ Numero de la réponse ADR. Obligatoire
Pays {COUNTRY_CODE} Code pays ISO 3166-1 alpha-3 pour la portée de la recherche d'adresse. Exemple : FRA ou GBR. Obligatoire
Taille {LENGTH} Longueur maximale des caractères pour les champs d'adresse retournés. S'applique uniquement aux adresses en caractères latins. Une valeur trop basse peut tronquer les résultats. Par défaut : 38. Minimum recommandé : 32. Optionnel
Instance {INSTANCE} Non renvoyé dans les résultats de cet endpoint - peut être omis sans risque. Optionnel

Réponse

La réponse JSON est un dictionnaire dont les clés sont numérotées de "1" à "n". Chaque entrée contient un complément d'adresse.

L'absence de données de sous-bâtiment n'est pas une erreur. Voir le guide d'intégration →
Champ Description France International
Batiment Libellé du complément de bâtiment ou d'appartement. String (38) String (150)
CodePostal Code postal associé au complément. Non disponible String (10)

Exemple de réponse

Exemple de réponse - France (1 Rue de la Louisiane, 31200 Toulouse)
{ "1": { "Batiment": "BATIMENT D RESIDENCE ALLEE DES CEDRES" }, "2": { "Batiment": "BATIMENT A RESIDENCE ALLEE DES CEDRES" }, "3": { "Batiment": "BATIMENT B RESIDENCE ALLEE DES CEDRES" }, "4": { "Batiment": "BATIMENT C RESIDENCE ALLEE DES CEDRES" } }
Exemple de réponse - International (GBR)
{ "1": { "Batiment": "Town Hall, Tameside Metropolitan Borough Council", "CodePostal": "M34 2AP" }, "2": { "Batiment": "Victoria Park Community Association", "CodePostal": "M34 2AP" } }

Erreurs

HTTP Type d'erreur Corps de la réponse
401 Paramètre Licence manquant ou vide unauthorized_client
401 Clé de licence incorrecte ou expirée unauthorized_client
400 Paramètre IDVoie manquant Bad Request Parameters empty fields
400 Paramètre IDNum manquant Bad Request Parameters empty fields
400 Paramètre Pays manquant Bad Request Parameters empty fields
400 Faute de frappe dans le nom du paramètre (ex. IdVoie au lieu de IDVoie) Bad Request Parameters empty fields

Tester l'API

Cliquez sur le bouton ci-dessous pour tester ce endpoint en direct dans votre navigateur.

Ouvrir la console

Voir aussi

Associé à

Cet article vous a-t-il été utile ?

Utilisateurs qui ont trouvé cela utile : 0 sur 0