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

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

Autocomplétion d'adresse en trois étapes utilisant l'API RESTful. funnelpostcode trouve les villes correspondantes à partir d'un code postal ou d'un nom de ville ; funneladdress renvoie les voies de la ville sélectionnée ; funnelcompl récupère les options de complément de bâtiment après la sélection de la voie.

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

Sélection de la ville (funnelpostcode)

Première étape de l'approche en entonnoir. Renvoie les villes et codes postaux correspondants à partir d'une saisie partielle de code postal ou de nom de ville. Le CityId de chaque résultat alimente l'étape suivante : funneladdress.

Requête

funnelpostcode prend en charge à la fois GET et POST.

{SERVER_ADDRESS}, {VERSION} et {LICENCE_CODE} sont fournis par DQE lors de la création du compte. Contactez votre gestionnaire de compte DQE pour obtenir ces identifiants.
GEThttps://{SERVER_ADDRESS}/{VERSION}/funnelpostcode/?PostalCode={POSTAL_CODE}&Country={COUNTRY_CODE}&Licence={LICENCE_CODE}

Exemple cURL

France - Recherche par code postal

curl "https://{SERVER_ADDRESS}/v1/funnelpostcode/?PostalCode=75008&Country=FRA&Licence={LICENCE_CODE}"
POSThttps://{SERVER_ADDRESS}/{VERSION}/funnelpostcode/

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

Exemple cURL

curl -X POST "https://{SERVER_ADDRESS}/v1/funnelpostcode/" \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "PostalCode=75008" \ -d "Country=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
PostalCode {POSTAL_CODE} Saisie du code postal ou du nom de ville. Obligatoire
Country {COUNTRY_CODE} Code pays ISO 3166-1 alpha-3 pour la portée de la recherche d'adresse. Exemple : FRA ou GBR. Obligatoire
Extended Y ou N Active la recherche dès 2 caractères saisis dans le code postal. Par défaut : N. Optionnel
Limit {NB} Nombre maximum de suggestions de localités renvoyées. Optionnel
Filter {FILTER} Contrôle le type de résultats renvoyé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 le guide des langues. Optionnel
France et Belgique : les codes postaux peuvent correspondre à plusieurs communes (regroupement fragmenté). funnelpostcode renverra une ligne de résultat par commune.

Réponse

En cas de succès, l'API renvoie un objet JSON contenant un compteur Found et un tableau PostalCodes.

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 renvoyé. Lorsqu'un code postal partiel est saisi avec Extended=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 de mots-clés.

Niveau supérieur

Clé Description Type
Found Nombre d'objets de suggestion de localité renvoyés. Integer
PostalCodes Tableau d'objets de suggestion de localité. Array

Objet de suggestion de localité - PostalCodes[n]

Clé Description France International
PostalCode Code postal de l'adresse. String (10) String (10)
City Nom de la ville. String (38) String (50)
Hamlet Localité ou hameau nommé (France) ou champ de niveau district équivalent (international). Disponibilité variable selon les pays. String (38) String (50)
SpecialDistribution Indicateur CEDEX : 1 = adresse CEDEX, 0 = non CEDEX. String (1) String (1)
Country Code pays ISO 3166-1 alpha-3. String (3) String (3)
AdministrativeArea Comté ou niveau administratif équivalent. Vide String (50)
StateLabel Libellé ISO de l'État ou de la région administrative (ex. ISHIKAWA pour le Japon). Non disponible String (50)
StateCode Code ISO de l'État ou de la région administrative (ex. 17 pour le Japon). String (50) String (50)
SubLocality Sous-localité (quartier, arrondissement, banlieue). Vide String (50)
CityId Identifiant unique de ville (code INSEE pour la France). String (20) String (20)
Latitude Géocoordonnées de la localité correspondante. Non disponible pour tous les pays - voir la couverture. String String
Longitude Géocoordonnées de la localité correspondante. Non disponible pour tous les pays - voir la couverture. String String

Objet Informations - PostalCodes[n].Informations

