Saltar a contenido

Guía del sistema

Esta guía explica cómo se articulan los objetos de la API: de dónde proceden los datos, qué los transforma y dónde leerlos. Complementa el glosario, que define cada entidad por separado.

Orden de lectura

Las cinco páginas se leen en este orden, que sigue el recorrido de los datos en el sistema.

Paso Página Qué se entiende en ella
1 Referencia GTFS Cómo entra la oferta teórica en el sistema y qué GTFS es el de referencia
2 Expediciones Qué distingue una expedición prevista de una expedición realizada, y cómo designarla sin ambigüedad
3 Tiempo real Cómo llegan los datos de campo y qué se difunde a los viajeros
4 Explotación Quién conduce qué, y cómo se contrasta lo previsto con lo realizado
5 Estadísticas y exportaciones Cómo extraer los datos de forma masiva para analizarlos

Una página queda fuera de este orden: Estaciones ferroviarias describe la referencia de las estaciones de viajeros de SNCF, el único endpoint de la API sin grupo y sin autenticación. Léala si vincula paradas de su red a estaciones; en caso contrario, puede ignorarla.

El grupo, requisito previo de toda llamada

Un grupo es una red explotada y la unidad de aislamiento de la API: casi todos los endpoints llevan el prefijo /groups/<group_id>, y un dato nunca existe fuera del grupo que lo contiene. Por tanto, antes de cualquier llamada, lo primero es saber con qué grupo se trabaja.

Un integrador recibe su <group_id> y una clave de API con los permisos correspondientes. La página Autenticación describe cómo obtener esta clave y transmitirla.

Los dos tiempos del sistema

Toda la lectura de la API se basa en una distinción, que recorre esta guía de principio a fin.

Teórico Realizado
Qué es Lo que la red tiene previsto Lo que ha ocurrido
Origen El GTFS importado Los datos transmitidos por los dispositivos de los conductores
Cambia cuando Se publica un nuevo GTFS Continuamente, durante el servicio
Ejemplo Una expedición sale a las 8:05 Salió a las 8:09, con dos paradas no atendidas

Confundir ambos es el error más frecuente en la integración: una misma expedición tiene un horario previsto y horas de paso observadas, y ambos se leen en lugares diferentes.

Unas palabras sobre las versiones

La API está versionada de v2 a v5; v4 es la versión por defecto y la que utiliza esta guía. El versionado y las tres categorías de endpoints (public, internal, datahub) se describen en la página de inicio.