Get available train trips

GET /trips

Returns a list of available train trips between the specified origin and destination stations on the given date, and allows for filtering by bicycle and dog allowances.

Query parameters

  • origin string(uuid) Required

    The ID of the origin station

  • destination string(uuid) Required

    The ID of the destination station

  • date string(date-time) Required

    The date and time of the trip in ISO 8601 format in origin station's timezone.

  • bicycles boolean

    Only return trips where bicycles are known to be allowed

    Default value is false.

  • dogs boolean

    Only return trips where dogs are known to be allowed

    Default value is false.

Responses

  • A list of available train trips

    Hide headers attribute Show headers attribute
    • The RateLimit header communicates quota policies. It contains a limit to convey the expiring limit, remaining to convey the remaining quota units, and reset to convey the time window reset time.

    Hide response attributes Show response attributes object
    • data array[object]
      Hide data attributes Show data attributes object
      • id string(uuid)

        Unique identifier for the trip

      • origin string

        The starting station of the trip

      • The destination station of the trip

      • departure_time string(date-time)

        The date and time when the trip departs

      • arrival_time string(date-time)

        The date and time when the trip arrives

      • operator string

        The name of the operator of the trip

      • price number

        The cost of the trip

      • Indicates whether bicycles are allowed on the trip

      • Indicates whether dogs are allowed on the trip

    Hide response attributes Show response attributes object
    • data array[object]
      Hide data attributes Show data attributes object
      • id string(uuid)

        Unique identifier for the trip

      • origin string

        The starting station of the trip

      • The destination station of the trip

      • departure_time string(date-time)

        The date and time when the trip departs

      • arrival_time string(date-time)

        The date and time when the trip arrives

      • operator string

        The name of the operator of the trip

      • price number

        The cost of the trip

      • Indicates whether bicycles are allowed on the trip

      • Indicates whether dogs are allowed on the trip

  • Bad Request

    Hide headers attribute Show headers attribute
    • The RateLimit header communicates quota policies. It contains a limit to convey the expiring limit, remaining to convey the remaining quota units, and reset to convey the time window reset time.

    Hide response attributes Show response attributes object
    • type string

      A URI reference that identifies the problem type

    • title string

      A short, human-readable summary of the problem type

    • detail string

      A human-readable explanation specific to this occurrence of the problem

    • instance string

      A URI reference that identifies the specific occurrence of the problem

    • status integer

      The HTTP status code

    Hide response attributes Show response attributes object
    • type string

      A URI reference that identifies the problem type

    • title string

      A short, human-readable summary of the problem type

    • detail string

      A human-readable explanation specific to this occurrence of the problem

    • instance string

      A URI reference that identifies the specific occurrence of the problem

    • status integer

      The HTTP status code

  • Unauthorized

    Hide headers attribute Show headers attribute
    • The RateLimit header communicates quota policies. It contains a limit to convey the expiring limit, remaining to convey the remaining quota units, and reset to convey the time window reset time.

    Hide response attributes Show response attributes object
    • type string

      A URI reference that identifies the problem type

    • title string

      A short, human-readable summary of the problem type

    • detail string

      A human-readable explanation specific to this occurrence of the problem

    • instance string

      A URI reference that identifies the specific occurrence of the problem

    • status integer

      The HTTP status code

    Hide response attributes Show response attributes object
    • type string

      A URI reference that identifies the problem type

    • title string

      A short, human-readable summary of the problem type

    • detail string

      A human-readable explanation specific to this occurrence of the problem

    • instance string

      A URI reference that identifies the specific occurrence of the problem

    • status integer

      The HTTP status code

  • Forbidden

    Hide headers attribute Show headers attribute
    • The RateLimit header communicates quota policies. It contains a limit to convey the expiring limit, remaining to convey the remaining quota units, and reset to convey the time window reset time.

    Hide response attributes Show response attributes object
    • type string

      A URI reference that identifies the problem type

    • title string

      A short, human-readable summary of the problem type

    • detail string

      A human-readable explanation specific to this occurrence of the problem

    • instance string

      A URI reference that identifies the specific occurrence of the problem

    • status integer

      The HTTP status code

    Hide response attributes Show response attributes object
    • type string

      A URI reference that identifies the problem type

    • title string

      A short, human-readable summary of the problem type

    • detail string

      A human-readable explanation specific to this occurrence of the problem

    • instance string

      A URI reference that identifies the specific occurrence of the problem

    • status integer

      The HTTP status code

  • Too Many Requests

    Hide headers attributes Show headers attributes
    • The RateLimit header communicates quota policies. It contains a limit to convey the expiring limit, remaining to convey the remaining quota units, and reset to convey the time window reset time.

    • The Retry-After header indicates how long the user agent should wait before making a follow-up request. The value is in seconds and can be an integer or a date in the future. If the value is an integer, it indicates the number of seconds to wait. If the value is a date, it indicates the time at which the user agent should make a follow-up request.

    Hide response attributes Show response attributes object
    • type string

      A URI reference that identifies the problem type

    • title string

      A short, human-readable summary of the problem type

    • detail string

      A human-readable explanation specific to this occurrence of the problem

    • instance string

      A URI reference that identifies the specific occurrence of the problem

    • status integer

      The HTTP status code

    Hide response attributes Show response attributes object
    • type string

      A URI reference that identifies the problem type

    • title string

      A short, human-readable summary of the problem type

    • detail string

      A human-readable explanation specific to this occurrence of the problem

    • instance string

      A URI reference that identifies the specific occurrence of the problem

    • status integer

      The HTTP status code

  • Internal Server Error

    Hide headers attribute Show headers attribute
    • The RateLimit header communicates quota policies. It contains a limit to convey the expiring limit, remaining to convey the remaining quota units, and reset to convey the time window reset time.

    Hide response attributes Show response attributes object
    • type string

      A URI reference that identifies the problem type

    • title string

      A short, human-readable summary of the problem type

    • detail string

      A human-readable explanation specific to this occurrence of the problem

    • instance string

      A URI reference that identifies the specific occurrence of the problem

    • status integer

      The HTTP status code

    Hide response attributes Show response attributes object
    • type string

      A URI reference that identifies the problem type

    • title string

      A short, human-readable summary of the problem type

    • detail string

      A human-readable explanation specific to this occurrence of the problem

    • instance string

      A URI reference that identifies the specific occurrence of the problem

    • status integer

      The HTTP status code

