Exemples de collecte¶

Les huit exports du spec datahub alimentent un entrepôt de données à partir de l'exploitation d'un groupe. Cette page en donne un exemple exécutable pour chacun, dans le langage sélectionné dans l'en-tête — actuellement Python.

Tous les exemples s'authentifient avec une clé d'API, transmise dans l'en-tête Authorization. La page Authentification décrit comment l'obtenir. Ils lisent leurs entrées dans l'environnement :

Variable	Contenu
`GROUP_ID`	L'identifiant du groupe à exporter
`PYSAE_API_KEY`	La clé d'API portant les droits d'export

Avant de commencer : les signatures diffèrent¶

Les huit exports ne s'appellent pas de la même façon. Trois familles cohabitent, et il n'y a pas d'appel générique qui couvre les huit.

Export	Paramètres
`trips`	`date` (requis)
`trip-km`, `passenger-counts`	`start_date`, `end_date` (requis)
`punctuality`, `trip-tracking`	`start_date` (requis), `end_date`
`drivers`, `vehicles`, `alerts`	aucun paramètre requis

Écrire les dates au format compact AAAAMMJJ — par exemple 20260131. C'est le seul format accepté par les cinq endpoints datés. punctuality et trip-tracking tolèrent aussi la forme AAAA-MM-JJ, mais les trois autres la rejettent : s'en tenir au format compact évite d'avoir à retenir lesquels.

La page Statistiques et exports du guide détaille ce que chacun renvoie.

Courses réalisées¶

GET /api/v4/groups/{group_id}/export/trips porte sur une journée, désignée par date. Pour couvrir une période, enchaîner un appel par jour.

import os

import httpx

group_id = os.environ["GROUP_ID"]
api_key = os.environ["PYSAE_API_KEY"]

response = httpx.get(
    f"https://api.pysae.com/api/v4/groups/{group_id}/export/trips",
    headers={"Authorization": f"Api-Key {api_key}"},
    params={"date": "20260131"},
    timeout=None,
)
response.raise_for_status()

with open("trips.csv", "wb") as file:
    file.write(response.content)

Kilomètres parcourus¶

GET /api/v4/groups/{group_id}/export/trip-km borne une période avec start_date et end_date, tous deux requis.

import os

import httpx

group_id = os.environ["GROUP_ID"]
api_key = os.environ["PYSAE_API_KEY"]

response = httpx.get(
    f"https://api.pysae.com/api/v4/groups/{group_id}/export/trip-km",
    headers={"Authorization": f"Api-Key {api_key}"},
    params={"start_date": "20260101", "end_date": "20260131"},
    timeout=None,
)
response.raise_for_status()

with open("trip-km.csv", "wb") as file:
    file.write(response.content)

Comptage voyageurs¶

GET /api/v4/groups/{group_id}/export/passenger-counts suit la même signature que les kilomètres.

import os

import httpx

group_id = os.environ["GROUP_ID"]
api_key = os.environ["PYSAE_API_KEY"]

response = httpx.get(
    f"https://api.pysae.com/api/v4/groups/{group_id}/export/passenger-counts",
    headers={"Authorization": f"Api-Key {api_key}"},
    params={"start_date": "20260101", "end_date": "20260131"},
    timeout=None,
)
response.raise_for_status()

with open("passenger-counts.csv", "wb") as file:
    file.write(response.content)

Ponctualité¶

GET /api/v4/groups/{group_id}/export/punctuality ne requiert que start_date. L'endpoint accepte en plus des filtres facultatifs — event, stop_id, gtfs_id, driver_id, route_id — pour restreindre l'export.

import os

import httpx

group_id = os.environ["GROUP_ID"]
api_key = os.environ["PYSAE_API_KEY"]

response = httpx.get(
    f"https://api.pysae.com/api/v4/groups/{group_id}/export/punctuality",
    headers={"Authorization": f"Api-Key {api_key}"},
    params={"start_date": "20260101", "end_date": "20260131"},
    timeout=None,
)
response.raise_for_status()

with open("punctuality.csv", "wb") as file:
    file.write(response.content)

Suivi de course¶

GET /api/v4/groups/{group_id}/export/trip-tracking requiert start_date et end_date.

import os

import httpx

group_id = os.environ["GROUP_ID"]
api_key = os.environ["PYSAE_API_KEY"]

response = httpx.get(
    f"https://api.pysae.com/api/v4/groups/{group_id}/export/trip-tracking",
    headers={"Authorization": f"Api-Key {api_key}"},
    params={"start_date": "20260101", "end_date": "20260131"},
    timeout=None,
)
response.raise_for_status()

with open("trip-tracking.csv", "wb") as file:
    file.write(response.content)

Conducteurs¶

GET /api/v4/groups/{group_id}/export/drivers exporte le référentiel des conducteurs, sans notion de période. Le paramètre facultatif archived permet d'inclure les conducteurs archivés, absents par défaut.

import os

import httpx

group_id = os.environ["GROUP_ID"]
api_key = os.environ["PYSAE_API_KEY"]

response = httpx.get(
    f"https://api.pysae.com/api/v4/groups/{group_id}/export/drivers",
    headers={"Authorization": f"Api-Key {api_key}"},
    timeout=None,
)
response.raise_for_status()

with open("drivers.csv", "wb") as file:
    file.write(response.content)

Véhicules¶

GET /api/v4/groups/{group_id}/export/vehicles exporte le parc. Le paramètre facultatif statuses restreint aux véhicules dans un état donné.

import os

import httpx

group_id = os.environ["GROUP_ID"]
api_key = os.environ["PYSAE_API_KEY"]

response = httpx.get(
    f"https://api.pysae.com/api/v4/groups/{group_id}/export/vehicles",
    headers={"Authorization": f"Api-Key {api_key}"},
    timeout=None,
)
response.raise_for_status()

with open("vehicles.csv", "wb") as file:
    file.write(response.content)

Alertes¶

GET /api/v4/groups/{group_id}/export/alerts exporte les messages d'information voyageurs du groupe. Aucun paramètre.

import os

import httpx

group_id = os.environ["GROUP_ID"]
api_key = os.environ["PYSAE_API_KEY"]

response = httpx.get(
    f"https://api.pysae.com/api/v4/groups/{group_id}/export/alerts",
    headers={"Authorization": f"Api-Key {api_key}"},
    timeout=None,
)
response.raise_for_status()

with open("alerts.csv", "wb") as file:
    file.write(response.content)

En production¶

Découper les longues périodes. Une tranche mensuelle se reprend après un échec ; un export annuel recommence de zéro.
Ne pas fixer de délai d'attente court. Les réponses sont diffusées au fil de l'eau et un export large met du temps à démarrer : un client qui impose un délai serré coupe la connexion avant la première ligne.
Rejouer un export est sans effet de bord. Ces endpoints sont en lecture seule.
Vérifier le périmètre de la clé. Une clé restreinte à certaines équipes exporte moins de lignes, sans que la réponse le signale.