Section 07 sur 12

Itinéraires

GET /journeys renvoie jusqu'à six itinéraires entre deux points. L'appel coûte 5 unités et les résultats sont mis en cache 60 secondes pour une requête identique.

Paramètres#

Paramètre	Valeur
`from`, `to`	un identifiant d'arrêt ou de zone (`idfm:area:71264`), des coordonnées (`48.8584,2.3470`), ou du texte libre résolu via `/places` (premier résultat)
`when`	RFC 3339 ou `now` (par défaut) ; heure de départ, ou d'arrivée avec `arrive_by=true`
`arrive_by`	`true` pour planifier à rebours depuis `when`
`modes`	liste pour restreindre les modes de transport
`planner`	`auto` (par défaut), `native`, `quavsit`
`max_walk`	mètres de marche autorisés à chaque extrémité, 1000 par défaut, 2500 au plus
`network`	force le réseau quand les deux points tombent dans plusieurs couvertures
`limit`	1–6, 3 par défaut

Un texte libre qui ne se résout à rien renvoie 404 place_not_found, avec le côté fautif dans details.

Un réseau par itinéraire#

Les deux extrémités doivent tomber dans la couverture du même réseau. Des points qui se résolvent vers des réseaux différents, ou vers aucun, renvoient 400 transit_query_invalid avec details.reason = "cross_network". Le calcul multi-réseaux (par exemple un TER puis un tram urbain) n'est pas disponible dans cette version ; planifiez chaque tronçon séparément.

Calculateurs natifs et routeur Quavsit#

Trois réseaux exposent un calculateur opérateur ; les autres sont servis par le routeur de Quavsit, construit sur l'horaire théorique du réseau :

Réseau	Choix de `planner=auto`	Repli si le calculateur natif échoue
`idfm`	natif (navitia via PRIM)	aucun : `503 transit_upstream_budget` quand le budget quotidien est épuisé
`sncf`	natif (navitia)	aucun
`tisseo`	natif (calculateur Tisséo, par coordonnées)	routeur Quavsit
`tbm`, `star`, `tam`, `rla`, `ilevia`	routeur Quavsit	—

planner=native sur un réseau sans calculateur renvoie 404 capability_unsupported. planner=quavsit force le routeur partout où l'horaire est chargé (tous les réseaux GTFS, Tisséo compris). Journey.source nomme ce qui a répondu : idfm, sncf, tisseo ou quavsit.

Le routeur Quavsit est un balayage de correspondances (connection scan) sur l'horaire courant, avec des cheminements piétons entre arrêts distants d'au plus 300 m (marche à 4,5 km/h, 60 s de battement) et la table de correspondances de l'opérateur quand elle existe. Les trip updates temps réel de la fenêtre sont appliqués avant le balayage : les courses retardées se décalent, les courses supprimées sont ignorées, et Journey.realtime vaut alors true. Les résultats privilégient l'arrivée la plus tôt, puis le moins de correspondances, puis le départ le plus tard. Le routeur ne calcule pas de tarif ; les calculateurs natifs renvoient fare quand ils le connaissent.

Forme de la réponse#

Un Journey porte departure_at, arrival_at, duration_seconds, transfers, walking_seconds, walking_meters, fare ({amount en centimes, currency, text} ou null), co2_grams quand il est connu, source, realtime et sections. Chaque Section est un tronçon walk, transit, wait ou transfer avec from_place, to_place, ses heures, line (un LineRef compact), headsign, direction_id, stop_ids et, pour les tronçons en transport, geometry en LineString GeoJSON découpé dans le tracé de la ligne entre la montée et la descente. Les tronçons à pied sont des segments droits avec distance_meters.

curl -sS "https://api.quavern.net/v1/journeys?from=48.8556,2.3592&to=idfm:area:71264&when=now&limit=2" \
  -H "Authorization: Bearer qv_p_…"

L'exemple JSON complet est dans Endpoints.

Ordre et doublons#

Les itinéraires sont classés par le calculateur (natif d'abord en auto), puis dédoublonnés sur (departure_at, arrival_at, suite des lignes empruntées).