Renseigné uniquement lorsque le code postal correspond directement à une adresse spécifique (ex. codes CEDEX en France). Sinon, tous les champs sont vides.

Clé Description France International
AdditionalAddress Ligne d'adresse supplémentaire. Vide String (50)
AdditionalAddress_2 Deuxième ligne d'adresse supplémentaire. Vide String (50)
StreetNumberList Liste de numéros de voie valides séparés par des points-virgules pour la voie correspondante. Contient toujours tous les numéros lorsqu'elle est présente ; vide lorsque StreetId est absent. String (1024) String (1024)
StreetType Type de voie (ex. RUE, AVENUE, BOULEVARD). Non renvoyé pour tous les jeux de données internationaux. String (20) String (20)
Street Nom de la voie. String (38) String (150)
Suburb Banlieue ou quartier. Vide String (50)
StreetId Identifiant unique de voie. Renseigné uniquement lorsque le code postal correspond à une voie spécifique. Lorsqu'il est présent, vous pouvez ignorer funneladdress et transmettre StreetId directement à funnelcompl. String (20) String (20)
Company Nom de l'entreprise. String (38) String (38)

Exemple de réponse

Exemple de réponse - France (75008 Paris)
{ "Found": 1, "PostalCodes": [ { "PostalCode": "75008", "City": "PARIS", "Hamlet": "", "SpecialDistribution": "0", "Country": "FRA", "AdministrativeArea": "", "StateLabel": "", "StateCode": "*", "SubLocality": "", "CityId": "75108", "Latitude": "48.8775112171854", "Longitude": "2.31760169076841", "Informations": { "AdditionalAddress": "", "AdditionalAddress_2": "", "StreetNumberList": "", "StreetType": "", "Street": "", "Suburb": "", "StreetId": "", "Company": "" } } ] }
Exemple de réponse - Japon (108-6390)
{ "Found": 3, "PostalCodes": [ { "PostalCode": "108-6390", "City": "ミナトク", "Hamlet": "", "SpecialDistribution": "0", "Country": "JPN", "AdministrativeArea": "ミナトク", "StateLabel": "トウキヨウト", "StateCode": "13", "SubLocality": "", "CityId": "402574_1086390", "Latitude": "", "Longitude": "", "Informations": { "AdditionalAddress": "", "AdditionalAddress_2": "", "StreetNumberList": "", "StreetType": "", "Street": "", "Suburb": "", "StreetId": "", "Company": "" } } ] }

Erreurs

Le endpoint RESTful renvoie un corps d'erreur JSON structuré avec un code de statut HTTP, un message et un identifiant d'erreur.

HTTP Type d'erreur Corps de la réponse
400 Paramètre obligatoire manquant
{"status":400,"message":"Missing parameters","details":"PostalCode,Licence","error":"bad request"}
400 Le code pays n'est pas un ISO 3166-1 alpha-3 valide
{"status":400,"message":"Country doesn't exist","details":"INVALID","error":"bad request"}
401 Numéro de licence incorrect ou non autorisé
{"status":401,"message":"Your licence is not allowed to cover this functionnality","details":"WRONG","error":"unauthorized_client"}

Tester l'API

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

Ouvrir la console

Recherche d'adresse (funneladdress)

Deuxième étape de l'approche en entonnoir. À partir d'un CityId issu de funnelpostcode et d'un nom de voie partiel, renvoie les voies correspondantes. Le StreetId de chaque résultat alimente l'étape finale : funnelcompl.

Requête

funneladdress prend en charge à la fois GET et POST.

{SERVER_ADDRESS}, {VERSION} et {LICENCE_CODE} sont fournis par DQE lors de la création du compte. {CITY_ID} est obtenu à partir de la réponse funnelpostcode lorsque l'utilisateur sélectionne une ville. Contactez votre gestionnaire de compte DQE pour obtenir ces identifiants.
La saisie de l'adresse doit être encodée en URL - ex. l'églisel%27%C3%A9glise.
GEThttps://{SERVER_ADDRESS}/{VERSION}/funneladdress/?CityId={CITY_ID}&Country={COUNTRY_CODE}&Street={INPUT}&Licence={LICENCE_CODE}

