Section 08 sur 12

Lieux

/places est le champ de recherche derrière l'application web : une requête, arrêts et adresses dans une seule liste. C'est aussi ainsi que /journeys résout le texte libre.

Fournisseurs#

Fournisseur	Source	Ce qu'il renvoie
`stops`	base Quavsit, recherche plein texte sur les noms d'arrêts et de zones (préfixe, insensible aux accents)	`Place` de kind `stop` ou `area`, avec `network` et `stop_id`
`addresses`	BAN, la Base Adresse Nationale (`api-adresse.data.gouv.fr`)	`Place` de kind `address`, `city` ou `poi`, avec `postcode`

Les deux sont actifs par défaut ; restreignez avec providers=stops ou providers=addresses. Les résultats portent source (store ou ban) et un score de pertinence dans [0, 1]. Les adresses couvrent la France uniquement.

Recherche#

GET /places?q=quinconces&near=44.84,-0.58&networks=tbm&limit=10

Paramètre	Notes
`q`	obligatoire, 1–120 caractères
`near`	`lat,lon` ; oriente les deux fournisseurs vers le point
`networks`	restreint le fournisseur d'arrêts
`providers`	`stops`, `addresses`, ou les deux (par défaut)
`limit`	1–20, 10 par défaut

À score égal, les arrêts précèdent les adresses. Une zone est préférée à ses arrêts enfants quand les deux correspondent ; utilisez l'identifiant de zone pour les passages, il agrège tous les quais.

Géocodage inverse#

GET /places/reverse?near=44.8412,-0.5716 renvoie l'adresse la plus proche depuis la BAN et les arrêts les plus proches depuis la base, chacun avec distance_meters. Utile pour nommer la position d'un utilisateur géolocalisé et choisir un arrêt de départ.

Forme d'un lieu#

json

{"id": "tbm:area:BEPIS66", "kind": "area", "name": "Quinconces", "label": "Quinconces, Bordeaux",
 "lat": 44.8437, "lon": -0.5742, "network": "tbm", "stop_id": "tbm:area:BEPIS66", "town": "Bordeaux",
 "postcode": null, "source": "store", "score": 0.98}

Les identifiants d'adresses sont préfixés ban: ; ce ne sont pas des identifiants stables et ils ne doivent pas être stockés, contrairement aux identifiants d'arrêts et de zones.

Cache et limites#

Les recherches de lieux sont mises en cache 10 minutes par requête. La BAN est appelée au plus une fois par seconde pour tout le service ; sous charge, le fournisseur d'adresses peut renvoyer moins de résultats tandis que celui des arrêts n'est pas affecté. Les données BAN sont sous Licence Ouverte 2.0 ; la mention figure dans meta.attribution dès que des adresses sont présentes.