Comment rechercher les arrêts de transport à proximité avec une API ?

Pour rechercher des arrêts autour d’un point, transmettez sa latitude, sa longitude et un rayon à une API de proximité. Vérifiez ensuite le statut de la réponse, les entités retournées et les informations de couverture avant d’afficher la liste ou la carte.

Dans le contrat ROOTE roote-1.0.0, la route GET /v1/transit/nearby découvre les lieux de transport à proximité. Elle ne récupère pas les départs ni les alertes en temps réel. La recherche d’un lieu et la recherche de son prochain passage sont deux opérations distinctes.

Définir les paramètres

La requête utilise lat pour la latitude et lng pour la longitude. L’alias lon est également décrit dans le contrat. Le paramètre radius exprime le rayon en mètres ; limit borne le nombre de résultats demandé. Le filtre modes peut préciser les modes de transport.

Ces coordonnées servent d’exemple de recherche à Bordeaux ; elles ne désignent pas un arrêt garanti. Consultez le contrat OpenAPI ROOTE pour les bornes, les champs et les conditions actuels.

Envoyer une première requête côté serveur

Voici un exemple JavaScript pour un environnement Node.js disposant de fetch. Le jeton, si votre accès en utilise un, reste dans une variable d’environnement côté serveur. L’exemple ne nécessite pas de placer un secret dans le navigateur.

async function rechercherArrets(token = process.env.ROOTE_API_TOKEN) {
  const url = new URL('https://api.roote.ai/v1/transit/nearby');
  url.search = new URLSearchParams({
    lat: '44.8378',
    lng: '-0.5792',
    radius: '600',
    limit: '10',
    modes: 'bus,tram'
  }).toString();

  const headers = { Accept: 'application/json' };
  if (token) headers.Authorization = `Bearer ${token}`;

  const response = await fetch(url, {
    headers,
    signal: AbortSignal.timeout(10000)
  });
  if (!response.ok) {
    throw new Error(`Erreur HTTP ${response.status}`);
  }

  const data = await response.json();
  if (data.contract_version !== 'roote-1.0.0') {
    throw new Error('Version du contrat non reconnue');
  }
  if (!['success', 'empty', 'partial'].includes(data.status)) {
    throw new Error('Recherche indisponible');
  }
  if (!Array.isArray(data.stations)) {
    throw new Error('Réponse sans collection stations valide');
  }

  return {
    status: data.status,
    stations: data.stations,
    lines: data.lines,
    operators: data.operators,
    coverage: data.coverage,
    warnings: data.warnings,
    attributions: data.attributions,
    meta: data.meta
  };
}

Le contrat consulté prévoit un accès anonyme ou par jeton, selon les politiques applicables. Vérifiez vos droits et les limites d’accès. Une réponse HTTP correcte ne dispense pas de valider son contenu ; en production, utilisez aussi une validation des objets contre le schéma.

Lire les entités et leurs relations

La collection stations contient les lieux retournés. Pour chacun, consultez notamment id, name, entity_kind, location et distance_meters. Les références line_ids et operator_ids permettent d’associer les collections lines et operators lorsqu’elles sont renseignées.

Affichez une distance géographique comme telle. Ne la transformez pas en temps de marche sans calcul d’itinéraire. Le guide trouver un arrêt proche explique pourquoi les accès peuvent modifier le déplacement réel.

Traitez aussi les informations inconnues explicitement. Dans le contrat, accessibility.wheelchair peut valoir unknown : cette valeur n’équivaut ni à yes ni à no. Une capacité de départs annoncée ne constitue pas une liste de départs.

Afficher une liste ou une carte

Utilisez l’identifiant pour stabiliser les éléments de l’interface, le nom pour leur libellé et location pour leur position. Associez les lignes grâce aux références, plutôt qu’en rapprochant leurs noms.

Si vous affichez des couleurs de lignes ou des libellés provenant des données, traitez-les comme des entrées externes à valider. Pour les noms, utilisez du texte plutôt que du HTML injecté.

Conservez les attributions des sources et affichez celles que le contrat indique comme requises.

Gérer résultat vide, réponse partielle et erreur

Un résultat empty décrit une recherche sans résultat retourné dans le périmètre connu. Il ne prouve pas l’absence physique de transports. Une réponse partial peut contenir des lieux utiles tout en signalant des limites : présentez les résultats et l’avertissement adapté.

Lisez coverage, warnings et les limites appliquées dans meta. Une liste tronquée ne décrit pas une couverture exhaustive. En cas d’erreur réseau ou HTTP, affichez une indisponibilité, sans remplacer le résultat par « aucun arrêt ».

Pour un code 429, consultez les consignes de reprise et les éventuels en-têtes du service. Évitez les relances en boucle.

Distinguer stations, zones et quais

Le champ entity_kind distingue plusieurs niveaux de lieux. Deux résultats voisins peuvent correspondre à des quais distincts ; deux noms similaires peuvent appartenir à des sources différentes.

Ne fusionnez pas automatiquement les lieux sur la seule proximité. Utilisez les relations et identités documentées par le service. Notre guide GTFS, GTFS-RT et GBFS explique le contexte des données.

Préparer l’intégration en production

Déclenchez les recherches lorsque la position ou les filtres changent utilement. Regroupez les appels identiques, définissez un délai d’attente et adaptez le cache au type de donnée et aux conditions du service.

Une liste de lieux et une disponibilité en temps réel n’ont pas les mêmes exigences de fraîcheur. Validez le parcours avec des réponses complètes, vides, partielles et en erreur avant de présenter la recherche aux utilisateurs.

Questions fréquentes

Nearby fournit-il les prochains départs ?

Pas dans le contrat présenté ici. Cette route découvre les lieux de transport ; les départs demandent une capacité distincte.

Peut-on afficher une liste vide après une erreur ?

Présentez une indisponibilité. Une erreur ne démontre pas l’absence d’arrêts.

Peut-on placer le jeton API dans le navigateur ?

Un secret doit rester côté serveur. Utilisez le modèle d’accès prévu pour votre application et votre compte.