GET /trips
curl \
 -X GET https://api.example.com/trips?origin=efdbb9d1-02c2-4bc3-afb7-6788d8782b1e&destination=b2e783e1-c824-4d63-b37a-d8d698862f1d&date=2024-02-01T09%3A00%3A00Z \
 -H "Authorization: Bearer $ACCESS_TOKEN"
Response examples (200)
# Headers
RateLimit: limit=10, remaining=0, reset=10

# Payload
{
  "data": [
    {
      "id": "ea399ba1-6d95-433f-92d1-83f67b775594",
      "origin": "efdbb9d1-02c2-4bc3-afb7-6788d8782b1e",
      "destination": "b2e783e1-c824-4d63-b37a-d8d698862f1d",
      "departure_time": "2024-02-01T10:00:00Z",
      "arrival_time": "2024-02-01T16:00:00Z",
      "price": 50,
      "operator": "Deutsche Bahn",
      "bicycles_allowed": true,
      "dogs_allowed": true
    },
    {
      "id": "4d67459c-af07-40bb-bb12-178dbb88e09f",
      "origin": "b2e783e1-c824-4d63-b37a-d8d698862f1d",
      "destination": "efdbb9d1-02c2-4bc3-afb7-6788d8782b1e",
      "departure_time": "2024-02-01T12:00:00Z",
      "arrival_time": "2024-02-01T18:00:00Z",
      "price": 50,
      "operator": "SNCF",
      "bicycles_allowed": true,
      "dogs_allowed": true
    }
  ],
  "links": {
    "self": "https://api.example.com/trips?origin=efdbb9d1-02c2-4bc3-afb7-6788d8782b1e&destination=b2e783e1-c824-4d63-b37a-d8d698862f1d&date=2024-02-01",
    "next": "https://api.example.com/trips?origin=efdbb9d1-02c2-4bc3-afb7-6788d8782b1e&destination=b2e783e1-c824-4d63-b37a-d8d698862f1d&date=2024-02-01&page=2"
  }
}
Response examples (200)
# Headers
RateLimit: limit=10, remaining=0, reset=10

