Estaciones ferroviarias¶
La API publica el referencial de estaciones de viajeros de la SNCF: 2782 estaciones, cada una con su código UIC, su posición y su adscripción administrativa. Es la única parte de la API que no pertenece a nadie: sin grupo, sin clave, sin derechos.
Qué distingue a este endpoint¶
| Resto de la API | Estaciones ferroviarias | |
|---|---|---|
| Ámbito | /groups/<group_id>/… |
ningún grupo |
| Autenticación | clave de API o sesión obligatoria | ninguna |
| Origen de los datos | el GTFS de su red y la información de campo | el conjunto de datos abierto de la SNCF gares-de-voyageurs |
| Cambia cuando | de forma continua, durante el servicio | cuando la SNCF revisa su conjunto de datos y el referencial se recarga manualmente |
La consecuencia que conviene tener presente: aquí nada es en tiempo real y nada es propio de su red. Es un índice, pensado para leerse antes que todo lo demás; típicamente, para designar mediante su código UIC la estación a la que corresponde una parada de su red.
Los dos endpoints¶
| Endpoint | Función |
|---|---|
GET /api/v4/rail-stations |
Busca en el referencial por nombre o por proximidad |
GET /api/v4/rail-stations/<uic> |
Lee una estación a partir de uno de sus códigos UIC |
Buscar por nombre¶
q se busca en cualquier parte del nombre de la estación, sin tener en cuenta mayúsculas, acentos ni separadores. chateauroux encuentra Châteauroux, y saint germain encuentra Saint-Germain-en-Laye Bel-Air – Fourqueux. No tiene que normalizar nada por su parte.
import httpx
response = httpx.get(
"https://api.pysae.com/api/v4/rail-stations",
params={"q": "Châteauroux"},
)
response.raise_for_status()
for station in response.json()["items"]:
print(station["uic"], station["name"])
La respuesta incluye la página y su total, como cualquier endpoint paginado de la API:
{
"items": [
{
"uic": ["87597005"],
"name": "Châteauroux",
"short_label": "CTX",
"segments_drg": ["A"],
"lat": 46.809737,
"lon": 1.699536,
"insee_code": "36044",
"source_ref": "0054eed7-a134-4fca-b217-d65e4d2ea153"
}
],
"total": 1,
"page": 1,
"page_size": 50
}
Buscar por proximidad¶
near=<latitude>,<longitude> ordena los resultados por distancia creciente y añade distance_meters a cada uno. radius, en metros, limita la búsqueda; su valor predeterminado es 10 km y se ignora si near no está presente.
GET /api/v4/rail-stations?near=48.880185,2.355151&radius=3000 devuelve las estaciones situadas a menos de 3 km de Paris Gare du Nord, empezando por la más cercana.
Ambos filtros se combinan: q y near juntos devuelven las estaciones cuyo nombre coincide, dentro del radio, ordenadas por distancia.
Una estación, varios códigos UIC¶
uic es una lista y no un valor único: es el aspecto que sorprende al integrar. La SNCF asigna varios códigos a una misma estación cuando la sirven varias redes: Paris Gare du Nord tiene tres y Avignon TGV, dos. Las consecuencias:
- Cualquiera de los códigos de una estación la resuelve.
GET /api/v4/rail-stations/87271007yGET /api/v4/rail-stations/87271031devuelven ambos Paris Gare du Nord. - Un código pertenece a una sola estación. Ningún código UIC se comparte, por lo que resolver uno nunca es ambiguo.
segments_drges una lista por la misma razón. El segmento de afluencia DRG (Ael más concurrido,Cel menos) se da por código, así que una estación con varios códigos puede tener varios segmentos.
Almacenar un único código por su parte basta para designar una estación, siempre que lea uic como una lista al comparar.
Vincular una parada de su red a una estación¶
La vinculación convierte el índice anterior en un dato de servicio: designa, para una parada de su GTFS, la estación cuyas salidas muestra, y delimita las estaciones cuyos datos ferroviarios se ingieren para su red. A diferencia del referencial, esta parte es propia de cada grupo y depende de la funcionalidad de pago rail_data: sin ella, los endpoints responden 403 con el código LOCKED_FEATURE.
GET /api/v4/groups/<group_id>/rail/station-links lista las vinculaciones del grupo. Cada vínculo incluye la parada (stop_id, con stop_name como etiqueta), la estación (uic) y un indicador is_orphan: true cuando la parada no existe —o ya no existe— en el GTFS publicado actualmente por el grupo. Un vínculo huérfano nunca se rechaza ni se elimina de oficio: sus paradas se reimportan con cada GTFS, y el vínculo debe sobrevivir a una reimportación que haga desaparecer momentáneamente su parada. Le corresponde a usted mostrar el indicador y corregir o retirar el vínculo.
Cada vínculo incluye también un ingestion_status, que indica en qué punto están los datos ferroviarios de la estación: ready cuando sus salidas se pueden consultar, pending mientras la estación se está ingiriendo, not_found cuando ningún tren del feed nacional actual la sirve. Vincular una estación que todavía no está en el almacén ferroviario responde de inmediato con pending y prepara sus datos de forma asíncrona, normalmente en cuestión de minutos; vuelva a listar los vínculos hasta que pase a ready y, mientras tanto, muestre «preparación en curso» en lugar de un panel de salidas vacío. not_found no es un error: el vínculo se conserva, y la actualización diaria lo reevalúa con cada nuevo feed de la SNCF.
La escritura está reservada al rol admin del grupo:
PUT /api/v4/groups/<group_id>/rail/station-linkscrea el vínculo(stop_id, uic)o, si ya existe, actualiza sustop_name; la llamada es idempotente y volver a enviarla nunca crea un duplicado. Elstop_idno se valida (véaseis_orphanmás arriba); el código UIC, en cambio, debe pertenecer al referencial; de lo contrario, la respuesta es un 404RAIL_STATION_NOT_FOUND.DELETE /api/v4/groups/<group_id>/rail/station-links/<stop_id>/<uic>retira el vínculo; sobre un vínculo inexistente, la respuesta es un 404RAIL_STATION_LINK_NOT_FOUND.
Leer el panel de salidas de una estación vinculada¶
Para esto sirve la vinculación: GET /api/v4/groups/<group_id>/rail/departures?stop_id=<stop_id> devuelve los trenes que salen de las estaciones vinculadas a esa parada de su red, con horarios teóricos y tiempo real combinados. Misma funcionalidad de pago rail_data que las vinculaciones: sin ella, 403 LOCKED_FEATURE.
La parada se designa por su stop_id en su GTFS, no por un código UIC. Una parada vinculada a varias estaciones devuelve las salidas de todas ellas en una sola lista.
La ventana horaria¶
from y to son instantes absolutos, en ISO 8601 o en segundos epoch, como en el resto de la API. Ambos límites están incluidos.
| Lo que usted envía | Ventana aplicada |
|---|---|
| nada | ahora → ahora + 1 h |
solo from |
from → from + 1 h |
solo to |
to - 1 h → to |
| ambos | tal cual, 24 h como máximo |
Una ventana invertida o de más de 24 h se rechaza con un 400 INVALID_RAIL_DEPARTURES_WINDOW: más allá, lo que pide es un catálogo de horarios, no un panel de salidas.
La respuesta¶
Una lista ordenada por scheduled_departure creciente, es decir, el horario teórico, sobre el que filtra la ventana, para que el orden no cambie cuando evolucionan las estimaciones.
| Campo | Función |
|---|---|
scheduled_departure |
El horario teórico. Siempre presente |
estimated_departure |
El horario estimado por el tiempo real, null si no lo hay |
delay_seconds |
La diferencia con signo entre ambos, negativa para un tren adelantado |
status |
scheduled, on_time, delayed, early, canceled, skipped, added |
destination |
Lo que hay que mostrar: stop_headsign, si no trip_headsign, si no el nombre de la última parada del tren |
route_type |
El modo, route_type de GTFS |
platform |
La vía, si la fuente la publica |
disruptions |
Las alertas en tiempo real que afectan a este tren, a su línea, a la estación o a toda la red |
service_date |
El día de servicio (YYYYMMDD), que no coincide con el día natural para un tren que sale después de medianoche |
Tres trampas que conviene conocer:
- Solo se listan los trenes en los que se puede subir. Un tren que termina su expedición en la estación, o que solo para en ella para el descenso de viajeros, no es una salida: figura en el panel de llegadas.
status: scheduledsignifica «sin tiempo real», no «puntual». Cuando ninguna entidad en tiempo real cubre el tren, el panel se sirve solo con sus horarios teóricos:estimated_departureydelay_secondsquedan ennullydisruptionsestá vacío. La ausencia de tiempo real degrada la visualización, nunca hace fallar la llamada, y se produce tren a tren, no panel a panel.- Ningún filtro por modo. Se devuelven todos los modos que sirven la estación, incluidos los autocares de sustitución
Car TER(route_type3): forman parte del servicio que el viajero debe ver. Filtre en el cliente porroute_typesi solo quiere los trenes.
platform es opcional de principio a fin: procede del platform_code del GTFS de la fuente, que el feed nacional de la SNCF no publica. Cuente con null en los datos de la SNCF y no lo convierta en una columna obligatoria de su visualización.
Una parada no vinculada a ninguna estación responde 200 con una lista vacía: es un estado de configuración, no un error. Lo mismo ocurre con una estación cuyos datos aún no se han ingerido: consulte ingestion_status en la vinculación para distinguir «en preparación» de «ningún tren».
Variante por código UIC — interna
GET /api/v4/groups/<group_id>/rail/departures/<uic> sirve el mismo panel, direccionado por estación en lugar de por parada. Es una utilidad de soporte y depuración, ausente de la especificación OpenAPI pública: ninguna integración debe indexarse por un código UIC, que es un identificador del referencial y no de su red.
El ámbito sigue siendo el del grupo que llama: un código UIC que otro grupo ha vinculado, pero este no, responde 200 con una lista vacía, nunca con los datos del otro grupo.
Leer el panel de llegadas de una estación vinculada¶
GET /api/v4/groups/<group_id>/rail/arrivals?stop_id=<stop_id> es el reflejo del panel de salidas: los trenes que llegan a las estaciones vinculadas a esa parada, con la misma funcionalidad rail_data, la misma ventana, las mismas fuentes y el mismo tiempo real. Solo cambia lo que depende del sentido.
| En el panel de salidas | En el panel de llegadas |
|---|---|
scheduled_departure, estimated_departure |
scheduled_arrival, estimated_arrival |
destination |
origin: el nombre de la primera parada de la expedición del tren |
ordenado por scheduled_departure |
ordenado por scheduled_arrival |
| se excluye un tren que termina su expedición en la estación | se lista un tren que termina su expedición en la estación |
| se lista un tren que empieza su expedición en la estación | se excluye un tren que empieza su expedición en la estación |
scheduled_departure se sigue devolviendo en una llegada cuando el tren vuelve a salir de la estación, y es null en su terminal. delay_seconds es el retraso de la llegada, y disruptions, las alertas activas a la hora de llegada. status, platform, route_type, trip_short_name (el número de tren) y los demás campos se leen exactamente igual que en el panel de salidas.
Una parada cerrada al descenso (drop_off_type 1 en el GTFS) se excluye, del mismo modo que una parada cerrada a la subida se excluye de las salidas.
Variante por código UIC — interna
GET /api/v4/groups/<group_id>/rail/arrivals/<uic> sirve el mismo panel por estación, ausente de la especificación OpenAPI pública como su equivalente de salidas. Es la ruta a la que llama la ficha de estación del mapa en directo de explotación, junto a departures/<uic>. Mismo ámbito: un código UIC que solo otro grupo ha vinculado responde 200 con una lista vacía.
Conectar una fuente ferroviaria propia del grupo¶
Por defecto, un grupo que dispone de la funcionalidad rail_data lee la fuente nacional de la SNCF, ingerida para toda la plataforma. La integración rail_data permite superponer la fuente GTFS propia de un cliente: sus datos se ingieren con un identificador de fuente propio del grupo (<group_id>:rail_data), filtrados solo a las estaciones que este grupo ha vinculado, y prevalecen sobre la fuente nacional en caso de colisión. Sin una integración declarada, el grupo lee únicamente la fuente nacional; declararla añade la superposición, no sustituye nada para los demás grupos.
En la lectura, el panel de salidas consolida ambas fuentes en este orden: primero la fuente nacional y, por encima, la del grupo. Una colisión se resuelve por sustitución, nunca campo a campo: el dato del cliente ocupa todo el lugar del dato homónimo de la SNCF, y un campo que su feed no incluye vale «ausente», no «heredado de la SNCF». Las claves naturales de colisión:
| Entidad | Clave |
|---|---|
| estación | codes_uic |
| línea | route_id |
| paso: una fila del panel | (trip_id, service_date, uic) |
| parada | stop_id |
| entidad en tiempo real (TripUpdate, alerta) | entity_id del FeedEntity |
La clave del paso incluye la estación, y no solo la expedición: un tren que sirve dos estaciones vinculadas a la misma parada da una fila por estación, no una sola. Figura el uic en lugar del stop_id porque es la identidad de estación compartida entre ambas fuentes; así, su superposición sustituye efectivamente el paso homónimo de la SNCF aunque los dos feeds nombren la vía de forma distinta.
El source_id de cada fila del panel indica cuál de las dos fuentes la ha producido. Es deliberadamente lo contrario del fusionador multi-GTFS de la v5 (merge_trips_to_v4_schemas), que une las listas y suma los agregados: aquí se superpone, de ahí una ruta de lectura dedicada.
La configuración se realiza mediante los endpoints de integración, reservados al rol admin del grupo:
PUT /api/v3/groups/<group_id>/integrations/rail_datacrea o sustituye la configuración;GET /api/v3/groups/<group_id>/integrations/rail_datala vuelve a leer;api_keysiempre aparece enmascarada;DELETE /api/v3/groups/<group_id>/integrations/rail_datala retira y purga de inmediato los datos ya ingeridos de esta fuente; el grupo vuelve a la fuente nacional únicamente.
Los campos:
| Campo | Función |
|---|---|
dataset_url |
La fuente GTFS: o bien un conjunto de datos de transport.data.gouv.fr (URL de la página o de la API; el zip se resuelve entonces mediante la API de datasets, como la fuente nacional), o bien la URL directa de un zip GTFS |
gtfs_rt_trip_updates_url |
Opcional: flujo GTFS-RT TripUpdates de la fuente |
gtfs_rt_service_alerts_url |
Opcional: flujo GTFS-RT ServiceAlerts de la fuente |
api_key |
Opcional: se envía como Authorization: Bearer en cada petición a la fuente |
enabled |
false suspende la fuente sin perder su configuración; sus datos se purgan en la siguiente actualización |
Todas las URL deben usar https: una URL http o de otro esquema se rechaza en la validación, y la ingesta se niega a contactar con una dirección IP no pública.
Se acepta una fuente puramente estática: las dos URL GTFS-RT pueden quedar vacías. Los datos se actualizan con el proceso por lotes diario del almacén ferroviario; un zip directo se considera modificado según sus cabeceras ETag / Last-Modified, y se vuelve a ingerir en cada pasada si el servidor no expone ninguna.
Buenas prácticas¶
- Almacene en caché lo que lee. El referencial es estático entre dos recargas manuales; volver a consultarlo en cada acción del usuario no aporta nada.
- Indexe por el código UIC, no por el nombre. La SNCF retoca los nombres; los códigos son el identificador estable.
source_refpermite encontrar el registro de origen en el conjunto de datos fuente, para auditoría. - Un código desconocido responde 404, con el código
RAIL_STATION_NOT_FOUND; no debe confundirse con una búsqueda vacía, que es un 200 contotal: 0. - No almacene en caché el panel de salidas como el referencial. Los flujos ferroviarios en tiempo real se actualizan aproximadamente cada dos minutos: consultar
departurescon más frecuencia devuelve las mismas estimaciones.