Premiers pas

Quavsit est une API HTTP en lecture seule pour les transports publics français : lignes, arrêts, prochains passages, position des véhicules, perturbations, lieux et itinéraires, pour plusieurs réseaux derrière un seul modèle de données. Chaque réponse indique si elle est en temps réel ou théorique. Cette page va de la clé à la première réponse en quelques minutes.

URL de base#

Tous les endpoints sont sous https://api.quavern.net/v1. Les requêtes sont de simples GET avec des paramètres de query ; les réponses sont en JSON, UTF-8, compressées en gzip quand le client l'accepte. Il n'existe aucun endpoint d'écriture.

Créer une clé#

Les clés se créent depuis votre compte myQuavern, sur my.quavern.com/account/quavsit. Une clé commence par qv_p_, n'est affichée qu'une fois, est stockée hachée et peut être révoquée depuis la même page. Le plan Free ne demande aucun moyen de paiement et comprend 5 000 unités par mois ; voir Limites et tarifs.

L'adresse e-mail du compte doit être vérifiée pour que l'API accepte la clé.

Première requête#

Remplacez qv_p_… par votre clé. L'exemple liste les réseaux connus de l'API ; il coûte une unité.

curl -sS "https://api.quavern.net/v1/networks" \
  -H "Authorization: Bearer qv_p_…"

Puis les prochains passages à un arrêt (les identifiants ci-dessous sont illustratifs ; trouvez les vrais avec /places ou /networks/{network}/stops) :

curl -sS "https://api.quavern.net/v1/stops/tbm:stop:3824/departures?limit=5" \
  -H "Authorization: Bearer qv_p_…"

Python#

La bibliothèque standard suffit ; aucun SDK n'est nécessaire.

import json
import urllib.parse
import urllib.request

BASE = "https://api.quavern.net/v1"
KEY = "qv_p_…"

def get(path, **params):
    query = urllib.parse.urlencode(params)
    url = f"{BASE}{path}" + (f"?{query}" if query else "")
    request = urllib.request.Request(url, headers={"Authorization": f"Bearer {KEY}"})
    with urllib.request.urlopen(request, timeout=15) as response:
        return json.load(response)

payload = get("/stops/tbm:stop:3824/departures", limit=5)
for departure in payload["data"]:
    print(departure["line_code"], departure["headsign"], departure["expected_at"] or departure["scheduled_at"])

JavaScript#

Fonctionne avec Node 18+ et les runtimes côté serveur. N'envoyez jamais une clé dans un navigateur ; appelez l'API depuis votre propre backend.

const BASE = "https://api.quavern.net/v1";
const KEY = "qv_p_…";

async function get(path, params = {}) {
  const url = new URL(BASE + path);
  for (const [name, value] of Object.entries(params)) url.searchParams.set(name, String(value));
  const response = await fetch(url, { headers: { Authorization: `Bearer ${KEY}` } });
  const body = await response.json();
  if (!response.ok) throw new Error(`${body.error.code} ${body.error.reason}`);
  return body;
}

const { data, meta } = await get("/stops/tbm:stop:3824/departures", { limit: 5 });
console.log(meta.freshness, data.map((d) => `${d.line_code} ${d.headsign}`));

Lire la réponse#

Chaque succès est de la forme {"data": …, "meta": {…}}. meta.freshness dit si au moins un élément est en temps réel ; meta.attribution porte la mention de source que vous devez afficher ; les en-têtes X-Quavsit-Units et X-Quavsit-Units-Remaining indiquent le coût de l'appel et ce qu'il reste ce mois-ci. Les erreurs sont {"error": {"code", "reason", "message"}} avec un reason stable. Détails dans Concepts et Erreurs.

Pour continuer#

Lisez Authentification pour les scopes et ce qui n'est pas accepté, Réseaux pour ce que chaque opérateur publie, et Endpoints pour la liste complète des routes et de leurs paramètres. L'application web quavsit.quavern.com utilise la même API et permet de trouver des identifiants facilement.