Exemple cURL

France - CityId de l'étape funnelpostcode précédente

curl "https://{SERVER_ADDRESS}/v1/funneladdress/?CityId=75108&Country=FRA&Street=bienfaisance&Licence={LICENCE_CODE}"
POSThttps://{SERVER_ADDRESS}/{VERSION}/funneladdress/

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

Exemple cURL

curl -X POST "https://{SERVER_ADDRESS}/v1/funneladdress/" \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "CityId=75108" \ -d "Country=FRA" \ -d "Street=bienfaisance" \ -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
CityId {CITY_ID} Identifiant de ville renvoyé par funnelpostcode dans le champ CityId. Limite la recherche de voie à la ville sélectionnée. Obligatoire
Country {COUNTRY_CODE} Code pays ISO 3166-1 alpha-3 pour la portée de la recherche d'adresse. Exemple : FRA ou GBR. Obligatoire
Street {INPUT} Nom de voie partiel saisi par l'utilisateur. Obligatoire
Limit {NB} Nombre maximum de suggestions d'adresses renvoyées. Optionnel
Length {LENGTH} Longueur maximale de caractères pour les champs d'adresse renvoyés. S'applique uniquement aux adresses en caractères latins. Par défaut : 38. Minimum recommandé : 32. Optionnel
Langue {LANGUAGE} Filtre les résultats par langue/script. JPN : JP Kanji · JK Katakana · EN Romanisé. HKG : EN · ZH. THA : EN · TH. Voir le guide des langues. Optionnel
Version 1.1 Lorsqu'il est défini sur 1.1, remplit le champ Hamlet pour les petites communes. Sans cela, les noms des petites communes apparaissent entre parenthèses dans le champ City. Optionnel

Réponse

En cas de succès, la réponse est un objet JSON avec deux clés de niveau supérieur : Found (entier) et Addresses (tableau d'objets de suggestion d'adresse).

Niveau supérieur

Clé Description Type
Found Nombre d'objets de suggestion d'adresse renvoyés. Integer
Addresses Tableau d'objets de suggestion d'adresse. Array

Objet de suggestion d'adresse - Addresses[n]

Clé Description France International
PostalCode Code postal de l'adresse. String (10) String (10)
City Nom de la ville. String (38) String (50)
Hamlet Localité ou hameau nommé (France) ou champ de niveau district équivalent (international). Renseigné lorsque Version=1.1 est défini. Disponibilité variable selon les pays. String (38) String (50)
SpecialDistribution Indicateur CEDEX : 1 = adresse CEDEX, 0 = non CEDEX. String (1) String (1)
Country Code pays ISO 3166-1 alpha-3. String (3) String (3)
StateCode Code ISO de l'État ou de la région administrative (ex. 17 pour le Japon). Vide String (50)
StateLabel Libellé ISO de l'État ou de la région administrative (ex. ISHIKAWA pour le Japon). Non disponible String (50)
AdministrativeArea Comté ou niveau administratif équivalent. Vide String (50)
SubLocality Sous-localité (quartier, arrondissement, banlieue). Vide String (50)
Suburb Banlieue ou quartier. Vide String (50)
CityId Identifiant unique de ville (code INSEE pour la France). String (20) String (20)
Input Forme normalisée de la voie saisie. Peut différer de la saisie d'origine par la casse ou le formatage. String (255) String (255)
Label Chaîne prête à l'affichage pour une liste déroulante d'autocomplétion. Les numéros 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 les consignes d'utilisation.
Utilisez Label uniquement pour alimenter la liste déroulante de suggestions - jamais pour stocker l'adresse. Voir le guide d'intégration →
Vide String (255)
Street Nom de la voie. String (38) String (150)
StreetId Identifiant unique de voie. Utilisé en entrée de funnelcompl. String (20) String (20)
StreetType Type de voie (ex. RUE, AVENUE, BOULEVARD). Non renvoyé pour tous les jeux de données internationaux. String (20) String (20)
StreetNumber Numéro de voie complet, complément inclus (bis, ter, etc.). String (38) String (38)
StreetNumberOnly Numéro de voie seul, sans complément (bis, ter, etc.). Vide String (4)
StreetNumberList Liste de numéros de voie 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 est introuvable ; contient uniquement le numéro correspondant dans le cas contraire. String (1024) String (1024)
StreetNumberListCount Lorsque le numéro recherché est introuvable ou absent, renvoie le nombre total de numéros de voie valides pour cette voie. Vide String
IsValidStreetNumber Indicateur de validité du numéro de voie. 1 si le numéro existe dans les données de référence, 0 sinon. Renvoie une chaîne vide pour certaines adresses internationales où la validation au niveau du numéro n'est pas disponible. Non disponible Integer
AdditionalAddress Informations d'adresse complémentaires (nom du bâtiment, étage, etc.). Disponibilité variable selon les pays - voir le guide d'intégration. Vide String (50)
Company Nom de l'entreprise associée à l'adresse. String (38) String (38)
Latitude Géocoordonnées de l'adresse correspondante. Non disponible pour tous les pays - voir la couverture. String String
Longitude Géocoordonnées de l'adresse correspondante. Non disponible pour tous les pays - voir la couverture. String String

