Search

Searches for available trips between two stations on a given date for a passenger party. This is the first step of the booking process; the returned trip.id values feed Trip Details, Recalculate, and Create Order.

Endpoint

Method: POST

URL: /v1/search

Request Headers

Parameter	Type	Required	Description
Authorization	String	Yes	Bearer <token> from Login

Request Parameters

Parameter	Type	Required	Description
└ departure	String	Yes	Departure station code
└ arrival	String	Yes	Arrival station code
└ date	String	Yes	Departure date (yyyy-MM-dd)
└ with_transfer	Boolean	No	Include trips with transfers (default false)
└ locale	String	No	Language, refer to Locale List
└ passengers	Object	Yes	Passenger party composition
└ adults	Integer	Yes	Number of adults (≥ 1)
└ children	Integer	No	Number of children (≥ 0)

Request Example

{
  "departure": "2200001",
  "arrival": "2218000",
  "date": "2026-07-01",
  "with_transfer": false,
  "locale": "en",
  "passengers": {
    "adults": 2,
    "children": 1
  }
}

Response Parameters

Parameter	Type	Required	Description
└ trips	[Object]	Yes	List of matching trips
└ id	String	Yes	Trip identifier (used by /trip, /recalculate, /order)
└ route_id	String	No	Route code
└ transport_id	String	No	Vehicle/transport code
└ route_name	String	No	Human-readable route name
└ with_transfer	Boolean	No	Trip has transfers
└ with_technical_stop	Boolean	No	Trip has technical stops
└ currency	String	Yes	Pricing currency
└ price	Number	Yes	Price per adult
└ seats_available	Integer	No	Total available seats
└ free_place_numbers	[String]	No	List of free seat numbers
└ has_place_numbers	Boolean	No	Whether seats are numbered (default true)
└ travel_time	Integer	No	Travel duration in seconds
└ fare_class_code	String	No	Fare class identifier
└ fare_class_name	String	No	Fare class name
└ luggage	String	No	Luggage policy text
└ regulations_url	String	No	Link to the carrier's rules
└ can_buy	Boolean	No	Bookable now? (default true)
└ images	[String]	No	Trip/carrier image URLs
└ departure	Place	Yes	Departure point (see Place)
└ arrival	Place	Yes	Arrival point (see Place)
└ carrier	Carrier	No	Carrier info (see Carrier)
└ amenities	Amenities	No	On-board amenity flags (see Amenities)
└ fares	[Fare]	Yes	Available fare options (see Fare)

The full Trip object (segments, seats, discounts, baggage, required passenger fields) is returned by Trip Details. On /search the trip carries summary pricing and the fare list.

Response Example

{
  "trips": [
    {
      "id": "trip_8f21",
      "route_id": "R-204",
      "route_name": "Kyiv — Lviv",
      "with_transfer": false,
      "currency": "UAH",
      "price": 650.0,
      "seats_available": 32,
      "travel_time": 28800,
      "can_buy": true,
      "departure": {
        "code": "2200001",
        "name": "Kyiv Central Bus Station",
        "datetime": "2026-07-01T08:00:00+03:00",
        "timezone": "Europe/Kyiv"
      },
      "arrival": {
        "code": "2218000",
        "name": "Lviv Bus Station",
        "datetime": "2026-07-01T16:00:00+03:00",
        "timezone": "Europe/Kyiv"
      },
      "carrier": { "id": "C-12", "name": "Example Lines" },
      "fares": [
        { "code": "adult", "name": "Standard", "price": 650.0, "currency": "UAH", "is_default": true }
      ]
    }
  ]
}

Shared Schemas

Place

Parameter	Type	Description
code	String	Station code
name	String	Station name
address	String	Physical address
country_code	String	ISO country code
datetime	String	Departure/arrival time, ISO-8601 with timezone offset
timezone	String	IANA timezone (e.g. Europe/Kyiv)
latitude	Number	Latitude
longitude	Number	Longitude

Carrier

Parameter	Type	Description
id	String	Carrier id
name	String	Carrier name
phone	String	Contact phone
email	String	Contact email
icon	String	Logo/icon URL
inn	String	Tax id
rating	Number	Carrier rating

Amenities

A boolean map of on-board amenity flags. Recognised keys: has_air_conditioning, has_tv, has_wifi, has_power, has_wc, has_coffee, has_music, has_baggage, has_bulky_baggage, has_seat_map, has_child_seat, has_usb, has_food, has_seat_belt, has_extra_space, has_pets_allowed, has_disable_accessibility, has_quiet_zone, has_reserved_seats. Unknown keys are ignored.

Fare

Parameter	Type	Required	Description
code	String	Yes	Fare code (e.g. adult)
name	String	No	Fare name
price	Number	Yes	Fare price
currency	String	No	Currency
is_default	Boolean	No	Default fare?
cancellation_info	[CancellationRule]	No	Per-fare cancellation rules (see Trip Details)

Error Code List

code	message	Description
UNAUTHORIZED	Invalid token	The bearer token is missing, invalid, or expired (401).