bookachoo

Get Price Calendar

List current prices of specific train connections and route in a certain time period.

Request
Security

Calendar endpoints are part of the bookachoo B2B API, and have restricted access. Valid credentials can be used to authenticate via HTTP Basic Authentication, and must be passed in the Authorization request header. 

Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

Credentials consist of a client_id and an access token, and should be used in a server-to-server context.

Query parameters
NameTypeDescription
from required string

Location of departure
  • City name from=Amsterdam
  • IATA code from=AMS
  • UIC code from=8400058
to required string

Location of arrival
  • City name to=Berlin
  • IATA code to=BER
  • IBNR to=8011160
departure enum Part of the day to depart inOne of:morning, afternoon, evening, night
period string

Time period to filter by (ISO-8601 Duration)
Example: period=P1M
index_by enum Index list of search resultsOne of:day, month
Responses

  • Successful response with list of offerings

    Body
    Property pathTypeDescription
    days array  
    days[].date string Date in YYYY-MM-DD format, pattern: /^\d{4}-\d{2}-\d{2}$/
    days[].offers array

    List of offers available on that date
    days[].offers[].time string

    Time of departure in 24-hour hh:mm format
    Example: "08:55"
    days[].offers[].price string Current price in the corresponding travel class, pattern: /^\d+\.\d{2,4}$/
    Example: "24.99"
    days[].offers[].currency "EUR"  
    days[].offers[].direct boolean

    Whether the offer is for a direct train connection
    days[].offers[].trainNumbers string[]

    Line number(s) of the train(s) servicing the offered connection
    Example: ["ICE-140"]
    days[].offers[].travelClass enum Normalized travel class the price applies to, one of:budget, standard, premium
    Example
    {
  "days": [
    {
      "date": "2025-01-01",
      "offers": [
        {
          "currency": "EUR",
          "direct": false,
          "price": "15.00",
          "time": "09:30",
          "trainNumbers": [
            "ABC-1234",
            "DEF-6789"
          ],
          "travelClass": "standard"
        },
        {
          "currency": "EUR",
          "direct": true,
          "price": "35.00",
          "time": "12:00",
          "trainNumbers": [
            "XYZ-9876"
          ],
          "travelClass": "premium"
        }
      ]
    },
    {
      "date": "2025-01-02",
      "offers": []
    }
  ]
}

  • Bad request due to invalid query parameters

    Body
    Property pathTypeDescription
    error object  
    error.description optional string

    Optional longer explanation describing the error.
    error.message string

    Concise error message.
    error.reason optional string

    Optional underlying reason that caused the error to happen.
    Example
    {
  "error": {
    "message": "Invalid query parameter",
    "description": "Failed to deserialize query string.",
    "reason": "index_by: unknown variant `week`, expected `day` or `month`"
  }
}

  • Unauthorized due to invalid or missing authentication token

    Headers
    NameDescription
    WWW-Authenticate

    Required authentication method
    Example: Basic realm="/calendar"; charset="UTF-8"
    Body
    Property pathTypeDescription
    error object  
    error.description optional string

    Optional longer explanation describing the error.
    error.message string

    Concise error message.
    error.reason optional string

    Optional underlying reason that caused the error to happen.
    Example
    WWW-Authenticate: Basic realm="/calendar"; charset="UTF-8"
    {
  "error": {
    "message": "Authorization required",
    "description": "Price calendar endpoint is for authorized consumers only.",
    "reason": "Unable to find authentication token in request"
  }
}

  • Unknown origin from or destination location to

    Body
    Property pathTypeDescription
    error object  
    error.description optional string

    Optional longer explanation describing the error.
    error.message string

    Concise error message.
    error.reason optional string

    Optional underlying reason that caused the error to happen.
    Example
    {
  "error": {
    "message": "Origin station not found",
    "description": "Unable to return price calendar due to unknown origin station."
  }
}