# Payload
<?xml version="1.0" encoding="UTF-8"?>
<root>
  <data type="array">
    <datum>
      <id>4f4e4e1-c824-4d63-b37a-d8d698862f1d</id>
      <origin>Berlin Hauptbahnhof</origin>
      <destination>Paris Gare du Nord</destination>
      <departure-time>2024-02-01T10:00:00Z</departure-time>
      <arrival-time>2024-02-01T16:00:00Z</arrival-time>
      <operator>Deutsche Bahn</operator>
      <price type="integer">50</price>
      <bicycles-allowed type="boolean">true</bicycles-allowed>
      <dogs-allowed type="boolean">true</dogs-allowed>
    </datum>
  </data>
  <links>
    <self>https://example.com</self>
    <next>https://example.com</next>
    <prev>https://example.com</prev>
  </links>
</root>
Response examples (400)
# Headers
RateLimit: limit=10, remaining=0, reset=10

# Payload
{
  "type": "https://example.com/errors/bad-request",
  "title": "Bad Request",
  "status": 400,
  "detail": "The request is invalid or missing required parameters."
}
Response examples (400)
# Headers
RateLimit: limit=10, remaining=0, reset=10

# Payload
{
  "type": "https://example.com/errors/bad-request",
  "title": "Bad Request",
  "status": 400,
  "detail": "The request is invalid or missing required parameters."
}
Response examples (401)
# Headers
RateLimit: limit=10, remaining=0, reset=10

# Payload
{
  "type": "https://example.com/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "You do not have the necessary permissions."
}
Response examples (401)
# Headers
RateLimit: limit=10, remaining=0, reset=10

# Payload
{
  "type": "https://example.com/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "You do not have the necessary permissions."
}
Response examples (403)
# Headers
RateLimit: limit=10, remaining=0, reset=10

# Payload
{
  "type": "https://example.com/errors/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "Access is forbidden with the provided credentials."
}
Response examples (403)
# Headers
RateLimit: limit=10, remaining=0, reset=10

# Payload
{
  "type": "https://example.com/errors/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "Access is forbidden with the provided credentials."
}
Response examples (429)
# Headers
RateLimit: limit=10, remaining=0, reset=10
Retry-After: 120

# Payload
{
  "type": "https://example.com/errors/too-many-requests",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "You have exceeded the rate limit."
}
Response examples (429)
# Headers
RateLimit: limit=10, remaining=0, reset=10
Retry-After: 120

# Payload
{
  "type": "https://example.com/errors/too-many-requests",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "You have exceeded the rate limit."
}
Response examples (500)
# Headers
RateLimit: limit=10, remaining=0, reset=10

# Payload
{
  "type": "https://example.com/errors/internal-server-error",
  "title": "Internal Server Error",
  "status": 500,
  "detail": "An unexpected error occurred."
}
Response examples (500)
# Headers
RateLimit: limit=10, remaining=0, reset=10

# Payload
{
  "type": "https://example.com/errors/internal-server-error",
  "title": "Internal Server Error",
  "status": 500,
  "detail": "An unexpected error occurred."
}