Documentación · v2.0.0

API TUSSAM

API REST de código abierto para consultar paradas, líneas y tiempos de llegada de los autobuses de TUSSAM (Sevilla) en tiempo real. Actúa como proxy inteligente sobre la API interna de TUSSAM: normaliza los datos, cachea los tiempos, reintenta con criterio ante los errores del origen y expone CORS para poder llamarse desde cualquier cliente.

Toda la superficie de lectura es pública y no requiere autenticación. Solo los endpoints de sincronización (escritura) están protegidos por una API key. Las respuestas son JSON con coordenadas en grados decimales; el endpoint agregado admite además salida GeoJSON.

URL base y formato

En el despliegue con Docker Compose incluido, la API escucha en http://localhost:8081. En producción, la URL base es la de tu propio despliegue. Todos los ejemplos de esta página usan el puerto local.

• Todas las respuestas son application/json (salvo formato=geojson, que devuelve un FeatureCollection).
• Las coordenadas se expresan en grados decimales (WGS84), no en el formato E6 del origen.
• Cada respuesta incluye cabeceras X-RateLimit-* con la cuota restante.
• Cabeceras de seguridad activas: X-Content-Type-Options, X-Frame-Options, Referrer-Policy y Strict-Transport-Security en producción.

Autenticación

Los endpoints de lectura son públicos. Los de sincronización (POST /sync/*) exigen la cabecera X-API-Key con el valor de la variable de entorno de la clave de sync. La comparación usa hmac.compare_digest para no filtrar información por tiempo de respuesta.

curl -X POST http://localhost:8081/sync/all \
  -H "X-API-Key: $MI_CLAVE_DE_SYNC"

El servicio se niega a arrancar la operación si la clave está sin definir o conserva el valor de ejemplo (responde 503). El flag ALLOW_UNAUTHENTICATED_SYNC permite desactivar la autenticación solo fuera de producción; con APP_ENV=production se rechaza siempre.

Rate limiting

Cada petición se contabiliza en dos cubos que se aplican de forma conjunta: uno por IP (techo anti-DDoS) y otro, más estricto, por dispositivo. Se responde 429 si cualquiera de los dos supera su límite. El identificador de dispositivo solo puede restringir más, nunca saltarse el límite por IP.

Un cliente que envíe un X-Device-ID estable (por ejemplo, un UUID generado al instalarse) obtiene su propia cuota de 60/min sin competir con el resto de usuarios de su misma IP. Cada respuesta trae:

• X-RateLimit-Limit: límite aplicable.
• X-RateLimit-Remaining: peticiones restantes en la ventana.
• X-RateLimit-Reset: segundos hasta que se libere cuota.
• Retry-After (solo en 429): segundos que conviene esperar.

Resiliencia y cache

El origen (reddelineas.tussam.es) devuelve 429 con facilidad y a veces cambia el formato de la respuesta. La API está construida para que el cliente nunca herede esos problemas:

• Cache fresco (TTL 60 s): los tiempos se sirven desde SQLite; el origen solo se consulta cuando expiran.
• Single-flight por parada: muchas peticiones simultáneas a la misma parada generan una sola llamada al origen.
• Reintentos con backoff: los 429 y 5xx se reintentan respetando el Retry-After que envíe el origen.
• Cache stale (hasta 10 min): si el origen cae, se sirve la última respuesta válida marcada con stale: true y su cached_at.

Los endpoints señalizan siempre el estado del origen para que el cliente distinga «no vienen buses» de «no pudimos consultar»: mediante upstream_status en /paradas/{codigo}/tiempos y tiempos_status por parada en /cercanas.

Referencia de endpoints

Códigos de error

Despliegue

La vía más rápida es la imagen publicada en el GitHub Container Registry (ghcr.io/686f6c61/api-tussam), que incluye una base de datos precargada: la API responde desde el primer arranque sin necesidad de sincronizar. La clave de sync solo hace falta para los endpoints de administración; expórtala en tu entorno (por ejemplo, generada con openssl rand -hex 24).

# Descarga la imagen del GitHub Container Registry
docker pull ghcr.io/686f6c61/api-tussam:main

# Arráncala (escucha en el puerto 8081; la clave solo hace falta para /sync/*)
export MI_CLAVE_DE_SYNC=$(openssl rand -hex 24)
docker run -d -p 8081:8080 \
  -e SYNC_API_KEY=$MI_CLAVE_DE_SYNC \
  ghcr.io/686f6c61/api-tussam:main

# Verifica el estado
curl http://localhost:8081/health

export MI_CLAVE_DE_SYNC=$(openssl rand -hex 24)
SYNC_API_KEY=$MI_CLAVE_DE_SYNC docker compose up -d

pip install -e .
export MI_CLAVE_DE_SYNC=$(openssl rand -hex 24)
SYNC_API_KEY=$MI_CLAVE_DE_SYNC uvicorn app.main:app \
  --host 0.0.0.0 --port 8080 --proxy-headers

Variables de entorno