Trains

Trains overview

Search, price, book and refund train journeys through the public Travelandz API.

Share

Search, price, book and refund train journeys through the public Travelandz API.

Base path

All public train operations live under /v1/trains. The currently available provider is gdsprovider=0.

Authentication

Every request requires Authorization: Bearer <secret_key> and X-Travelandz-Id: <public_key>:<profile_code>. The persisted profile code has the form dp_<12 alphanumeric>; keep secrets server-side.

Protocol conventions

  • JSON endpoints return 200 OK on a successful operation.
  • POST requests use Content-Type: application/json.
  • Dates use YYYY-MM-DD and amounts use { amount, currency }.
  • Unknown body or query fields are rejected with 400.
  • Stream endpoints return newline-delimited JSON (NDJSON), not one JSON document.

Workflow

  1. Search locations, then use their ids to search journeys.
  2. Keep journeyId and request offers for the selected journey.
  3. Keep one or more offerId values and create a pre-booking.
  4. Use bookingId to inspect required fields and create the order.
  5. Keep orderId and use refundable items before requesting a refund.

Endpoint catalog

MethodPathPurpose
GET/v1/trains/locationsSearch train locations.
POST/v1/trains/journeysSearch journeys.
POST/v1/trains/journeys/streamStream journeys as NDJSON.
POST/v1/trains/journeys/:gdsprovider/:journeyId/offersGet journey offers.
POST/v1/trains/journeys/:gdsprovider/:journeyId/offers/streamStream journey offers.
POST/v1/trains/book/:gdsprovider/prebookCreate a pre-booking.
GET/v1/trains/book/:gdsprovider/:bookingId/required-fieldsGet required booking fields.
POST/v1/trains/book/:gdsprovider/:bookingId/orderCreate and confirm an order.
GET/v1/trains/order/:gdsprovider/:orderIdGet an order and tickets.
GET/v1/trains/order/:gdsprovider/:orderId/refundable-itemsList refundable items.
POST/v1/trains/order/:gdsprovider/:orderId/refundStart a refund.
GET/v1/trains/order/:gdsprovider/:orderId/refundGet refund status.

Shared enums

FieldValues
passengers[].typeyouth, adult, senior
passengers[].titlemr, ms, mx
identityDocument.typepassport
transporttrain, bus, ferry
flexibilitynon_flex, semi_flex, full_flex
order.statuspending, confirmed, cancelled
refund.statesuccess, pending, error