Documentación de la API

Referencia técnica de cada endpoint: parámetros, ejemplos de petición y respuesta reales. Para conseguir una key, visita /developers.

Autenticación en una línea

Toda la API va detrás de una API key, salvo la propia alta. Envíala siempre en la cabecera X-API-Key.

curl "https://api.bonovia.app/v1/stations?q=madrid" \
  -H "X-API-Key: tu_key_aqui"

Formato de los errores

Cuando algo falla, la respuesta sigue casi siempre el mismo formato: { "error": "mensaje" }. Los códigos concretos que puede devolver cada endpoint (400, 401, 429...) están documentados en su propia página — no todos los endpoints pueden devolver los mismos: POST /v1/keys, por ejemplo, no requiere autenticación, así que nunca devuelve 401.

Única excepción al formato: /v1/health usa ok: false y un código 503 o 500 para señalar problemas, sin campo error.

Autenticación

Cómo conseguir y revocar tu propia API key. Todo lo demás en esta API va detrás de X-API-Key.

POST/v1/keys

Crear una API key

Alta self-service, sin autenticación previa — así es como consigues tu primera key.

POST/v1/keys/revoke

Revocar tu API key

Auto-revocación: la key que envías en X-API-Key es tanto la autenticación como la que se revoca.

Estaciones y rutas

Los datos de transporte en sí: buscar estaciones, ver qué se puede alcanzar desde una, y consultar horarios.

GET/v1/stations

Buscar estaciones

Búsqueda de estaciones y agrupaciones de ciudad por nombre, sin distinguir acentos ni mayúsculas.

GET/v1/explore

Explorar destinos alcanzables

Todos los destinos alcanzables desde una estación de origen, en trayecto directo, con duración y operador. Paginado.

GET/v1/departures

Próximas salidas

Salidas ordenadas por hora desde una estación, para un día concreto.

Cuenta

Lo que puedes consultar sobre tu propia API key.

GET/v1/keys/usage

Estadísticas de uso

El uso de tu propia key — nunca el de otras. La autenticación de esta llamada ya identifica de quién son los datos.

Sistema

Salud y frescura de los datos que sirve la API.

GET/v1/health

Estado del sistema

Frescura del paquete de datos GTFS activo y estado de las comprobaciones internas.