Renseigné lorsque 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)
{ "Found": 1, "Addresses": [ { "PostalCode": "75008", "City": "PARIS", "Hamlet": "", "SpecialDistribution": "0", "Country": "FRA", "StateCode": "", "SubLocality": "", "CityId": "75108", "Input": "bienfaisance", "Label": "", "AdditionalAddress": "", "StreetNumber": "", "StreetType": "RUE", "Street": "RUE DE LA BIENFAISANCE", "StreetId": "1454259", "IsValidStreetNumber": "", "StreetNumberListCount":"", "StreetNumberList": "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", "StreetNumberOnly": "", "StateLabel": "", "AdministrativeArea": "", "Suburb": "", "Company": "", "Latitude": "48.876526", "Longitude": "2.316451" } ] }
Exemple de réponse - Japon (三田, 108-6390)

Japon - CityId 402573_1086390, Langue=JP (Kanji)

{ "Found": 1, "Addresses": [ { "PostalCode": "108-6390", "City": "港区", "Hamlet": "", "SpecialDistribution": "", "Country": "JPN", "StateCode": "13", "SubLocality": "", "CityId": "402573", "Input": "三田", "Label": "〒108-6390 東京都港区三田", "AdditionalAddress": "", "StreetNumber": "", "StreetType": "", "Street": "三田", "StreetId": "558203", "IsValidStreetNumber": 1, "StreetNumberListCount":0, "StreetNumberList": "", "StreetNumberOnly": "", "StateLabel": "東京都", "AdministrativeArea": "港区", "Suburb": "", "Company": "", "Latitude": "", "Longitude": "" } ] }

Erreurs

Le endpoint RESTful renvoie un corps d'erreur JSON structuré avec un code de statut HTTP, un message et un identifiant d'erreur.

HTTP Type d'erreur Corps de la réponse
400 Paramètre obligatoire manquant
{"status":400,"message":"Missing parameters","details":"CityID","error":"bad request"}
400 Le code pays n'est pas un ISO 3166-1 alpha-3 valide
{"status":400,"message":"Country doesn't exist","details":"JPNde","error":"bad request"}
401 Numéro de licence incorrect ou non autorisé
{"status":401,"message":"Your licence is not allowed to cover this functionnality","details":"WRONG LICENSE","error":"unauthorized_client"}

Tester l'API

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

Ouvrir la console

Bâtiment (funnelcompl)

Dernière étape de l'approche en entonnoir. À partir d'un StreetId et d'un StreetNumber issus de funneladdress, renvoie une liste de suggestions de compléments de bâtiment : noms de bâtiment, numéros d'étage, noms d'entreprise, numéros d'appartement.

Requête

funnelcompl prend en charge à la fois GET et POST.

