TrustyData Docs
Site Tarifs Contact

Adresses

Formulaire d'inscription, fiche CRM, fichier importé : une partie des adresses saisies contient une coquille ou n'existe pas. Ces quatre endpoints couvrent le cycle complet : suggérer pendant la frappe, vérifier après saisie, consulter une fiche, chercher autour d'un point.

Endpoint Quand l'utiliser Plan minimum
GET /address/autocomplete Champ de saisie interactif — suggestions au fil de la frappe Discovery
POST /address/verify Adresse déjà saisie (formulaire, CRM, import) — obtenir un verdict Discovery
GET /address/view/{id} Re-consulter une fiche déjà résolue, sans repasser par une recherche Discovery
GET /address/proximity Adresses de la BAN présentes autour d'un point (rayon en mètres) Growth

Trois lignes prêtes à écrire

Les quatre endpoints ci-dessus renvoient l'adresse deux fois : en champs atomiques (numero, rep, nom_voie…) et en trois lignes déjà composées, au format attendu par un formulaire, une étiquette ou une fiche CRM. Ces trois lignes sortent sur tous les plans, Discovery compris.

Champ Composition Exemple
ligne_voie numero + rep + nom_voie 215 B Chemin des Acacias
ligne_complement nom_ld Les Grandes Terres
ligne_commune code_postal + nom_commune 01600 Sainte-Euphémie

Préférez ces lignes à une concaténation faite chez vous : elles absorbent les cas qui font sortir un espace en trop ou un code postal amputé. rep est vide dans la grande majorité des adresses de la BAN — seuls les composants renseignés sont assemblés, avec un espace simple, donc 215 Chemin des Acacias et non 215  Chemin des Acacias. De même, ligne_commune conserve toujours le zéro initial d'un code postal de l'Ain, de Corse ou d'outre-mer.

Une ligne vide vaut null, mais le champ reste là

Quand aucun composant n'est renseigné, la ligne vaut null — jamais une chaîne vide. Les trois champs sont en revanche toujours présents dans la réponse, y compris avec details=false : la forme ne change pas d'un plan à l'autre, donc un mapping qui les consomme ne casse pas quand l'abonnement évolue.

En pratique, ligne_complement est vide la plupart du temps : la BAN place généralement le lieu-dit dans nom_voie (par exemple "nom_voie": "Lieu-dit Les Grandes Terres" avec "nom_ld": ""). Prévoyez une ligne 2 qui peut ne rien porter plutôt qu'un gabarit à trois lignes obligatoires.

GET /address/autocomplete — suggestions en direct

Branchez cet endpoint sur un champ de saisie : à chaque frappe, il retourne des suggestions classées par pertinence pour guider l'utilisateur vers une adresse qui existe réellement dans la BAN. 

curl -H "Authorization: Bearer VOTRE_CLE_API" \
  "https://api.trustydata.app/services/v1/address/autocomplete?q=32+bis+rue+de+labbeville"
{
  "status": "OK",
  "message": "",
  "suggestions": [
    {
      "score": 0.99,
      "adresse": "32 bis Rue de Labbeville, 95690 Nesles-la-Vallée",
      "ligne_voie": "32 bis Rue de Labbeville",
      "ligne_complement": null,
      "ligne_commune": "95690 Nesles-la-Vallée",
      "id": "9fdb209a-6862-4d1c-8ad7-aea35bd2cbd0",
      "numero": "32",
      "rep": "bis",
      "nom_voie": "Rue de Labbeville",
      "code_postal": "95690",
      "nom_commune": "Nesles-la-Vallée",
      "code_insee": "95446",
      "id_ban": "95446_0440_00032_bis",
      "position": {
        "lat": 49.130633,
        "lon": 2.163253,
        "x": 638928.82,
        "y": 6892638.86,
        "type_position": "segment"
      },
      "geocoding": {
        "iris": "0000",
        "code_iris": "954460000",
        "nom_iris": "Nesles-la-Vallée",
        "type_iris": "Z"
      },
      "statistical_grid": { "…": "…" }
    }
  ]
}

