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.
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.
Exemple cURL
France - Recherche par code postal
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
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 |
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.
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.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)
Exemple de réponse - Japon (108-6390)
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.
IDLocalite de la réponse CP lorsque l'utilisateur sélectionne une ville. Contactez votre chargé de compte DQE pour obtenir ces identifiants.Adresse doit être encodée en URL - ex. l'église → l%27%C3%A9glise.Exemple cURL
France - IDLocalite de l'étape CP précédente
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
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
Exemple de réponse
Exemple de réponse - France (Rue de la Bienfaisance, 75008 Paris)
Exemple de réponse - Japon (三田, 108-6390)
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.
IDVoie de la réponse ADR lorsque l'utilisateur sélectionne une voie. Contactez votre chargé de compte DQE pour obtenir ces identifiants.Exemple cURL
France - IDVoie de l'étape ADR précédente
Lorsque l'utilisateur n'a pas saisi de numéro de rue, transmettez un paramètre IDNum vide : &IDNum=
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
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.
| 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)
Exemple de réponse - International (GBR)
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é à