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 Node.js.

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 { writeFile } from "node:fs/promises"

const groupId = process.env.GROUP_ID
const apiKey = process.env.PYSAE_API_KEY

const url = new URL(
  `https://api.pysae.com/api/v4/groups/${groupId}/export/trips`,
)
url.searchParams.set("date", "20260131")

const response = await fetch(url, {
  headers: { Authorization: `Api-Key ${apiKey}` },
})
if (!response.ok) {
  throw new Error(`Export failed: ${response.status}`)
}

await writeFile("trips.csv", Buffer.from(await response.arrayBuffer()))

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 { writeFile } from "node:fs/promises"

const groupId = process.env.GROUP_ID
const apiKey = process.env.PYSAE_API_KEY

const url = new URL(
  `https://api.pysae.com/api/v4/groups/${groupId}/export/trip-km`,
)
url.searchParams.set("start_date", "20260101")
url.searchParams.set("end_date", "20260131")

const response = await fetch(url, {
  headers: { Authorization: `Api-Key ${apiKey}` },
})
if (!response.ok) {
  throw new Error(`Export failed: ${response.status}`)
}

await writeFile("trip-km.csv", Buffer.from(await response.arrayBuffer()))

Comptage voyageurs¶

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

import { writeFile } from "node:fs/promises"

const groupId = process.env.GROUP_ID
const apiKey = process.env.PYSAE_API_KEY

const url = new URL(
  `https://api.pysae.com/api/v4/groups/${groupId}/export/passenger-counts`,
)
url.searchParams.set("start_date", "20260101")
url.searchParams.set("end_date", "20260131")

const response = await fetch(url, {
  headers: { Authorization: `Api-Key ${apiKey}` },
})
if (!response.ok) {
  throw new Error(`Export failed: ${response.status}`)
}

await writeFile("passenger-counts.csv", Buffer.from(await response.arrayBuffer()))

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 { writeFile } from "node:fs/promises"

const groupId = process.env.GROUP_ID
const apiKey = process.env.PYSAE_API_KEY

const url = new URL(
  `https://api.pysae.com/api/v4/groups/${groupId}/export/punctuality`,
)
url.searchParams.set("start_date", "20260101")
url.searchParams.set("end_date", "20260131")

const response = await fetch(url, {
  headers: { Authorization: `Api-Key ${apiKey}` },
})
if (!response.ok) {
  throw new Error(`Export failed: ${response.status}`)
}

await writeFile("punctuality.csv", Buffer.from(await response.arrayBuffer()))

Suivi de course¶

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

import { writeFile } from "node:fs/promises"

const groupId = process.env.GROUP_ID
const apiKey = process.env.PYSAE_API_KEY

const url = new URL(
  `https://api.pysae.com/api/v4/groups/${groupId}/export/trip-tracking`,
)
url.searchParams.set("start_date", "20260101")
url.searchParams.set("end_date", "20260131")

const response = await fetch(url, {
  headers: { Authorization: `Api-Key ${apiKey}` },
})
if (!response.ok) {
  throw new Error(`Export failed: ${response.status}`)
}

await writeFile("trip-tracking.csv", Buffer.from(await response.arrayBuffer()))

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 { writeFile } from "node:fs/promises"

const groupId = process.env.GROUP_ID
const apiKey = process.env.PYSAE_API_KEY

const url = new URL(
  `https://api.pysae.com/api/v4/groups/${groupId}/export/drivers`,
)

const response = await fetch(url, {
  headers: { Authorization: `Api-Key ${apiKey}` },
})
if (!response.ok) {
  throw new Error(`Export failed: ${response.status}`)
}

await writeFile("drivers.csv", Buffer.from(await response.arrayBuffer()))

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 { writeFile } from "node:fs/promises"

const groupId = process.env.GROUP_ID
const apiKey = process.env.PYSAE_API_KEY

const url = new URL(
  `https://api.pysae.com/api/v4/groups/${groupId}/export/vehicles`,
)

const response = await fetch(url, {
  headers: { Authorization: `Api-Key ${apiKey}` },
})
if (!response.ok) {
  throw new Error(`Export failed: ${response.status}`)
}

await writeFile("vehicles.csv", Buffer.from(await response.arrayBuffer()))

Alertes¶

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

import { writeFile } from "node:fs/promises"

const groupId = process.env.GROUP_ID
const apiKey = process.env.PYSAE_API_KEY

const url = new URL(
  `https://api.pysae.com/api/v4/groups/${groupId}/export/alerts`,
)

const response = await fetch(url, {
  headers: { Authorization: `Api-Key ${apiKey}` },
})
if (!response.ok) {
  throw new Error(`Export failed: ${response.status}`)
}

await writeFile("alerts.csv", Buffer.from(await response.arrayBuffer()))

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.

Note interne

Des endpoints internes servent les mêmes données pour les usages back-office. Ils ne sont pas destinés aux intégrations externes.