Réponse obtenue en plan Business : position (dès Starter), geocoding (dès Growth) et statistical_grid (dès Business — tronqué ici, une trentaine d'indicateurs INSEE Filosofi) s'ajoutent progressivement selon le plan. Le champ score (0 à 1) indique la confiance du rapprochement ; pour la suggestion retenue, stockez id_ban (l'identifiant stable du référentiel BAN) plutôt que id, qui n'est qu'un identifiant technique côté TrustyData.

POST /address/verify — vérifier une adresse déjà saisie

Quand l'utilisateur a déjà validé une adresse — un formulaire soumis, une fiche CRM, une ligne de fichier importé — vérifiez-la en un appel : la réponse retourne un verdict explicite plutôt qu'une simple liste de candidats. 

curl -X POST "https://api.trustydata.app/services/v1/address/verify" \
  -H "Authorization: Bearer VOTRE_CLE_API" \
  -H "Content-Type: application/json" \
  -d '{"q":"10 av Champs Elysee Paris"}'
{
  "status": "success",
  "message": "",
  "matches": [
    {
      "score": 0.883,
      "verdict": "match_probable",
      "adresse": "10 Avenue des Champs Elysées, 75008 Paris 8e Arrondissement",
      "ligne_voie": "10 Avenue des Champs Elysées",
      "ligne_complement": null,
      "ligne_commune": "75008 Paris 8e Arrondissement",
      "id": "f9141266-72d0-4f7b-a3a1-f5e97af95e92",
      "numero": "10",
      "nom_voie": "Avenue des Champs Elysées",
      "code_postal": "75008",
      "nom_commune": "Paris 8e Arrondissement",
      "code_insee": "75108",
      "id_ban": "75108_1733_00010",
      "position": {
        "lat": 48.867887,
        "lon": 2.315269,
        "x": 649770.24,
        "y": 6863313.14,
        "type_position": "parcelle"
      },
      "geocoding": {
        "iris": "2907",
        "code_iris": "751082907",
        "nom_iris": "Concorde Jardin Champs Élysées",
        "type_iris": "D"
      },
      "statistical_grid": { "…": "…" }
    }
  ]
}

Réponse obtenue en plan Business (mêmes paliers que ci-dessus pour position, geocoding, statistical_grid). Le verdict prime sur le score : match_exact signale une correspondance fiable, à accepter directement ; match_probable — comme ici, pour une saisie abrégée et sans accent (« av », « Elysee ») — signale un candidat plausible, à confirmer avant d'écraser la donnée d'origine. Comme pour l'autocomplétion, stockez id_ban, pas id.

GET /address/view/{id} — consulter une fiche stockée

Pour re-consulter plus tard une fiche déjà résolue — par exemple ré-afficher le détail d'une adresse enregistrée en base sans repasser par une recherche — utilisez l'identifiant id renvoyé par autocomplete ou verify. 

curl -H "Authorization: Bearer VOTRE_CLE_API" \
  "https://api.trustydata.app/services/v1/address/view/9fdb209a-6862-4d1c-8ad7-aea35bd2cbd0"
{
  "adresse": "32 bis Rue de Labbeville, 95690 Nesles-la-Vallée",
  "ligne_voie": "32 bis Rue de Labbeville",
  "ligne_complement": null,
  "ligne_commune": "95690 Nesles-la-Vallée",
  "id": "9fdb209a-6862-4d1c-8ad7-aea35bd2cbd0",
  "numero": "32",
  "rep": "bis",
  "nom_voie": "Rue de Labbeville",
  "code_postal": "95690",
  "nom_commune": "Nesles-la-Vallée",
  "code_insee": "95446",
  "id_ban": "95446_0440_00032_bis",
  "position": {
    "lat": 49.130633,
    "lon": 2.163253,
    "x": 638928.82,
    "y": 6892638.86,
    "type_position": "segment"
  },
  "geocoding": {
    "iris": "0000",
    "code_iris": "954460000",
    "nom_iris": "Nesles-la-Vallée",
    "type_iris": "Z"
  },
  "statistical_grid": { "…": "…" }
}

Réponse obtenue en plan Business. La fiche n'a pas d'enveloppe status/matches : elle reprend directement les champs de l'adresse, avec le même enrichissement progressif par plan que les deux endpoints précédents.

GET /address/proximity — chercher autour d'un point

Pour lister les adresses de la BAN présentes autour d'un point — zone de chalandise, rayon d'intervention, adresses voisines d'un point de vente — passez une adresse libre ou des coordonnées, et un rayon en mètres. 

curl -G "https://api.trustydata.app/services/v1/address/proximity" \
  -H "Authorization: Bearer VOTRE_CLE_API" \
  --data-urlencode "adresse=1 rue de la Paix 75002 Paris" \
  --data-urlencode "rayon=300"
{
  "point_central": {
    "lat": 48.868546,
    "lon": 2.33031,
    "adresse_resolue": "1 Rue de la Paix, 75002 Paris 2e Arrondissement",
    "id": "235150cf-5b6c-4f9f-879f-002ec6dbe9fd"
  },
  "resultats": [
    {
      "adresse": "1 Rue de Caumartin, 75009 Paris 9e Arrondissement",
      "ligne_voie": "1 Rue de Caumartin",
      "ligne_complement": null,
      "ligne_commune": "75009 Paris 9e Arrondissement",
      "id": "b98c89a3-dd78-4503-9901-04059077f359",
      "id_ban": "75109_1617_00001",
      "distance_m": 259,
      "position": { "…": "…" },
      "geocoding": { "…": "…" },
      "statistical_grid": { "…": "…" }
    },
    { "…": "…" }
  ],
  "pagination": {
    "offset": 0,
    "limit": 10,
    "total_estime": 538,
    "tronque": false,
    "next_offset": 10
  }
}

Réponse tronquée, obtenue en plan Business (page de 10 résultats via l'outil interne utilisé pour cet exemple — les 9 suivants ont la même structure que le premier ; un appel HTTP direct sans paramètre limit pagine par défaut sur 100). Les résultats sont triés par distance croissante (distance_m, en mètres à vol d'oiseau) et reprennent chacun la structure de view/{id}. La pagination est stateless : suivez pagination.next_offset jusqu'à null — elle s'arrête à l'offset 5 000 (pages de 100 par défaut, 200 au maximum) ; au-delà, ou si pagination.tronque vaut true, réduisez le rayon pour rester exhaustif.

Bonnes pratiques

Aucun résultat n'est un succès HTTP

status: "no_results" avec matches: [] est une réponse HTTP 200, pas une erreur — testez toujours status avant de lire matches[0]. Ci-dessous, la même requête verify avec une adresse qui n'existe pas : 

curl -X POST "https://api.trustydata.app/services/v1/address/verify" \
  -H "Authorization: Bearer VOTRE_CLE_API" \
  -H "Content-Type: application/json" \
  -d '{"q":"999 avenue Inexistante 99999 Villeneulle"}'
{
  "status": "no_results",
  "message": "No verified match found",
  "matches": []
}

Dans ce cas, renvoyez la saisie vers l'autocomplétion : proposer des suggestions à partir des premiers caractères valides aide l'utilisateur à corriger lui-même plutôt que de bloquer le formulaire sur une erreur muette.

Une adresse par requête

L'API traite une adresse par appel. Pour des volumes (qualification d'un fichier, dédoublonnage d'une base), intégrez-la dans un script ou un pipeline ETL côté client.

Richesse de la réponse par plan

La richesse de chaque réponse (autocomplete, verify, view, et chaque résultat de proximity) dépend du plan attaché à votre clé : position dès Starter, géocodage IRIS dès Growth, grille statistique INSEE Filosofi en Business — détail champ par champ dans Plans & quotas.

Prochains pas