### **Description** This endpoint can be used to retrieve all connections between the specified departure and arrival stations on a specific day. **Data preparation** In order for users to search for trips, the meta data related to marketing carriers and stations will need to be retrieved and stored locally, which can be achieved by making use of the [/marketing_carriers/{marketing_carrier_id}](https://lively-space-811588.postman.co/workspace/f46e13d3-12d7-41eb-86e4-45523c4a451d/request/18003295-4b7f6a67-704f-4c88-9f76-99fd6837d089?ctx=documentation), [/stations](https://lively-space-811588.postman.co/workspace/f46e13d3-12d7-41eb-86e4-45523c4a451d/request/18003295-d273a8e6-5331-4c9f-a515-433384136d05?ctx=documentation), [/cities](https://lively-space-811588.postman.co/workspace/f46e13d3-12d7-41eb-86e4-45523c4a451d/request/18003295-48bf5070-88e4-4db9-90b3-14916e88294f?ctx=documentation) and /areas endpoints. Once the stations and marketing carriers have been onboarded, trips can be searched by using the [/connections/find](https://lively-space-811588.postman.co/workspace/f46e13d3-12d7-41eb-86e4-45523c4a451d/request/18003295-7d7b6f93-3ca8-45fc-a7f6-bba7f0346667?ctx=documentation) endpoint. **How it works** This search endpoint is carrier agnostic and returns all trips that run between the requested stations on the specified date(s) of travel. The response provides all the information required to display clear search results to the user, including: - The carrier operating the trip - Departure and arrival station - Travel times & duration - Price - Available fare classes & amenities The /connections/find request can include up to 8 departure and 8 arrival stations. Discount cards in both booking and pax context can be passed as query parameters. The booking_id param should be passed when searching for available rides in amendment context. Please refer to the key concepts section for further information on [Discount Cards](https://api.distribusion.com/doc/key-concepts#discount-cards) and [Emissions data](https://api.distribusion.com/doc/key-concepts#emissions-data) that further enrich the search experience. At this stage the user should be able to view and select from all available trips and fare classes that are returned for the search query. **Station, area, city search** The [/connections/find endpoint](https://lively-space-811588.postman.co/workspace/f46e13d3-12d7-41eb-86e4-45523c4a451d/request/18003295-7d7b6f93-3ca8-45fc-a7f6-bba7f0346667?ctx=documentation) allows flexible search on a station, area (airport), or city level, depending on what the user inputs in the search interface. The following location parameters can be specified in the request: - `departure_stations[]` / `arrival_stations[]`: 8 letter code that denotes a specific station. - `departure_city` / `arrival_city`: 5 letter code that denotes the city and allows you to search for all stations within said city. - `departure_area` / `arrival_area`: 7 letter code that denotes an airport and allows you to search for all stations within said airport. When a user searches for a city or airport on your website / application, it is recommended to pass through the respective city or area code instead of creating a mapping to the respective stations. This is all taken care of within Distribusion’s system and will ensure that all relevant trips are returned. Please note that even if you search in our API on city or area level, the response will provide connections on a station level, implying that you still need to add metadata (such as name and location) on a station level to your system in order to correctly display available trips to users. **Searching for return trips** Searching for return tickets is the exact same process as for single tickets, with the addition of the `return_date` parameter which will retrieve all trips in the opposite direction on the date indicated. Similarly, please fill in the `return_departure_time` and `return_arrival_time` parameters when performing a vacancy search using the [/connections/vacancy](https://lively-space-811588.postman.co/workspace/f46e13d3-12d7-41eb-86e4-45523c4a451d/request/18003295-80418d62-9571-48c8-a250-7a8442fca8c6?ctx=documentation) endpoint. **Searching with passenger typed prices** As a default, the Distribusion API returns prices for Adult passenger type. However, if the age group or exact age of passengers is collected upon search, more precise pricing can be requested through the API. The response format does not differ depending on which passenger identifiers are passed. **Stations** Regardless of whether the user searched for a specific station or a city / airport, the search results should display the precise stops returned by the API for each trip so that the user can clearly see the departure and arrival locations. **Carriers** It is required to show the name of the carrier operating each trip that is displayed in the search results. We strongly recommend adding the carrier’s logo here as well, a great way to make use of the strong brands that some of the operators bring to your platform. This carrier metadata and much more can be retrieved from the [/marketing_carriers/{marketing_carrier_id}](https://lively-space-811588.postman.co/workspace/f46e13d3-12d7-41eb-86e4-45523c4a451d/request/18003295-4b7f6a67-704f-4c88-9f76-99fd6837d089?ctx=documentation) endpoint through the parameters `trade_name` and `white_label_logo`. We recommend refreshing logos on a weekly basis as these can change over time. **Journey duration** To help users easily compare journeys, it is useful to indicate the duration of each trip. Simply read and display the `duration` parameter under the [/connections/find](https://lively-space-811588.postman.co/workspace/f46e13d3-12d7-41eb-86e4-45523c4a451d/request/18003295-7d7b6f93-3ca8-45fc-a7f6-bba7f0346667?ctx=documentation) endpoint when displaying search results. **Journey transfers** For full transparency, users should be shown whether, and how many, transfers are on the trip. Whether a journey has a transfer is shown in the [/connections/find](https://lively-space-811588.postman.co/workspace/f46e13d3-12d7-41eb-86e4-45523c4a451d/request/18003295-7d7b6f93-3ca8-45fc-a7f6-bba7f0346667?ctx=documentation) endpoint. An example of a trip with multiple parts, or segments, is shown below from ATVIEVHS to CZPSEPBU. As you can see, the 0 and 1 highlighted in red demonstrate that the trip is made of 2 segments. If there is only a 0, this means that the vehicle moves directly from requested origin to destination. If you would like to locate the connecting station, scroll down until you see the connections section which shows CZPRGZOB as the transit point. **Mobile tickets** The majority of carriers accept tickets to be displayed on mobile devices, which is what users are accustomed to. The parameter `ticket_printing_required` in the [/marketing_carriers/{marketing_carrier_id}](https://lively-space-811588.postman.co/workspace/f46e13d3-12d7-41eb-86e4-45523c4a451d/request/18003295-4b7f6a67-704f-4c88-9f76-99fd6837d089?ctx=documentation) endpoint enables you to see which carriers do not need their tickets to be printed, we recommend surfacing this to your customers with an icon or text. We also recommend indicating the necessity of a hard copy during search results or at the checkout page. Learn more about ticketing in the [Ticketing](https://api.distribusion.com/doc/key-concepts#ticketing) section. **Amenities** Carriers differentiate themselves by providing varying amenities, which are strongly recommended to be displayed in the search results, for example as icons. Amenities can be found in the [/marketing_carriers/{marketing_carrier_id}](https://lively-space-811588.postman.co/workspace/f46e13d3-12d7-41eb-86e4-45523c4a451d/request/18003295-4b7f6a67-704f-4c88-9f76-99fd6837d089?ctx=documentation) endpoint, under fare class features. Please find the most common global amenities in [this table](https://api.distribusion.com/doc/key-concepts#id10). **Passenger types** Distribusion also makes it easier to integrate a large variety of carriers by harmonising all available passenger types into five standardised codes: - Infant: PINT - Child: PCIL - Youth: PYPO - Adult: PNOS - Senior: PSOE The availability and age range of each passenger type is dependent upon the respective marketing carrier’s policies. This information can be found in the [/marketing_carriers/{marketing_carrier_id}](https://lively-space-811588.postman.co/workspace/f46e13d3-12d7-41eb-86e4-45523c4a451d/request/18003295-4b7f6a67-704f-4c88-9f76-99fd6837d089?ctx=documentation) endpoint. The response displays the available passenger types for the respective carrier and details the age brackets associated with each available passenger type. To start selling Distribusion inventory, at minimum the passenger type Adult (PNOS) must be integrated. We recommend integrating all passenger types in order to be able to provide full parity on discounts to your customers, where available. **Journey types** Distribusion allows you to sell tickets for single and return journeys, please find the three distinct journey types available below: - Single `single`: Trip can be booked only one-way. - Open return `open_return`: Trip can be booked for outbound & inbound legs; whereby the inbound leg is not bound to a specific date of travel but rather to a time interval (e.g. 3 months). - Fixed return `fixed_return`: Trip can be booked for outbound & inbound legs; whereby both legs are bound to specific travel dates. Journey types are defined per fare class, please find additional details in the following [Fare Classes](https://api.distribusion.com/doc/key-concepts#id13) section. Even if a carrier does not support any explicit return journey types, Distribusion still allows return bookings to be placed within one user flow and request. Simply use a single journey fare class and specify a return date in the relevant API requests. **Fare classes** The Distribusion Retailer API also provides full parity on carrier fare class offerings. A fare class can describe both the class of travel / type of seat or bus (e.g. standard or first class, seat or bed), as well as the journey type (single, fixed return, open return) that is on offer. Fare classes are provided and detailed in two endpoints: - The [/marketing_carriers/{marketing_carrier_id}](https://lively-space-811588.postman.co/workspace/f46e13d3-12d7-41eb-86e4-45523c4a451d/request/18003295-4b7f6a67-704f-4c88-9f76-99fd6837d089?ctx=documentation) endpoint response includes all fare classes that the requested marketing carrier supports. Not every fare class supported by a carrier is necessarily available for every trip served by that carrier. - The [/connections/find](https://lively-space-811588.postman.co/workspace/f46e13d3-12d7-41eb-86e4-45523c4a451d/request/18003295-7d7b6f93-3ca8-45fc-a7f6-bba7f0346667?ctx=documentation) endpoint response includes the available fare classes for the selected trip(s) and their respective prices. In case only one fare class is available for a specific trip, only one fare class will be provided. Each fare class has its own code (as shown in the examples above) and is defined by the following parameters in the API: - `name` (as defined by the carrier and which can be displayed to the user) - `journey_type` (single vs. return types) - `fare_features` (amenities & cancellation policies) - `passenger_group_rules` (is there a limit to the number of passengers per type can be booked?) - `ticket_validity_rules` (is a ticket for this fare class valid for one fixed trip or a longer period of time?) Ticket validity rules are described by a number of further parameters, which are detailed below: - Type `outbound`; `inbound`: The rule applies to the inbound or outbound leg of the trip. - Use type `once`; `multiple`: Ticket can be used for a single or unlimited trips. - Reference time `departure_time`; `beginning_of_departure_day`; `purchase_time`; `beginning_of_purchase_day`; `outbound_voucher_redemption`; `inbound_voucher_redemption`: Anchor from which the ticket validity duration begins. - Offset `minutes`; `hours`; `days`; `months`: Buffer between reference time and start of validity duration. - Duration `minutes`; `hours`; `days`; `months`: Time window of ticket validity starting from reference time (plus offset) **Next step** Once the user selects their trip and departure, confirm the price and the availability of the seats for all passengers using the [/connections/vacancy](https://lively-space-811588.postman.co/workspace/f46e13d3-12d7-41eb-86e4-45523c4a451d/request/18003295-80418d62-9571-48c8-a250-7a8442fca8c6?ctx=documentation) endpoint. ### **More Info** - **Full API Integration** - [Basic workflow](https://api.distribusion.com/doc/full-api-integration#basic-workflow) - [Trip search](https://api.distribusion.com/doc/full-api-integration#trip-search) - **Key Concepts** - [Searching for trips](https://api.distribusion.com/doc/key-concepts#id3) - [Searching for return trips](https://api.distribusion.com/doc/key-concepts#searching-for-return-trips) - [Searching with passenger typed prices](https://api.distribusion.com/doc/key-concepts#searching-with-passenger-typed-prices) - [Displaying search results](https://api.distribusion.com/doc/key-concepts#id4) - [Stations](https://api.distribusion.com/doc/key-concepts#id5) - [Carriers](https://api.distribusion.com/doc/key-concepts#id6) - [Journey duration](https://api.distribusion.com/doc/key-concepts#id7) - [Journey transfers](https://api.distribusion.com/doc/key-concepts#id8) - [Mobile tickets](https://api.distribusion.com/doc/key-concepts#id9) - [Amenities](https://api.distribusion.com/doc/key-concepts#id10) - [Fare class and trip characteristics](https://api.distribusion.com/doc/key-concepts#id11) - [Passenger types](https://api.distribusion.com/doc/key-concepts#passenger-types) - [Journey types](https://api.distribusion.com/doc/key-concepts#id12) - [Fare classes](https://api.distribusion.com/doc/key-concepts#fare-classes) - [Discount cards](https://api.distribusion.com/doc/key-concepts#discount-cards) - [Types of supported discounts](https://api.distribusion.com/doc/key-concepts#types-of-supported-discounts) - [Parameters characterising discounts](https://api.distribusion.com/doc/key-concepts#parameters-characterising-discounts) - [API workflow](https://api.distribusion.com/doc/key-concepts#api-workflow) - [Emissions data](https://api.distribusion.com/doc/key-concepts#emissions-data) - [Amendments](https://api.distribusion.com/doc/key-concepts#amendments) - [Types of supported amendment operations](https://api.distribusion.com/doc/key-concepts#types-of-supported-amendment-operations) - [API workflow](https://api.distribusion.com/doc/key-concepts#id22) - [Emissions data](https://api.distribusion.com/doc/key-concepts#emissions-data) - [Virtual interlining](https://api.distribusion.com/doc/key-concepts#virtual-interlining) - [Currencies and locales](https://api.distribusion.com/doc/key-concepts#currencies-and-locales) - **Rail Requirements** - [Search Fields](https://docs.google.com/document/d/1s8ckJhKtO2BI81a_-zg5Q1Nnf1BcGEGYLGZCuSoHmMw/edit#heading=h.elebh2hmj7sy) - [Search Results](https://docs.google.com/document/d/1s8ckJhKtO2BI81a_-zg5Q1Nnf1BcGEGYLGZCuSoHmMw/edit#heading=h.rn22ye73l2gn) - **Endpoints** - [GET /retailers/v4/connections/find](https://api.distribusion.com/doc/api#get-retailers-v4-connections-find-connections-find)

