Section 08 of 12

Places

/places is the search box behind the web app: one query, stops and addresses in one list. It is also how /journeys resolves free text.

Providers#

Provider	Source	What it returns
`stops`	Quavsit store, full-text search on stop and area names (accent-insensitive prefix match)	`Place` of kind `stop` or `area`, with `network` and `stop_id`
`addresses`	BAN, the French national address base (`api-adresse.data.gouv.fr`)	`Place` of kind `address`, `city` or `poi`, with `postcode`

Both run by default; restrict with providers=stops or providers=addresses. Results carry source (store or ban) and a relevance score in [0, 1]. Addresses cover France only.

Search#

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

Parameter	Notes
`q`	required, 1–120 characters
`near`	`lat,lon`; biases both providers towards the point
`networks`	restricts the stop provider
`providers`	`stops`, `addresses`, or both (default)
`limit`	1–20, default 10

Stops are returned before addresses at equal score. Areas are preferred to their child stops when both match; use the area id for departures, it aggregates all platforms.

Reverse#

GET /places/reverse?near=44.8412,-0.5716 returns the nearest address from BAN and the nearest stops from the store, each with distance_meters. Use it to label a geolocated user and to pick a starting stop.

Place shape#

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}

Address ids are prefixed ban:; they are not stable identifiers and should not be stored, unlike stop and area ids.

Caching and limits#

Place searches are cached 10 minutes by query. BAN is called at most once per second across the whole service; under load the address provider may return fewer results while the stop provider is unaffected. BAN data is under Licence Ouverte 2.0; the attribution in meta.attribution includes it when addresses are present.