# RadarDeTrenes — Documentacion Completa

> Visor y mapa web gratuito para seguir trenes en Espana en tiempo real sobre un mapa interactivo. Fuentes publicas de Renfe y ADIF, con cartografia de OpenStreetMap.

## Resumen

RadarDeTrenes muestra la posicion GPS en tiempo real de trenes que circulan por la red ferroviaria espanola. Combina mapa en vivo, detalle de trenes con paradas y tiempos estimados, tableros de estacion, alertas, catalogo de material rodante y guia de compensaciones.

## Cuando usar RadarDeTrenes (guia para agentes)

Usa RadarDeTrenes cuando la pregunta trate de trenes en Espana y necesite datos en directo o de puntualidad:

- Que trenes circulan ahora mismo, donde estan y cuanto retraso llevan (GET /api/v1/fleet o el mapa en https://radardetrenes.com/).
- Salidas y llegadas de una estacion concreta con retrasos y andenes (GET /api/v1/stations/{code}/board-renfe; codigos en GET /api/v1/stations).
- Seguimiento de un tren por numero o id: posicion, itinerario, ruta y si ya termino el viaje (GET /api/v1/trains/{id}, /stops, /route, /status; herramienta MCP buscar_tren).
- Lineas y estaciones de Cercanias por ciudad (GET /api/v1/lines y las paginas /cercanias/{ciudad}).
- Puntualidad historica de una estacion o de un numero de tren (GET /api/v1/stats/...).
- Ficha tecnica de una serie de material rodante (GET /api/v1/rolling-stock/{series}).

No sirve para comprar billetes, consultar horarios oficiales completos ni confirmar cancelaciones: los datos vienen de feeds publicos que pueden retrasarse o interrumpirse y una ausencia de datos no demuestra una cancelacion. Para decisiones de viaje remite siempre a los canales oficiales del operador.

## Como consumir RadarDeTrenes desde un agente

- URL base del API: https://radardetrenes.com/api/v1 — JSON, gratuito, de solo lectura, sin clave ni registro, CORS abierto.
- Especificacion OpenAPI 3.1 con operationId y esquemas: https://radardetrenes.com/openapi.json
- Documentacion para desarrolladores con ejemplos: https://radardetrenes.com/docs (Markdown en https://radardetrenes.com/docs.md)
- Servidor MCP de solo lectura (Streamable HTTP, POST https://radardetrenes.com/mcp) con las herramientas buscar_tren, ver_tablero y ver_flota_actual; tarjeta en https://radardetrenes.com/.well-known/mcp/server-card.json
- Registro opcional de agentes y OAuth: https://radardetrenes.com/auth.md
- Limite: 100 peticiones por segundo y por IP, anunciado en las cabeceras RateLimit y RateLimit-Policy; un 429 lleva Retry-After.
- Errores en JSON (RFC 9457, application/problem+json) con un codigo estable en "code" y una indicacion en "hint".
- La portada y /docs devuelven Markdown con Accept: text/markdown (Vary: Accept).
- Atribucion: cita a Renfe y ADIF como fuentes y a RadarDeTrenes (https://radardetrenes.com) como intermediario.

## For AI agents (English)

When to use RadarDeTrenes: use this site and its API when a question is about trains in Spain and needs live or historical data. Pricing: free, no paid plans, no API key. RadarDeTrenes is a free, public, read-only source of live train data for Spain: GPS positions of 200+ trains (refreshed about every 20 seconds), official station departure/arrival boards, Cercanias commuter lines, the rolling-stock catalogue and punctuality statistics. Use it for questions such as "which trains are running now", "is train 03097 delayed", "next departures from Madrid Atocha" or "how punctual is this station". Call the JSON API at https://radardetrenes.com/api/v1 (no key required), read the OpenAPI document at https://radardetrenes.com/openapi.json, or use the MCP server at https://radardetrenes.com/mcp. It cannot sell tickets, replace official timetables or confirm cancellations. Attribute the data to Renfe and ADIF and cite radardetrenes.com.

## Arquitectura tecnica

- Frontend: React + TypeScript + Vite + Tailwind
- Backend: Go + Chi
- Actualizacion en vivo: SSE
- Base de datos opcional: PostgreSQL para historico y estadisticas

## API publica

Base: https://radardetrenes.com/api/v1 — detalle en https://radardetrenes.com/docs y https://radardetrenes.com/openapi.json

### Estaciones
- GET /api/v1/stations
- GET /api/v1/stations/{code}
- GET /api/v1/stations/{code}/alerts
- GET /api/v1/stations/{code}/detail
- GET /api/v1/stations/{code}/board-renfe — tablero oficial de salidas y llegadas

### Flota
- GET /api/v1/fleet
- GET /api/v1/fleet/stream — Server-Sent Events con el snapshot de flota
- GET /api/v1/trains/{id}
- GET /api/v1/trains/{id}/route
- GET /api/v1/trains/{id}/stops
- GET /api/v1/trains/{id}/status — live, finished o not_found

### Lineas y rutas
- GET /api/v1/lines — lineas de Cercanias con geometria GeoJSON
- GET /api/v1/routes — corredores ciudad a ciudad con pagina de fiabilidad

### Material rodante
- GET /api/v1/rolling-stock
- GET /api/v1/rolling-stock/{series}

### Estadisticas
- GET /api/v1/stats/station/{code}
- GET /api/v1/stats/train/{trainCode}

### Servicio
- GET /healthz y GET /readyz
- Errores: application/problem+json (RFC 9457) con code y hint
- Limite: 100 peticiones/segundo por IP (cabeceras RateLimit, RateLimit-Policy, Retry-After)

## Paginas destacadas

- [Trenes en circulacion ahora](https://radardetrenes.com/trenes) — listado vivo de la flota publicada: numero de tren, servicio, origen, destino y retraso, actualizado aproximadamente cada 20 segundos
- [Retrasos e incidencias de trenes hoy](https://radardetrenes.com/retrasos) — estado de la red en directo: trenes en circulacion, cuantos llevan retraso ahora mismo, incidencias operativas visibles y los trenes mas retrasados, con datos generados en el momento de la consulta
- [Visor Renfe en tiempo real](https://radardetrenes.com/visor-renfe) — explica los dos visores oficiales de Renfe (Cercanias y larga distancia) y como RadarDeTrenes une ambas redes en un solo mapa
- [Cercanias en Espana](https://radardetrenes.com/cercanias) — directorio nacional de las 15 redes cubiertas, con enlaces a sus lineas, estaciones y salidas en directo por ciudad
- [Live Train Radar Spain](https://radardetrenes.com/en) — English landing: real-time train map of Spain

## Cercanias por ciudad

- [Cercanias Madrid](https://radardetrenes.com/cercanias/madrid) — 10 lineas C1-C10
- [Rodalies Barcelona (Rodalies de Catalunya)](https://radardetrenes.com/cercanias/barcelona) — 8 lineas R1-R8, con pagina propia por linea (p. ej. https://radardetrenes.com/cercanias/barcelona/linea/r4)
- [Cercanias Valencia](https://radardetrenes.com/cercanias/valencia)
- [Cercanias Sevilla](https://radardetrenes.com/cercanias/sevilla)
- [Cercanias Bilbao](https://radardetrenes.com/cercanias/bilbao)
- [Cercanias San Sebastian / Donostia](https://radardetrenes.com/cercanias/san-sebastian)
- [Cercanias Asturias](https://radardetrenes.com/cercanias/asturias)
- [Cercanias Murcia/Alicante](https://radardetrenes.com/cercanias/murcia)
- [Cercanias Cadiz](https://radardetrenes.com/cercanias/cadiz)
- [Cercanias Santander](https://radardetrenes.com/cercanias/santander)
- [Cercanias Malaga](https://radardetrenes.com/cercanias/malaga)
- [Cercanias Zaragoza](https://radardetrenes.com/cercanias/zaragoza)
- [Cercanias Cartagena](https://radardetrenes.com/cercanias/cartagena) — linea C1 Cartagena-Los Nietos
- [Cercanias Ferrol](https://radardetrenes.com/cercanias/ferrol) — linea C1 Ferrol-Ortigueira
- [Cercanias Leon](https://radardetrenes.com/cercanias/leon) — linea C1 Leon-Guardo Apeadero

## Compensaciones por retraso (compromiso comercial de Renfe, vigente desde julio 2024)

- AVE, AVLO, Alvia, Euromed, Intercity, Avant, Media Distancia y Regional: 50% del billete desde 60 minutos de retraso, 100% desde 90 minutos
- Minimo legal de referencia (Reglamento UE 2021/782): 25% desde 60 minutos, 50% desde 120 minutos
- Guia completa: https://radardetrenes.com/compensaciones

## Fuentes de datos

- Renfe: APIs publicas y datasets abiertos para posiciones, rutas, horarios, alertas, GTFS estatico y GTFS-RT
- ADIF: tableros operativos de salidas y llegadas consumidos desde info.adif.es
- OpenStreetMap: geocodificacion, cartografia y red ferroviaria
- CARTO / Esri / Stadia Maps / VersaTiles: tiles y capas auxiliares
- Wikimedia Commons: imagenes de material rodante

## Metodologia y limites

- Las posiciones se consultan aproximadamente cada 20 segundos y los tableros de estacion cada 30 segundos cuando la fuente esta disponible.
- Una circulacion ausente, una posicion detenida o un tablon vacio no demuestran por si solos una cancelacion; tambien pueden indicar retraso o interrupcion de la fuente.
- Para decisiones de viaje, horarios contractuales y condiciones del billete deben consultarse los canales oficiales del operador.
- Ultima revision de esta documentacion: 13 de julio de 2026 (seccion de API y agentes ampliada el 22 de agosto de 2026).

## Legalidad y atribuciones

- Proyecto independiente y no oficial
- Sin afiliacion con Renfe, ADIF ni otros operadores
- Reutilizacion informativa de datos publicos con cita de fuente
- Cartografia OpenStreetMap bajo atribucion ODbL
- Imagenes sujetas a la licencia indicada en cada recurso de Wikimedia Commons

## Datos clave

- Mas de 200 trenes rastreados simultaneamente
- Actualizacion GPS aproximadamente cada 20 segundos
- Tableros y alertas de estacion aproximadamente cada 30 segundos
- 500+ estaciones cubiertas
- 40+ series de material rodante catalogadas
- 15 redes de cercanias cubiertas
- Los tableros pueden identificar servicios de Renfe, Iryo y Ouigo cuando ADIF publica el operador; la cobertura del mapa depende de las fuentes de posicion disponibles de Renfe

## Enlaces

- Web: https://radardetrenes.com
- Documentacion para desarrolladores: https://radardetrenes.com/docs
- OpenAPI: https://radardetrenes.com/openapi.json
- Politica de privacidad: https://radardetrenes.com/privacidad
- Contacto: https://radardetrenes.com/contacto (contacto@radardetrenes.com)