Description

This endpoint is used to confirm the price and availability for the specified number and type of passengers for the selected trip. It is essential that you use this endpoint prior to allowing the customer to book and pay for the journey.

How it works

Once the user has selected a specific trip and proceeds to the checkout page on your platform, the next step is to call the /connections/vacancy endpoint.

The response includes the confirmation of availability and price for the requested combination of passengers on the selected trip.

In the rare event that the trip is no longer available (vacant: false), the customer must not be allowed to proceed to the checkout page. It is recommended to notify the user that this trip is now booked out and redirect to the results page with the option to select a new trip.

Next step

Once the price and availability is confirmed, allow users to select their seat using the /connections/seats endpoint.

More Info

• Full API integration
  • Trip selection and reservation
• Key Concepts
  • Ancillaries
    • Supported ancillaries
    • API workflow
  • Discount cards
    • Types of supported discounts
    • Parameters characterising discounts
    • API workflow
  • Amendments
    • Types of supported amendment operations
    • API workflow
  • Currencies and locales
  • Virtual interlining
• Rail Requirements
  • Search Fields
  • Search Results
• Endpoints
  • GET /retailers/v4/connections/vacancy

Description

This endpoint can be used to retrieve the seat layout of the bus for the requested trip. It will return all the information required for you to display the available seats to your user and allow a free seat to be selected, such as the seat label, vacancy status, fare class, and postition coordinates (x - row, y - column, z - level).

