Autocomplétion - Ligne unique - API Standard
Autocomplétion d'adresse en deux étapes utilisant l'API classique. SINGLEV2 renvoie une liste classée de suggestions d'adresses à partir d'une saisie libre ; COMPLV2 récupère les options de sous-bâtiment après que l'utilisateur a sélectionné une suggestion.
Flux d'autocomplétion en deux étapes
L'utilisateur saisit librement ; SINGLEV2 renvoie des suggestions classées en temps réel. Après sélection, COMPLV2 récupère les options de sous-bâtiment (noms de bâtiment, numéros d'étage, numéros d'appartement).
Casse de la sortie - La casse suit la norme postale du pays concerné.
SINGLEV2
Point de terminaison API standard pour l'autocomplétion d'adresse. Accepte une saisie libre partielle ou complète et renvoie une liste classée de suggestions d'adresses. Chaque suggestion contient un IDVoie utilisé en entrée de COMPLV2 pour la complétion du sous-bâtiment.
Quand utiliser SINGLEV2 Utilisez ce point de terminaison pour suggérer des adresses au fur et à mesure de la saisie de l'utilisateur. Il gère les saisies partielles (fragment de rue, code postal, nom de ville) et renvoie tous les champs structurés prêts à remplir un formulaire. Pour vérifier qu'une adresse déjà complète est valide et délivrable, utilisez plutôt RNVP. Voir le guide d'intégration →
Requête
Les méthodes GET et POST sont toutes deux prises en charge.
{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.
La saisie de l'adresse doit être encodée en URL - ex.
l'église → l%27%C3%A9glise. GEThttps://{SERVER_ADDRESS}/SINGLEV2/?Adresse={INPUT}&Pays={COUNTRY_CODE}&Licence={LICENCE_CODE}
Exemples cURL
France - saisie partielle
curl "https://{SERVER_ADDRESS}/SINGLEV2/?Adresse=8%20rue%20Victor%20Hugo%20Levall&Pays=FRA&Licence={LICENCE_CODE}&Taille=38&NbMax=20&Version=1"
Japon - Kanji, avec le paramètre Langue
curl "https://{SERVER_ADDRESS}/SINGLEV2/?Adresse=108-6390&Pays=JPN&Taille=38&Langue=JP&Version=1&Licence={LICENCE_CODE}"
POSThttps://{SERVER_ADDRESS}/SINGLEV2/
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
France - saisie partielle
curl -X POST "https://{SERVER_ADDRESS}/SINGLEV2/" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "Adresse=8+rue+Victor+Hugo+Levall" \
-d "Pays=FRA" \
-d "Licence={LICENCE_CODE}" \
-d "Taille=38" \
-d "NbMax=20" \
-d "Version=1"
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 |
| Adresse | {INPUT} |
Chaîne d'adresse en texte libre saisie par l'utilisateur. Accepte une saisie partielle - fragment de rue, numéro de rue, code postal ou nom de ville. Doit être encodée en URL. Aucun format à séparateur requis - transmettez la chaîne brute telle que saisie. | Obligatoire |
| Pays | {COUNTRY_CODE} |
Code pays ISO 3166-1 alpha-3 définissant la portée de la recherche d'adresse. Exemple : FRA ou GBR. |
Obligatoire |
| Taille | {LENGTH} |
Longueur maximale en caractères des suggestions d'adresses renvoyées. S'applique uniquement aux adresses en caractères latins. Une valeur trop faible peut tronquer les résultats. Par défaut : 38. Minimum recommandé : 32. |
Optionnel |
| NbMax | {NB} |
Nombre maximal de suggestions d'adresses renvoyées. Par défaut : 20. |
Optionnel |
| Version | 1 |
Lorsqu'il est défini sur 1, le type de voie est extrait de la clé Voie et renvoyé dans un champ dédié TypeVoie. Sans ce paramètre, le type de voie reste inclus dans Voie (ex. RUE DE LA PAIX) et TypeVoie est vide. |
Optionnel |
| Instance | {INSTANCE} |
Non renvoyé dans les résultats pour ce point de terminaison - peut être omis sans risque. | Optionnel |
| Langue | {LANGUAGE} |
Filtre les résultats par langue/script (ex. JPN : JP = Kanji · JK = Katakana · EN = Romanisé). Voir le guide des langues. |
Optionnel |
| Filter | {FILTER} |
France uniquement. Filtre les adresses CEDEX : 1 toutes les adresses ; 2 non-CEDEX uniquement ; 3 CEDEX uniquement. |
Optionnel |
Réponse
En cas de succès, l'API renvoie un objet JSON. Les clés sont des numéros de rang de "1" à "n", chacun correspondant à un dictionnaire de champs d'adresse. Le premier résultat est la correspondance la plus proche de la saisie.
Lecture métier : Considérez la réponse comme une liste classée de suggestions d'adresses.
"1" est la meilleure correspondance ; les numéros supérieurs sont des candidats alternatifs. Le champ label contient la chaîne prête à afficher pour votre menu déroulant d'autocomplétion - tout le reste fournit les composants structurés permettant de remplir les champs du formulaire.| Clé | Description | France | International |
|---|---|---|---|
| label | Chaîne prête à afficher pour un menu déroulant 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 notes d'utilisation.
Utilisez
label uniquement pour remplir le menu déroulant de suggestions - jamais pour stocker l'adresse. Voir le guide d'intégration →
|
String (255) | String (255) |
| Voie | Nom de la rue. | String (38) | String (150) |
| TypeVoie | Type de voie (ex. RUE, AVENUE, BOULEVARD). Renseigné uniquement lorsque Version=1 est défini - dans ce cas, le type de voie est retiré de Voie et renvoyé ici à la place. |
String (20) | String (20) |
| Numero | Numéro de rue complet, complément inclus (bis, ter, etc.). | String (38) | String (38) |
| Num | Alias de Numero. Conservé pour compatibilité - privilégiez Numero. |
String (38) | String (38) |
| NumSeul | Numéro de rue seul, sans complément (bis, ter, etc.). | String (4) | String (4) |
| NbNumero aussi : Nbnumero |
Lorsque le numéro recherché est introuvable ou absent, renvoie le nombre total de numéros de rue valides pour cette rue. Peut être une chaîne vide pour certaines adresses internationales où cette donnée n'est pas disponible. | String | String |
| 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. Renvoie une chaîne vide pour certaines adresses internationales où la validation au niveau du numéro n'est pas disponible. |
Integer | Integer |
| ListeNumero | Liste des 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 est introuvable ; ne contient que le numéro correspondant dans le cas contraire. | String (1024) | String (1024) |
| IDVoie aussi : CodeVoie |
Identifiant unique de la rue. Utilisé en entrée de COMPLV2. CodeVoie est conservé pour compatibilité. Privilégiez IDVoie dans les nouvelles intégrations. | String (20) | String (20) |
| CodePostal | Code postal de l'adresse. | String (10) | String (10) |
| Localite | Nom de la ville. | String (38) | String (50) |
| SousLocalite | Sous-localité (quartier, arrondissement, banlieue). | Vide | String (50) |
| LieuDit | Lieu-dit ou hameau nommé (France) ou champ équivalent au niveau du quartier (international). La disponibilité varie selon le pays. | String (38) | String (50) |
| IDLocalite | Identifiant unique de la ville (code INSEE pour la France). | String (20) | String (20) |
| 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 | Informations régionales ou administratives complémentaires. | Non disponible | String (50) |
| Suburb | Banlieue ou quartier. | Non disponible | String (50) |
| Complement | Informations complémentaires sur l'adresse (nom du bâtiment, étage, etc.). La disponibilité varie selon le pays - voir le guide d'intégration. | Vide | String (50) |
| Complement2 | Seconde ligne de sous-bâtiment. Renseigné pour certaines adresses internationales lorsqu'un identifiant de bâtiment et un identifiant de sous-bâtiment (étage, appartement, suite) sont disponibles comme entrées distinctes, ainsi que pour certaines adresses CEDEX organisationnelles. | Non disponible | String (50) |
| Entreprise | Nom de l'entreprise associée à l'adresse. | String (38) | String (38) |
| Thoroughfare | Voie secondaire (dependent street). | Non disponible | Royaume-Uni uniquement |
| Pays | Code pays ISO 3166-1 alpha-3. | String (3) | String (3) |
| Latitude | Coordonnées géographiques de l'adresse correspondante. Non disponible pour tous les pays - voir la couverture. | Non disponible | String |
| Longitude | Coordonnées géographiques de l'adresse correspondante. Non disponible pour tous les pays - voir la couverture. | Non disponible | String |
| Saisie | Forme normalisée de l'adresse soumise. Peut différer de la saisie d'origine en casse ou en formatage. Non renseigné pour tous les pays. | String (255) | String (255) |
| Instance | Champ interne. | Vide | String |
Renseigné avec Version=1
Rue sélectionnée sans numéro ? Voir le guide d'intégration →
Exemple de réponse
Royaume-Uni - saisie "Abbey Road NW10 7TJ London"
{
"1": {
"label": "Abbey Road (West London Waste)|NW10 7TJ LONDON",
"valid_num": 1,
"Num": "",
"Numero": "",
"ListeNumero": "",
"Nbnumero": 0,
"NbNumero": 0,
"NumSeul": "",
"Saisie": "ABBEY ROAD NW10 7TJ LONDON",
"Pays": "GBR",
"Complement": "",
"Voie": "Abbey Road",
"CodeVoie": "7831549_NW107TJ",
"IDVoie": "7831549_NW107TJ",
"IDLocalite": "1745994",
"Instance": 1,
"CodePostal": "NW10 7TJ",
"Localite": "LONDON",
"Province": "",
"LieuDit": "",
"Longitude": "",
"Latitude": "",
"Suburb": "",
"TypeVoie": "",
"Entreprise": "West London Waste",
"Thoroughfare": ""
}
}
Japon - saisie "三田", Langue=JP
{
"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": ""
},
"2": {
"label": "〒942-0054 新潟県上越市三田",
"valid_num": 1,
"Num": "",
"Numero": "",
"ListeNumero": "",
"Nbnumero": 0,
"NbNumero": 0,
"NumSeul": "",
"Saisie": "三田",
"Pays": "JPN",
"Complement": "",
"Voie": "三田",
"CodeVoie": "537719",
"IDVoie": "537719",
"IDLocalite": "387092",
"Instance": 1,
"CodePostal": "942-0054",
"Localite": "上越市",
"Province": "15",
"LieuDit": "",
"Longitude": "",
"Latitude": "",
"Region1": "新潟県",
"Region2": "上越市",
"Region3": "",
"Suburb": "",
"TypeVoie": ""
}
// ... 18 résultats supplémentaires
}
Erreurs
| HTTP | Type d'erreur | Corps de la réponse |
|---|---|---|
| 400 | Manquant ou vide : Licence
|
Bad Request Parameters empty fields |
| 401 | Clé de licence invalide ou non autorisée | unauthorized_client |
| 400 | Manquant ou vide : Adresse
|
Bad Request Parameters empty fields |
| 400 | Manquant ou vide : Pays
|
Bad Request Parameters empty fields |
| 400 | Nom de paramètre non reconnu (ex. faute de frappe dans Adresse) |
Bad Request Parameters empty fields |
Tester l'API
Cliquez sur le bouton ci-dessous pour tester ce point de terminaison en direct dans votre navigateur.
Ouvrir la console
COMPLV2
Seconde étape de l'approche en ligne unique. À partir d'un identifiant de rue et d'un numéro de rue sélectionnés dans un résultat SINGLEV2, renvoie une liste de suggestions de sous-bâtiment : noms de bâtiment, numéros d'étage, noms d'entreprise, numéros d'appartement.
Quand utiliser COMPLV2 Utilisez COMPLV2 après que l'utilisateur a sélectionné une rue depuis SINGLEV2. Transmettez les valeurs
IDVoie et IDNum renvoyées par SINGLEV2 pour obtenir des options de sous-bâtiment détaillées. Si aucune option de sous-bâtiment n'existe pour l'adresse, aucune entrée numérotée n'est renvoyée.Requête
Les méthodes GET et POST sont toutes deux prises en charge.
{SERVER_ADDRESS} et {LICENCE_CODE} sont fournis par DQE lors de la création du compte. {STREET_ID} est obtenu à partir de la réponse de SINGLEV2. Contactez votre chargé de compte DQE pour obtenir ces identifiants.
GEThttps://{SERVER_ADDRESS}/COMPLV2/?IDVoie={STREET_ID}&IDNum={NUM}&Pays={COUNTRY_CODE}&Licence={LICENCE_CODE}
Exemple cURL
France
curl "https://{SERVER_ADDRESS}/COMPLV2/?IDVoie=1454602&IDNum=20&Pays=FRA&Licence={LICENCE_CODE}"
POSThttps://{SERVER_ADDRESS}/COMPLV2/
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
France
curl -X POST "https://{SERVER_ADDRESS}/COMPLV2/" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "IDVoie=1454602" \
-d "IDNum=20" \
-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 la rue renvoyé par SINGLEV2 dans le champ IDVoie ou CodeVoie. |
Obligatoire |
| IDNum | {STREETNUMBER} |
Numéro de rue sélectionné par l'utilisateur - correspond au champ Numero de la réponse SINGLEV2. |
Obligatoire |
| Pays | {COUNTRY_CODE} |
Code pays ISO 3166-1 alpha-3 définissant la portée de la recherche d'adresse. Exemple : FRA ou GBR. |
Obligatoire |
| Taille | {LENGTH} |
Longueur maximale en caractères des champs d'adresse renvoyés. S'applique uniquement aux adresses en caractères latins. Une valeur trop faible peut tronquer les résultats. Par défaut : 38. Minimum recommandé : 32. |
Optionnel |
| Filter | {FILTER} |
Pour les États-Unis : filtre les suggestions de complément selon la saisie de l'utilisateur. Transmettez le type de complément partiel saisi (ex. FL, STE, RM) - seules les entrées de complément correspondant à cette valeur sont renvoyées. |
Optionnel |
Réponse
En cas de succès, l'API renvoie un objet JSON avec deux types de clés. Les clés numérotées ("1" à "n") représentent chacune une option de sous-bâtiment. Les clés géographiques de premier niveau (Latitude, Longitude) donnent les coordonnées géographiques de l'adresse correspondante. La couverture du géocodage varie selon le pays - voir Couverture géographique.
L'absence de données de sous-bâtiment n'est pas une erreur. Voir le guide d'intégration →
| Clé | Description | France | International |
|---|---|---|---|
| Entrées numérotées ("1" à "n") - une par option de sous-bâtiment | |||
| Batiment | Libellé d'adresse complémentaire (nom du bâtiment, étage, appartement, etc.). | String (38) | String (150) |
| CodePostal | Code postal spécifique à cette sous-unité, lorsqu'il est disponible (ex. ZIP+4 pour les États-Unis). | Non disponible | String (10) |
| Champs géographiques de premier niveau | |||
| Latitude | Coordonnées géographiques de l'adresse correspondante. Non disponible pour tous les pays - voir la couverture. | String | String |
| Longitude | Coordonnées géographiques de l'adresse correspondante. Non disponible pour tous les pays - voir la couverture. | String | String |
| Premier niveau - optionnel, France uniquement (nécessite un abonnement Iris/Ilot) | |||
| Status_IrisIlot | Source des codes IRIS/Îlot (ex. INSEE). |
String (5) | Non disponible |
| ilot | Code îlot. | String (9) | Non disponible |
| iris | Code IRIS. | String (9) | Non disponible |
Exemple de réponse
France
{
"1": { "Batiment": "BATIMENT A" },
"2": { "Batiment": "BATIMENT B" },
"3": { "Batiment": "BATIMENT C" },
"4": { "Batiment": "BATIMENT D" },
"5": { "Batiment": "BATIMENT E" },
"Latitude": "48.879024",
"Longitude": "2.333291"
}
Erreurs
| HTTP | Type d'erreur | Corps de la réponse |
|---|---|---|
| 400 | Manquant ou vide : Licence
|
Bad Request Parameters empty fields |
| 500 | Clé de licence invalide ou non autorisée |
{} (objet JSON vide) |
| 400 | Manquant : IDVoie
|
400 Bad Request |
| 400 | Manquant : Pays
|
400 Bad Request |
| 400 | Faute de frappe dans le nom du paramètre (clé non reconnue) | 400 Bad Request |
Tester l'API
Cliquez sur le bouton ci-dessous pour tester ce point de terminaison en direct dans votre navigateur.
Ouvrir la console
Voir aussi
Associé à