{SERVER_ADDRESS}, {VERSION} et {LICENCE_CODE} sont fournis par DQE lors de la création du compte. {STREET_ID} est obtenu à partir du champ StreetId de la réponse funneladdress lorsque l'utilisateur sélectionne une voie. Contactez votre gestionnaire de compte DQE pour obtenir ces identifiants.
GEThttps://{SERVER_ADDRESS}/{VERSION}/funnelcompl/?StreetId={STREET_ID}&Country={COUNTRY_CODE}&StreetNumber={NUMBER}&Licence={LICENCE_CODE}

Exemple cURL

France - StreetId de l'étape funneladdress précédente

curl "https://{SERVER_ADDRESS}/v1/funnelcompl/?StreetId=2408474&Country=FRA&StreetNumber=1&Licence={LICENCE_CODE}"

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

POSThttps://{SERVER_ADDRESS}/{VERSION}/funnelcompl/

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

Exemple cURL

curl -X POST "https://{SERVER_ADDRESS}/v1/funnelcompl/" \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "StreetId=0751080070" \ -d "Country=FRA" \ -d "StreetNumber=17" \ -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
StreetId {STREET_ID} Identifiant unique de voie renvoyé par funneladdress dans le champ StreetId. Obligatoire
Country {COUNTRY_CODE} Code pays ISO 3166-1 alpha-3 pour la portée de la recherche d'adresse. Exemple : FRA ou GBR. Obligatoire
StreetNumber {NUMBER} Numéro de voie sélectionné par l'utilisateur - correspond au champ StreetNumber de la réponse funneladdress. Obligatoire
Length {LENGTH} Longueur maximale de caractères pour les champs d'adresse renvoyé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

Réponse

En cas de succès, la réponse est un objet JSON avec trois clés de niveau supérieur : Found, AdditionalAddresses (tableau) et un objet de géocoordonnées Geolocalisation.

L'absence de données de complément n'est pas une erreur. Voir le guide d'intégration →

Niveau supérieur

Clé Description Type
Found Nombre d'objets de complément d'adresse renvoyés. Integer
AdditionalAddresses Tableau d'objets de complément d'adresse. Array
Geolocalisation Géocoordonnées de l'adresse correspondante. Vide lorsque non disponible pour ce type d'adresse. Object

Objet AdditionalAddress - AdditionalAddresses[n]

Clé Description France International
AdditionalAddress Libellé du complément de bâtiment ou d'appartement. String (38) String (150)
PostalCode Code postal associé au complément. String String

Géocoordonnées - Geolocalisation

Clé Description France International
Latitude Géocoordonnées de l'adresse correspondante. Non disponible pour tous les pays - voir la couverture. String String
Longitude Géocoordonnées de l'adresse correspondante. Non disponible pour tous les pays - voir la couverture. String String

Exemple de réponse

Exemple de réponse - France (1 Rue de la Louisiane, 31200 Toulouse)
{ "Found": 4, "AdditionalAddresses": [ { "AdditionalAddress": "BATIMENT A RESIDENCE ALLEE DES CEDRES", "PostalCode": "" }, { "AdditionalAddress": "BATIMENT B RESIDENCE ALLEE DES CEDRES", "PostalCode": "" }, { "AdditionalAddress": "BATIMENT C RESIDENCE ALLEE DES CEDRES", "PostalCode": "" }, { "AdditionalAddress": "BATIMENT D RESIDENCE ALLEE DES CEDRES", "PostalCode": "" } ], "Geolocalisation": { "Latitude": "", "Longitude": "" } }

Erreurs

Le endpoint RESTful renvoie un corps d'erreur JSON structuré avec un code de statut HTTP, un message et un identifiant d'erreur.

HTTP Type d'erreur Corps de la réponse
400 Paramètre obligatoire manquant
{"status":400,"message":"Missing parameters","details":"StreetId","error":"bad request"}
400 Le code pays n'est pas un ISO 3166-1 alpha-3 valide
{"status":400,"message":"Country doesn't exist","details":"JPNde","error":"bad request"}
401 Numéro de licence incorrect ou non autorisé
{"status":401,"message":"Your licence is not allowed to cover this functionnality","details":"WRONG LICENSE","error":"unauthorized_client"}

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