Supported carriers

Please ask your account manager if seat layouts are available for the carriers that you are integrating, as not all carriers support this functionality.

How it works

Carriers also often allow users to select the precise seat in which they will sit during the journey.

The Distribusion API supports surfacing the seat layout of the vehicle through the /connections/seats endpoint. The API returns a coordinate system based on which the seat map can be projected on the frontend. This option is most commonly exposed to the user on or just before the checkout page.

Whether or not a carrier supports seat selection can be identified through the /marketing_carriers/{marketing_carrier_id} endpoint.

API Workflow

1. Retrieve and display the seat map for the specific trip using the /connections/seats endpoint.
2. Once the user has selected the desired seat(s) specify the respective seat codes in the /reservations/create or /reservations/confirm request, depending on the point of the user flow in which the selection is being made. In case the journey is multi-segment, a seat code per segment must be specified.

Note

Seat preferences (e.g. aisle or window seat) and paid seat reservation are supported within the scope of the Ancillaries functionality.

Next step

Create a reservation or booking using the selected trip, departure and seats.

We recommend using the reservations flow. For that, create a reservation using the /reservations/create endpoint.

If you prefer to use the bookings flow, create a booking using the /bookings/create endpoint.

More Info

• Full API Integration
  • Basic workflow
• Key Concepts
  • Seat selection
    • API Workflow
• Endpoints
  • GET /retailers/v4/connections/seats