API Adresse — Autocomplétion ligne unique (RESTful)

Autocomplétion - Ligne unique - RESTful

Autocomplétion d'adresse en deux étapes via l'API RESTful. single renvoie des suggestions d'adresses classées à partir d'une saisie libre ; compl récupère les options de complément de bâtiment après que l'utilisateur a sélectionné une suggestion.

Flux d'autocomplétion en deux étapes

L'utilisateur saisit librement ; /single/ renvoie des suggestions classées en temps réel. Après sélection, /compl/ récupère les options de complément de bâtiment (noms de bâtiment, numéros d'étage, numéros d'appartement).

Étape 1/single/Autocomplétion en texte libre → Étape 2/compl/Détails du bâtiment et de l'appartement

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

single

Aller à Requête Paramètres Réponse Exemple Erreurs ▶ Tester l'API

Endpoint RESTful 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 porte un StreetId utilisé en entrée de compl pour la complétion du bâtiment.

Quand utiliser single Utilisez cet endpoint pour suggérer des adresses au fur et à mesure de la saisie de l'utilisateur. Il traite 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 livrable, utilisez plutôt CheckAddress. Voir le guide d'intégration →

Requête

GET et POST sont tous deux pris en charge.

{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.

La saisie de l'adresse doit être encodée en URL - ex. l'église → l%27%C3%A9glise.

GET POST

GEThttps://{SERVER_ADDRESS}/{VERSION}/single/?Address={INPUT}&Country={COUNTRY_CODE}&Licence={LICENCE_CODE}

Exemples cURL

France - saisie partielle

curl "https://{SERVER_ADDRESS}/v1/single/?Address=8%20rue%20Victor%20Hugo%20Levall&Country=FRA&Length=38&Limit=20&Version=1&Licence={LICENCE_CODE}"

Japon - Kanji, avec le paramètre Langue

curl "https://{SERVER_ADDRESS}/v1/single/?Address=108-6390&Country=JPN&Length=38&Langue=JP&Version=1&Licence={LICENCE_CODE}"

POSThttps://{SERVER_ADDRESS}/{VERSION}/single/

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}/v1/single/" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "Address=8+rue+Victor+Hugo+Levall" \
  -d "Country=FRA" \
  -d "Length=38" \
  -d "Limit=20" \
  -d "Version=1" \
  -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
