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.
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.
Exemple cURL
France - Recherche par code postal
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
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 |
Réponse
En cas de succès, l'API renvoie un objet JSON contenant un compteur Found et un tableau PostalCodes.
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)
Exemple de réponse - Japon (108-6390)
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.
l'église → l%27%C3%A9glise.Exemple cURL
France - CityId de l'étape funnelpostcode précédente
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
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
Exemple de réponse
Exemple de réponse - France (Rue de la Bienfaisance, 75008 Paris)
Exemple de réponse - Japon (三田, 108-6390)
Japon - CityId 402573_1086390, Langue=JP (Kanji)
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.
StreetId de la réponse funneladdress lorsque l'utilisateur sélectionne une voie. Contactez votre gestionnaire de compte DQE pour obtenir ces identifiants.Exemple cURL
France - StreetId de l'étape funneladdress précédente
Lorsque l'utilisateur n'a pas saisi de numéro de voie, transmettez un paramètre StreetNumber vide : &StreetNumber=
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
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.
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)
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é à