Saltar a contenido

Referencia GTFS

Todo parte de aquí. El GTFS describe la oferta teórica de la red (líneas, paradas, trazados, calendarios, horarios) y es lo que da su identidad a las expediciones que la API expone después.

Un grupo conserva varios GTFS

Un GTFS no se importa de una vez por todas. Una red cambia de oferta en cada temporada, con cada obra, con cada ajuste del servicio. No se trata de una nueva versión de un GTFS existente: es un nuevo GTFS, con un nuevo identificador. Por tanto, el grupo acumula GTFS distintos, cada uno publicado para su periodo de validez.

La consecuencia práctica es importante: una fecha determina el GTFS vigente. Pedir los horarios de una expedición sin saber a qué GTFS pertenece no tiene sentido en cuanto se sale del día en curso.

Endpoint Función
GET /api/v4/groups/<group_id>/gtfs Lista los GTFS del grupo
GET /api/v4/groups/<group_id>/gtfs/<gtfs_id> Descarga el archivo zip de un GTFS
GET /api/v4/groups/<group_id>/history/gtfs-active Devuelve el GTFS vigente en una fecha pasada

Para una integración que trabaja con datos históricos, el tercer endpoint es el punto de entrada: evita tener que reconstruir uno mismo la correspondencia entre una fecha y un GTFS.

Consultar y descargar un GTFS sin autenticación

La lista de los GTFS de un grupo es pública: muestra también las ofertas futuras y los borradores. Una llamada anónima no recibe ni el autor de la última modificación (mod_user), ni el informe de validación (validation), ni el fallo de una publicación programada (publication_failed): estos campos requieren un rol de lectura en el grupo. Los archivos, por su parte, pueden descargarse sin cuenta en dos casos.

Endpoint Acceso anónimo
GET /api/v4/groups/<group_id>/gtfs Siempre: lista los GTFS del grupo, incluidas las ofertas futuras y los borradores
GET /api/v4/groups/<group_id>/gtfs/pub Siempre: es el GTFS vigente, la URL estable que se debe facilitar a un portal de datos abiertos
GET /api/v4/groups/<group_id>/gtfs/<gtfs_id> Si este GTFS ya se ha publicado, o si el operador lo ha compartido para su descarga pública

Cualquier otro GTFS (borrador, oferta programada, importación nunca compartida) requiere un rol de lectura en el grupo; una llamada anónima recibe 403 NO_ROLE, también para un identificador desconocido. El campo public_download de un GTFS indica si se ha compartido.

Los dos endpoints de archivo responden con una cabecera ETag y una cabecera Last-Modified, y aceptan solicitudes condicionales: devuelva el ETag en If-None-Match (o la fecha en If-Modified-Since) y un archivo sin cambios recibirá un 304 Not Modified vacío, sin reconstruirse. If-None-Match tiene prioridad cuando se envían ambas cabeceras. El ETag también cambia cuando se renombra un equipo del grupo, algo que Last-Modified no refleja.

El operador configura el uso compartido desde las aplicaciones de Pysae: PUT /api/v4/groups/<group_id>/gtfs/<gtfs_id>/metadata con {"public_download": true}. Sirve para los archivos preparados para un portal de datos abiertos sin ponerlos en servicio. Un GTFS publicado sigue siendo descargable sea cual sea este ajuste.

El ciclo de vida de un GTFS

Un GTFS importado no entra en servicio de inmediato. Primero se valida y después se publica; el archivado lo retira del servicio sin destruirlo, de modo que los datos generados mientras estaba activo siguen siendo interpretables.

Por eso un GTFS archivado sigue pudiendo consultarse: las expediciones realizadas hace seis meses se vinculan al GTFS que estaba vigente entonces, y no al de hoy.

Endpoint Función
GET /api/v4/groups/<group_id>/gtfs/<gtfs_id>/validate Devuelve el informe de validación de un GTFS

La validación se apoya en un servicio de control dedicado. Si no responde a tiempo, la llamada devuelve 504 GTFS_VALIDATOR_TIMED_OUT; si no está disponible o responde con un error, 502 GTFS_VALIDATOR_UNAVAILABLE. En ambos casos el GTFS no es la causa: el informe queda pendiente y la llamada puede repetirse más tarde.

La importación y las transiciones de estado están reservadas a las aplicaciones de Pysae: POST /api/v4/groups/<group_id>/gtfs y, después, .../publish, .../archive y .../restore.

Qué contiene la referencia

Tres objetos del GTFS aparecen constantemente en la API y se definen en el glosario:

  • gtfs: el propio GTFS;
  • trips: las expediciones previstas;
  • stop-times: sus horarios de paso por las paradas.

Las líneas, paradas y trazados también existen en la referencia, pero la API pública los expone a través de las expediciones y no como colecciones propias: se leen las paradas de una expedición, no el catálogo de paradas.

Siguientes pasos

Una vez conocido el GTFS vigente, se puede designar una expedición sin ambigüedad: ese es el objeto de la página Expediciones.