Saltar a contenido

Ejemplos de recopilación

Las ocho exportaciones del spec datahub alimentan un almacén de datos a partir de la explotación de un grupo. Esta página ofrece un ejemplo ejecutable para cada una, en el lenguaje seleccionado en la cabecera — actualmente Node.js.

Todos los ejemplos se autentican con una clave de API, transmitida en la cabecera Authorization. La página Autenticación describe cómo obtenerla. Leen sus entradas del entorno:

Variable Contenido
GROUP_ID El identificador del grupo que se va a exportar
PYSAE_API_KEY La clave de API con los permisos de exportación

Antes de empezar: las firmas son distintas

Las ocho exportaciones no se llaman de la misma manera. Conviven tres familias, y no existe ninguna llamada genérica que cubra las ocho.

Exportación Parámetros
trips date (obligatorio)
trip-km, passenger-counts start_date, end_date (obligatorios)
punctuality, trip-tracking start_date (obligatorio), end_date
drivers, vehicles, alerts ningún parámetro obligatorio

Escriba las fechas en el formato compacto AAAAMMDD — por ejemplo 20260131. Es el único formato que aceptan los cinco endpoints con fecha. punctuality y trip-tracking toleran también la forma AAAA-MM-DD, pero los otros tres la rechazan: atenerse al formato compacto evita tener que recordar cuáles.

La página Estadísticas y exportaciones de la guía detalla lo que devuelve cada una.

Expediciones realizadas

GET /api/v4/groups/{group_id}/export/trips abarca una jornada, designada por date. Para cubrir un periodo, encadene una llamada por día.

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()))

Kilómetros recorridos

GET /api/v4/groups/{group_id}/export/trip-km acota un periodo con start_date y end_date, ambos obligatorios.

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()))

Recuento de viajeros

GET /api/v4/groups/{group_id}/export/passenger-counts sigue la misma firma que los kilómetros.

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()))

Puntualidad

GET /api/v4/groups/{group_id}/export/punctuality solo requiere start_date. El endpoint acepta además filtros opcionales —event, stop_id, gtfs_id, driver_id, route_id— para restringir la exportación.

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()))

Seguimiento de expediciones

GET /api/v4/groups/{group_id}/export/trip-tracking requiere start_date y 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()))

Conductores

GET /api/v4/groups/{group_id}/export/drivers exporta el referencial de conductores, sin noción de periodo. El parámetro opcional archived permite incluir los conductores archivados, que no aparecen por defecto.

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()))

Vehículos

GET /api/v4/groups/{group_id}/export/vehicles exporta la flota. El parámetro opcional statuses la restringe a los vehículos en un estado determinado.

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()))

Alertas

GET /api/v4/groups/{group_id}/export/alerts exporta los mensajes de información a los viajeros del grupo. Sin parámetros.

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 producción

  • Divida los periodos largos. Un tramo mensual se puede retomar tras un fallo; una exportación anual vuelve a empezar desde cero.
  • No fije un tiempo de espera corto. Las respuestas se transmiten de forma continua y una exportación amplia tarda en comenzar: un cliente que impone un plazo ajustado corta la conexión antes de la primera fila.
  • Repetir una exportación no tiene efectos secundarios. Estos endpoints son de solo lectura.
  • Compruebe el perímetro de la clave. Una clave restringida a determinados equipos exporta menos filas, sin que la respuesta lo indique.

Nota interna

Hay endpoints internos que sirven los mismos datos para los usos de back-office. No están destinados a las integraciones externas.