TrustyData Docs
Site Tarifs Contact

Mes lieux

Vos boutiques, restaurants, agences ou points de retrait — appelés ici des sites — vivent dans un référentiel qui vous appartient. Vous l'alimentez depuis votre système source, puis vous demandez à l'API quels sites se trouvent autour d'un point. C'est ce qui répond à « quel est mon point de vente le plus proche de ce prospect ? » sans que vous ayez à stocker des coordonnées ni à calculer des distances vous-même.

Un référentiel privé, pas un annuaire

/locations/* ne cherche que dans vos données. Rien n'y est mutualisé, rien n'en sort vers un autre compte, et aucun site n'y est ajouté par TrustyData. Pour chercher des établissements dans une base publique, voyez plutôt le guide Entreprises (SIRENE) ou Adresses (BAN).

Les endpoints en un coup d'œil

Endpoint Quand l'utiliser Plan minimum
GET /locations/search Trouver vos sites les plus proches d'un point, triés par distance Starter
GET /locations/referentiels
GET …/referentiels/{code}		 Lister vos référentiels, ou en consulter un Starter
POST /locations/referentiels
PATCH · DELETE		 Créer un référentiel, le renommer, l'archiver Starter
GET …/{code}/sites
GET …/sites/{id_externe}		 Lister les sites d'un référentiel, ou lire une fiche complète Starter
PUT …/sites/{id_externe}
PATCH · DELETE		 Écrire un site : remplacer, compléter, supprimer Starter
POST …/{code}/sites:lot Écrire jusqu'à 1 000 sites en un appel Starter
POST …/{code}/sites:sync Aligner le référentiel sur un export complet de votre système Starter
GET /locations/taches/{id} Relire le rapport d'une écriture en masse Starter

Le service entier s'ouvre à partir du plan Starter. Seul le filtre par étiquettes de /locations/search demande Growth. Le nombre de sites que vous pouvez stocker, lui, dépend du plan — voyez La capacité incluse dans votre plan.

Le modèle : des référentiels, des sites

Un référentiel est un ensemble de sites, identifié par un code court que vous choisissez (boutiques, agences, demo…). Ce code circule dans toutes les URLs et ne se modifie plus après création ; seul le nom affiché change. Un compte peut en tenir plusieurs — un par enseigne, par réseau ou par pays, par exemple.

Dans un référentiel, chaque site est identifié par son id_externe : votre identifiant, celui de votre ERP, de votre PIM ou de votre tableur. TrustyData ne fabrique pas de clé technique à rapprocher ensuite — c'est la vôtre qui sert d'adresse dans l'API, ce qui rend toutes les écritures idempotentes : rejouer le même export ne crée pas de doublon, il met à jour.

Un site porte une identité (nom public, nom interne, description), une adresse, une position, un fuseau horaire, des étiquettes libres, des contacts, des liens, des horaires hebdomadaires et leurs exceptions, plus un objet donnees libre où ranger ce que le modèle ne prévoit pas (surface, nombre de couverts, code d'enseigne…).

Alimenter un référentiel

Créez d'abord le référentiel, puis poussez les sites. Un site se fournit avec des coordonnées ou avec une adresse : dans le second cas, TrustyData la géocode pour vous (voir plus bas). 

curl -X POST "https://api.trustydata.app/services/v1/locations/referentiels" \
  -H "Authorization: Bearer VOTRE_CLE_API" \
  -H "Content-Type: application/json" \
  -d '{"code": "boutiques", "nom": "Nos boutiques"}'
curl -X PUT "https://api.trustydata.app/services/v1/locations/referentiels/boutiques/sites/PARIS-01" \
  -H "Authorization: Bearer VOTRE_CLE_API" \
  -H "Content-Type: application/json" \
  -d '{
    "nom_public": "Boutique Opéra",
    "ligne_voie": "12 rue Scribe",
    "code_postal": "75009",
    "commune": "Paris",
    "fuseau": "Europe/Paris",
    "tags": ["click-and-collect"]
  }'

PUT remplace, PATCH complète

Les deux verbes ne servent pas au même usage, et les confondre coûte des données :

  • PUT remplace intégralement la fiche. Tout champ absent du corps retombe à sa valeur par défaut, tout sous-objet absent disparaît. C'est le bon verbe quand votre système source fait autorité sur la fiche entière.
  • PATCH ne touche que ce que vous transmettez. Un sous-objet absent est laissé tel quel ; null efface explicitement un champ effaçable. C'est le bon verbe pour corriger un numéro de téléphone sans réécrire les horaires.

Le champ statut (actif / inactif) n'est accepté que par PATCH : un PUT ne réactive jamais tout seul un site que vous aviez retiré des recherches.

DELETE sur un site le supprime définitivement. Pour le sortir des recherches en gardant son historique, préférez PATCH avec {"statut": "inactif"}.

Écrire beaucoup de sites : :lot

Jusqu'à 1 000 sites en un appel, chacun porté par son id_externe. Une ligne invalide n'annule pas les autres : la réponse livre le compte de ce qui est passé et nomme ce qui a échoué. 

curl -X POST "https://api.trustydata.app/services/v1/locations/referentiels/boutiques/sites:lot" \
  -H "Authorization: Bearer VOTRE_CLE_API" \
  -H "Content-Type: application/json" \
  -d '{
    "sites": [
      {"id_externe": "PARIS-01", "nom_public": "Paris Opéra",
       "latitude": 48.8710, "longitude": 2.3317},
      {"id_externe": "LYON-01", "nom_public": "Lyon Part-Dieu",
       "ligne_voie": "17 rue du Docteur Bouchut",
       "code_postal": "69003", "commune": "Lyon"}
    ]
  }'
{
  "tache_id": "0f8c1c2e-6d4a-4a1b-9a3d-5b7e0c9f2a11",
  "total": 2,
  "crees": 2,
  "mis_a_jour": 0,
  "erreurs": []
}

total compte les lignes soumises, pas les réussites : crees + mis_a_jour + erreurs.length vaut toujours total. Conservez le tache_id — il permet de relire le rapport plus tard, sans rejouer l'écriture.

Une écriture = un appel compté

Un :lot de 1 000 sites consomme une unité de quota, comme un PUT unitaire. C'est le bon réflexe pour un chargement initial ou une reprise quotidienne.

Aligner sur un export complet : :sync

Là où :lot ajoute et met à jour, :sync fait du corps de la requête la vérité entière du référentiel : ce qui n'y figure pas est désactivé. Jamais supprimé — un export ultérieur qui ramène le site le réactive.

Le filet contre l'export tronqué

Une synchronisation qui désactiverait plus de la moitié de vos sites actifs est refusée en 409, avec le nombre de sites avant et après. C'est presque toujours le signe d'un export interrompu ou d'un filtre resté actif dans votre système source. Si la réduction est bien voulue — fermeture d'un réseau, changement de périmètre — renvoyez le même appel avec "confirmer_reduction": true.

Relire un rapport : /locations/taches/{id}

Le tache_id rendu par :lot et :sync donne accès au rapport détaillé : ce qui est passé, et la liste nommée de ce qui a échoué. Cet endpoint n'est pas facturé — c'est le reçu d'une écriture déjà payée, et il reste lisible même si votre quota mensuel est épuisé. 

curl "https://api.trustydata.app/services/v1/locations/taches/0f8c1c2e-6d4a-4a1b-9a3d-5b7e0c9f2a11" \
  -H "Authorization: Bearer VOTRE_CLE_API"

Le géocodage se fait en tâche de fond

Un site poussé avec latitude et longitude est cherchable immédiatement. Un site poussé avec une adresse seule part en file d'attente : TrustyData la résout contre le référentiel BAN officiel (IGN), puis le site devient cherchable. L'écriture vous rend donc la main tout de suite, sans attendre la résolution.

Chaque fiche porte l'état de ce travail dans geocodage_statut :

ValeurCe qu'elle dit
non_requis Vous avez fourni les coordonnées — rien à résoudre
en_attente L'adresse est en file d'attente : le site n'est pas encore cherchable
ok Adresse résolue, position calculée
echec L'adresse n'a pas pu être résolue — corrigez-la, ou fournissez les coordonnées

Après un chargement, listez les sites restés en échec pour traiter d'un coup ce qui a résisté : 

curl "https://api.trustydata.app/services/v1/locations/referentiels/boutiques/sites?geocodage=echec" \
  -H "Authorization: Bearer VOTRE_CLE_API"

Le paramètre statut=tous de ce même endpoint inclut les sites désactivés — c'est ainsi qu'on retrouve ce qu'une synchronisation a mis de côté.

Chercher les sites les plus proches

GET /locations/search est la raison d'être du service. Vous donnez un référentiel, un centre et un rayon ; l'API rend vos sites triés du plus proche au plus lointain, chacun avec sa distance_m et son état d'ouverture calculé dans le fuseau du site. 

curl "https://api.trustydata.app/services/v1/locations/search?referentiel=boutiques&lat=45.7640&lon=4.8357&rayon=3&limit=2" \
  -H "Authorization: Bearer VOTRE_CLE_API"
{
  "resultats": [
    {
      "id_externe": "LYON-01",
      "nom_public": "Boutique Lyon 1er",
      "ligne_voie": "11 Rue du Jardin des Plantes",
      "code_postal": "69001",
      "commune": "Lyon 1er Arrondissement",
      "latitude": 45.770325,
      "longitude": 4.832611,
      "fuseau": "Europe/Paris",
      "tags": ["terrasse"],
      "distance_m": 743.4,
      "ouverture": {
        "statut": "ferme",
        "prochaine_ouverture": "2026-09-01T11:30:00+02:00",
        "prochaine_fermeture": null
      },
      "statut": "actif",
      "geocodage_statut": "ok"
    }
  ],
  "pagination": {
    "limit": 2,
    "offset": 0,
    "next_offset": 2,
    "total_estime": 8
  },
  "point_central": {
    "lat": 45.764,
    "lon": 4.8357,
    "adresse_resolue": null,
    "precision": "coordonnees"
  }
}

distance_m est une distance à vol d'oiseau, en mètres. Pour un temps de trajet réel — utile pour arbitrer entre deux sites presque équidistants —, enchaînez avec /route/summary.

Le centre : coordonnées, adresse ou commune

Le centre se donne soit par lat+lon, soit par adresse — jamais les deux. Le paramètre adresse accepte une adresse complète, mais aussi un nom de commune ou un code postal seul : le centre est alors celui de la commune. C'est ce qui permet de répondre à un visiteur qui n'a tapé que « Lyon ».

Le bloc point_central dit toujours où la recherche a effectivement porté, et son champ precision distingue les trois cas :

precisionLe centre est…
coordonnees Le point que vous avez fourni, tel quel
adresse Une adresse résolue au numéro — adresse_resolue dit laquelle
commune Le centre d'une commune, faute de voie et de numéro dans la saisie

La distinction n'est pas décorative : un rayon de 2 km n'a pas le même sens autour d'un numéro de rue et autour du centre d'une grande ville. Affichez-la, ou élargissez le rayon quand la précision vaut commune. Un nom qui ne correspond exactement à aucune commune française est refusé en 422 plutôt que rapproché d'une commune vaguement ressemblante.

Filtrer par étiquette

Le paramètre tags est répétable et conjonctif : le site doit porter toutes les étiquettes demandées. Il permet de ne montrer que les points qui rendent un service donné. 

…/locations/search?referentiel=boutiques&adresse=Lyon&rayon=10&tags=click-and-collect&tags=accessible

Ce filtre demande le plan Growth ; la recherche elle-même reste accessible dès Starter.

Rayon et pagination

Le rayon s'exprime en kilomètres, entre 1 et 50. La pagination se pilote par limit (1–200, 100 par défaut) et offset (jusqu'à 5 000) ; le bloc pagination rend next_offset — null quand vous êtes au bout — et un total_estime.

La capacité incluse dans votre plan

Chaque plan inclut un nombre de sites, sans supplément :

PlanSites inclus
DiscoveryService non inclus — les appels sont refusés en 403
Starter200
Growth2 000
Business10 000

Une écriture qui ferait dépasser ce nombre — tolérance de 10 % comprise — est refusée en 409. Le detail porte alors capacite_sites_depassee, vos sites_actifs, votre capacite et le plafond toléré : un refus chiffré, plutôt qu'un dépassement silencieux que vous découvririez sur la facture.

Aucune facturation au site

La capacité est incluse dans le prix du plan. Stocker 9 000 sites sur un plan Business ne coûte pas plus que d'en stocker 10. Seuls les appels d'API sont comptés, comme pour les autres services — voir Plans & quotas.

Les sites désactivés ne comptent pas dans la capacité : c'est ce qui rend :sync sûr, même sur un référentiel proche du plafond.

Ce que le service ne fait pas

  • Pas d'isochrone. Le rayon est kilométrique et à vol d'oiseau. Pour raisonner en temps de trajet, combinez avec les itinéraires.
  • Pas de référentiel partagé. Aucun site n'est fourni par TrustyData, aucun n'est visible d'un autre compte.
  • Pas d'appel depuis un navigateur. Votre clé d'API ne doit jamais partir dans du code client : appelez /locations/search depuis votre serveur, qui relaie le résultat à votre page.

Gérer vos lieux sans écrire de code

Tout ce que fait l'API se fait aussi à la main depuis l'espace client, sur la même donnée : créer un référentiel, ajouter des sites, corriger une position sur la carte, saisir des horaires. C'est le chemin le plus court pour démarrer, et le bon outil pour les corrections ponctuelles une fois l'intégration en place.

Pour aller plus loin