Address	`{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 avec séparateur pipe requis - transmettez la chaîne brute telle que saisie.	Obligatoire
Country	`{COUNTRY_CODE}`	Code pays ISO 3166-1 alpha-3 délimitant la recherche d'adresse. Exemple : `FRA` ou `GBR`.	Obligatoire
Length	`{LENGTH}`	Longueur maximale en caractères des suggestions d'adresses renvoyées. 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
Limit	`{NB}`	Nombre maximal de suggestions d'adresses renvoyées. Par défaut : `20`.	Optionnel
Version	`1`	Lorsqu'il est défini à `1`, le type de voie est extrait de la clé `Street` et renvoyé dans un champ dédié `StreetType`. Sans ce paramètre, le type de voie reste inclus dans `Street` (ex. RUE DE LA PAIX) et `StreetType` est vide.	Optionnel
Langue	`{LANGUAGE}`	Filtre les résultats par langue/écriture (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, la réponse est un objet JSON avec deux clés de premier niveau : Found (entier) et Addresses (tableau d'objets suggestion d'adresse, jusqu'à Limit éléments). 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. Addresses[0] est la meilleure correspondance ; les éléments suivants du tableau sont des candidats alternatifs. Le champ Label contient la chaîne prête à afficher pour votre liste déroulante d'autocomplétion - tout le reste vous fournit les composants structurés pour remplir les champs du formulaire.

Premier niveau

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

Objet suggestion d'adresse - `Addresses[n]`

Clé	Description	France	International
Label	Chaîne prête à afficher 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 notes d'utilisation. Utilisez `Label` uniquement pour remplir la liste déroulante de suggestions - jamais pour stocker l'adresse. Voir le guide d'intégration →	String (255)	String (255)
Street	Nom de la rue.	String (38)	String (150)
StreetType	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 `Street` et renvoyé ici à la place.	String (20)	String (20)
StreetNumber	Numéro de rue complet, y compris tout complément (bis, ter, etc.).	String (38)	String (38)
StreetNumberOnly	Numéro de rue seul, sans aucun complément (bis, ter, etc.).	String (4)	String (4)
StreetNumberListCount	Lorsque le numéro recherché n'est pas trouvé 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
IsValidStreetNumber	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
StreetNumberList	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 n'est pas trouvé ; ne contient que le numéro correspondant sinon.	String (1024)	String (1024)
StreetId	Identifiant unique de la rue. Utilisé en entrée de compl.	String (20)	String (20)
PostalCode	Code postal de l'adresse.	String (10)	String (10)
City	Nom de la ville.	String (38)	String (50)
Hamlet	Lieu-dit ou hameau nommé (France) ou champ équivalent au niveau du quartier (international). Disponibilité variable selon le pays.	String (38)	String (50)
SubLocality	Sous-localité (quartier, arrondissement, banlieue).	Empty	String (50)
SpecialDistribution	Non utilisé. Toujours renvoyé sous forme de chaîne vide.	String	String
CityId	Identifiant unique de la ville (code INSEE pour la France).	String (20)	String (20)
StateCode	Code ISO de l'État ou région administrative (ex. `17` pour le Japon).	Empty	String (50)
StateLabel	Libellé ISO de l'État ou région administrative (ex. `ISHIKAWA` pour le Japon).	Non disponible	String (50)
AdministrativeArea	Comté ou niveau administratif équivalent.	Empty	String (50)
Suburb	Banlieue ou quartier.	Empty	String (50)
AdditionalAddress	Informations complémentaires d'adresse (nom de bâtiment, étage, etc.). Disponibilité variable selon le pays - voir le guide d'intégration.	Empty	String (50)
Company	Nom de l'entreprise associée à l'adresse.	String (38)	String (38)
Input	Forme normalisée de l'adresse soumise. Peut différer de la saisie d'origine en casse ou en mise en forme. Non renseigné pour tous les pays.	String (255)	String (255)
Country	Code pays ISO 3166-1 alpha-3.	String (3)	String (3)
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é 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"

{
  "Found": 1,
  "Addresses": [
    {
      "PostalCode":           "NW10 7TJ",
      "City":                 "LONDON",
      "Hamlet":               "",
      "SpecialDistribution":  "",
      "Country":              "GBR",
      "StateCode":            "",
      "SubLocality":          "",
      "CityId":               "1745994",
      "Input":                "ABBEY ROAD NW10 7TJ LONDON",
      "Label":                "Abbey Road (West London Waste)|NW10 7TJ LONDON",
      "AdditionalAddress":    "",
      "StreetNumber":         "",
      "StreetType":           "",
      "Street":               "Abbey Road",
      "StreetId":             "7831549_NW107TJ",
      "IsValidStreetNumber":  1,
      "StreetNumberListCount":0,
      "StreetNumberList":     "",
      "StreetNumberOnly":     "",
      "StateLabel":           "",
      "AdministrativeArea":   "",
      "Suburb":               "",
      "Company":              "West London Waste",
      "Latitude":             "",
      "Longitude":            "" }
  ]
}

Japon - saisie "三田", Langue=JP

{
  "Found": 20,
  "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":            "" },
    {
      "PostalCode":           "942-0054",
      "City":                 "上越市",
      "Hamlet":               "",
      "SpecialDistribution":  "",
      "Country":              "JPN",
      "StateCode":            "15",
      "SubLocality":          "",
      "CityId":               "387092",
      "Input":                "三田",
      "Label":                "〒942-0054 新潟県上越市三田",
      "AdditionalAddress":    "",
      "StreetNumber":         "",
      "StreetType":           "",
      "Street":               "三田",
      "StreetId":             "537719",
      "IsValidStreetNumber":  1,
      "StreetNumberListCount":0,
      "StreetNumberList":     "",
      "StreetNumberOnly":     "",
      "StateLabel":           "新潟県",
      "AdministrativeArea":   "上越市",
      "Suburb":               "",
      "Company":              "",
      "Latitude":             "",
      "Longitude":            "" }
    // ... 18 autres résultats
  ]
}

Erreurs

L'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 `Licence` manquant	{"status":400,"message":"Missing parameters","details":"Licence","error":"bad request"}
400	Paramètre `Licence` vide	{"status":400,"message":"Licence must be filled","details":"Empty","error":"bad request"}
401	Numéro de licence incorrect	{"status":401,"message":"Your licence is not allowed to cover this functionnality","details":"{WRONG}","error":"unauthorized_client"}
400	Paramètre `Address` manquant	{"status":400,"message":"Missing parameters","details":"Address","error":"bad request"}
400	Paramètre `Country` manquant	{"status":400,"message":"Missing parameters","details":"Country","error":"bad request"}
400	Paramètre `Country` vide	{"status":400,"message":"Country must be filled","details":"Empty","error":"bad request"}
400	Erreur de frappe dans le nom d'un paramètre	{"status":400,"message":"Missing parameters","details":"Address","error":"bad request"}

Tester l'API

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

Ouvrir la console

compl

Aller à Requête Paramètres Réponse Exemple Erreurs ▶ Tester l'API

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 single, 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.

Quand utiliser compl Utilisez compl après que l'utilisateur a sélectionné une rue depuis single. Transmettez les StreetId et StreetNumber renvoyés par single pour obtenir des options de complément de bâtiment détaillées. Si aucune option de complément de bâtiment n'existe pour l'adresse, aucune entrée numérotée n'est renvoyée.

Requête

GET et POST sont tous deux pris en charge.

{SERVER_ADDRESS}, {VERSION} et {LICENCE_CODE} sont fournis par DQE lors de la création du compte. {STREETID} est obtenu à partir de la réponse de single. Contactez votre gestionnaire de compte DQE pour obtenir ces identifiants.

GET POST

GEThttps://{SERVER_ADDRESS}/{VERSION}/compl/?StreetId={STREETID}&StreetNumber={STREETNUMBER}&Country={COUNTRY_CODE}&Licence={LICENCE_CODE}

Exemple cURL

France

curl "https://{SERVER_ADDRESS}/v1/compl/?StreetId=1454602&StreetNumber=20&Country=FRA&Licence={LICENCE_CODE}"

POSThttps://{SERVER_ADDRESS}/{VERSION}/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

France

curl -X POST "https://{SERVER_ADDRESS}/v1/compl/" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "StreetId=1454602" \
  -d "StreetNumber=20" \
  -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
StreetId	`{STREETID}`	Identifiant unique de la rue renvoyé par single dans le champ `StreetId`.	Obligatoire
StreetNumber	`{STREETNUMBER}`	Numéro de rue sélectionné par l'utilisateur - correspond au champ `StreetNumber` de la réponse single.	Obligatoire
Country	`{COUNTRY_CODE}`	Code pays ISO 3166-1 alpha-3 délimitant la recherche d'adresse. Exemple : `FRA` ou `GBR`.	Obligatoire
Length	`{LENGTH}`	Longueur maximale en caractères des 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
Search	`{SEARCH}`	Pour les États-Unis : filtre les suggestions de compléments selon ce que l'utilisateur a saisi. 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, la réponse est un objet JSON avec deux clés de premier niveau : Found et AdditionalAddresses (tableau), ainsi qu'un objet Geolocalisation. La couverture de géocodage varie selon le pays - voir Couverture géographique.

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

Clé	Description	France	International
Found	Nombre de compléments d'adresse trouvés.	Integer	Integer
AdditionalAddresses	Tableau d'objets complément d'adresse.	Array	Array
AdditionalAddresses[0]. AdditionalAddress	Libellé du complément d'adresse (nom de bâtiment, étage, appartement, etc.).	String (38)	String (150)
AdditionalAddresses[0]. PostalCode	Code postal spécifique à cette sous-unité, lorsqu'il est disponible (ex. ZIP+4 pour les USA).	Empty	String (10)
Geolocalisation	Informations de géolocalisation de l'adresse.	Object	Object
Geolocalisation. Latitude	Géocoordonnées de l'adresse correspondante. Non disponible pour tous les pays - voir la couverture.	String	String
Geolocalisation. Longitude	Géocoordonnées de l'adresse correspondante. Non disponible pour tous les pays - voir la couverture.	String	String

Exemple de réponse

France

{
  "Found": 5,
  "AdditionalAddresses": [
    { "AdditionalAddress": "BATIMENT A", "PostalCode": "" },
    { "AdditionalAddress": "BATIMENT B", "PostalCode": "" },
    { "AdditionalAddress": "BATIMENT C", "PostalCode": "" },
    { "AdditionalAddress": "BATIMENT D", "PostalCode": "" },
    { "AdditionalAddress": "BATIMENT E", "PostalCode": "" }
  ],
  "Geolocalisation": {
    "Latitude":  "48.879024",
    "Longitude": "2.333291" }
}

Erreurs

HTTP	Type d'erreur	Corps de la réponse
400	Paramètre `StreetId` manquant	{"status":400,"message":"Missing parameters","details":"StreetId","error":"bad request"}
400	Paramètre `StreetNumber` manquant	{"status":400,"message":"Missing parameters","details":"StreetNumber","error":"bad request"}
400	Paramètre `Country` manquant	{"status":400,"message":"Missing parameters","details":"Country","error":"bad request"}
400	Paramètre `Licence` manquant	{"status":400,"message":"Missing parameters","details":"Licence","error":"bad request"}
401	Client non autorisé (licence invalide, expirée ou hors périmètre)	{"status":401,"message":"Your licence is not allowed to cover this functionnality","details":"{INVALID_LICENCE}","error":"unauthorized_client"}

Tester l'API

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

Ouvrir la console

API Adresse — Autocomplétion ligne unique (RESTful)

single

Requête

Exemples cURL

Exemple cURL

Paramètres

Réponse

Premier niveau

Objet suggestion d'adresse - `Addresses[n]`

Exemple de réponse

Erreurs

Tester l'API

compl

Requête

Exemple cURL

Exemple cURL

Paramètres

Réponse

Exemple de réponse

Erreurs

Tester l'API

Voir aussi

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

Previous article

Next article

single

Requête

Exemples cURL

Exemple cURL

Paramètres

Réponse

Premier niveau

Objet suggestion d'adresse - Addresses[n]

Exemple de réponse

Erreurs

Tester l'API

compl

Requête

Exemple cURL

Exemple cURL

Paramètres

Réponse

Exemple de réponse

Erreurs

Tester l'API

Voir aussi

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

Previous article

Next article

Objet suggestion d'adresse - `Addresses[n]`