Chrona is a REST API that wraps the Infraestruturas de Portugal API, providing a cleaner interface for Portuguese railway data. It handles the complexity of the official API and adds features like caching, proper error handling, and data formatting.
Requires JDK 17+. Clone and run:
./gradlew runAPI runs on http://localhost:8000 with OpenAPI docs at /openapi.
Docker deployment:
# Build locally
docker build -t chrona .
docker run -p 8000:8000 chrona
# Or grab from container registry
docker run -p 8000:8000 ghcr.io/zadoke/chronav2/api-server:latestGET /train/{trainId}
Returns data for a specific train including its complete journey, stops, delays, and operational details. You get origin and destination stations with formatted names, complete list of stops with scheduled times and delay information, train operator and service type (Alfa Pendular, Intercidades, etc.), real-time status and delay information, and journey duration with timestamps. Throws 404 if the train doesn't exist or isn't running on the current date.
GET /station/search/{query}
Searches for railway stations matching the query string. Due to limitations in the upstream API, only the first word of multi-word queries is used for matching. Returns up to 25 stations with station ID (needed for schedule endpoints) and formatted station name. Results are cached for performance. The search is case-insensitive and handles partial matches. Empty results return 404.
GET /schedule/departures/{stationId}
Returns departure schedule for the specified station within a 14-hour window (2 hours before current time to 12 hours after). The response includes a filtered list excluding trains that have already departed, train numbers, destinations, and departure times, estimated carriage count based on train configuration, real-time delay and status information, and service type with operator details.
GET /schedule/arrivals/{stationId}
Same data structure as departures but filtered for arriving trains. Uses the same time window and filtering logic. Both schedule endpoints automatically handle timezone conversion for Lisbon time and filter results by train type (excludes freight and service trains by default).
GET /health/liveness
Basic application health check. Returns 200 if the service is running and responsive. Used by kubernetes typically.
GET /health/readiness
Checks connectivity to the upstream Infraestruturas de Portugal API. Returns 200 if external dependency is accessible, 503 otherwise.
GitHub Actions handles CI/CD pipeline with automatic Docker image publishing to GitHub Container Registry on main branch pushes.