Searching for Trips
Once the cities, areas, stations and marketing carrier metadata have been on-boarded, trips can be searched by using the /connections/find endpoint.
The /connections/find endpoint searches between two locations on a specified date of travel for all possible trips available for your credentials. The search itself can be used between cities, areas and stations as described in the Preparing Metadata section.
The response is carrier and vehicle-type agnostic and returns all available trips that fit the location parameters requested considering the carriers whitelisted for your account. The response provides all information required to display clear search results to the user including:
- The carrier operating the trip
- The mode of transport
- Departure and arrival station
- Travel times and duration
- Available fare classes with prices and features/amenities
- Cancellation/refund policies
Search Parameters
Locations
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.
The search workflow allows you to switch between departure and arrival location types to match the user search (particularly relevant for airport to city searches), such as below:
Area to City
&departure_area=GBLONLA
&arrival_city=GBLONStation to City
&departure_stations[]=GBLONLHB
&arrival_city=GBLONFor more details about locations and how to get the stations, areas and city codes needed for this step, check the Preparing Metadata section.
Geo Coordinates
The geo coordinate search allows retailers to query trip results using geographic coordinates, rather than relying on a predefined list of stations as explained above. Distribusion supports latitude and longitude coordinates with 6 decimals of precision e.g. 45.488126,9.203600 alongside radius in meters e.g. 1000.
For more details about how to search using coordinates check the Geo Coordinate Search guide.
UIC and IATA Codes
Distribusion API also offers the ability to search based on industry-specific identifiers such as IATA and UIC codes. These methods provide greater flexibility and precision for various search scenarios.
For more details about how to search IATA and UIC codes check the IATA and UIC Codes Search guide.
Return Trips
For return trips, we recommend to include both the inbound and outbound segments into the same request. This can be done by adding the return_date parameter. For more details, check our guide about Journey Types.
Passenger Age
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 with the parameters passengers[][pax] and passengers[][max_age] combined.
When searching for travel for multiple passengers, you should combine the relevant parameters into a single request. For example, if you need to book 2 adults aged 40, 1 baby aged 5 months, and 1 child aged 5 years, the request would look like this:
&passengers[][pax]=2&passengers[][max_age]=40
&passengers[][pax]=1
&passengers[][max_age]=0
&passengers[][pax]=1
&passengers[][max_age]=5Carrier Filter
To filter the results to a specific carrier you can use the parameter carrier_codes[] and the code of the carrier. The list of carriers available via your credentials and corresponding codes can be retrieved from the /marketing_carriers endpoint.
Departure & Arrival Times
To get more precise search results you can define the departure start and end times in your request. This allows users to search for a trip during a specific time of the day e.g. afternoon departing betwen 15:00 and 17:00. This is supported for the departure time with the parameters departure_start_time and departure_end_time, and for return trips you can also define the departure times of the return leg using return_start_time and return_end_time.
We recommned using these parameters to improve the search experience, particularly for carriers that are unable to deliver results for the full day such as Deutsche Bahn, Trenitalia and SNCF. For more details, check our Limited Day Content guide.
Search Results
Stations
Regardless of whether the user searched for a specific station, area or city, the search results should display the precise station 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} endpoint through the parameters trade_name and white_label_logo.
To understand more about marketing carriers and operating carriers check our Operating Carriers guide.
Fare Classes
Carriers usually have multiple fare classes available per departure. These fare classes present users with different options to book their trip. Each fare has differences in name, prices, features/amenities and cancellation policies. Carriers usually require that the full name of the fare class are displayed to users, in most cases in the local language, so we recommend not to rewrite or hide them. To understand more about it check our Fare Classes guide.
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 endpoint when displaying search results. Note that the value is displayed in seconds, so you must convert it to hours and minutes.
Journey Transfers
For full transparency, users should be shown whether, and how many, transfers are on the trip. Whether a journey has a transfer, it is shown in the /connections/find endpoint. An example of a trip with multiple parts, or segments, is shown below from FRNTENAN to FRPARPRB.
"segments": { "data": [ { "id": "TREN-ITMILMTB-ITBRIBAC-2024-09-05T14:07-2024-09-05T22:32-0", "type": "segments" }, { "id": "TREN-ITMILMTB-ITBRIBAC-2024-09-05T14:07-2024-09-05T22:32-1", "type": "segments" } ] }As you can see, the 0 and 1 at the end of each id identify 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 the transit point.
Leg Type
When return trips are requested, you can identify if the trips in the response correspond to a outbound or inbound leg by looking at the leg_type field that could return either outbound or inbound.
Features & Amenities
Carriers differentiate themselves by providing varying amenities, which are strongly recommended to be displayed in the search results, for example as icons. Features can be found in the /marketing_carriers/{marketing_carrier_id} endpoint, under fare_features but are also displayed in the /connections/find response. For some carriers such as Amtrak and SNCF they appear as amenities under the /connections/find response. To understand more about it check our Features & Amenities guide.
Cancellation & Refund Policies
The fare and carrier’s cancellation policy for the chosen trip and fare class are communicated through fare_features as well that are provided in the /marketing_carriers/{marketing_carrier_id} and /connections/find endpoints. To understand more about it check our Cancellation & Refund Policies guide.
Line Details
Some carriers include the line details under the vehicle_number, line and line_prefix fields. We recommend adding this information to your interface to allow user to know more about the line they are booking.
Seats Left
Some carriers return information about the amount of seats left under the total_seats_left (total seats left in the departure) and seats_left (seats left per fare class) field. This can be used in your UI to create a sense of urgency with users. You might want to display this only when the number of seats is below a low number such as 10 or 5. A null value for seats_left means the carrier did not provide seat availability information; this should not be interpreted as an absence of vacant seats.
Ticket Validity
Some tickets can be used for a whole day or multiple days. This information does not appear under the /connections/find response, but it can be sourced from the /marketing_carriers/{marketing_carrier_id} endpoint. For more details check our Ticket Validity guide.
Enterprise Features
Refer to the our Discount Cards and Emissions Data guides to further enrich the search experience.
Best Practices
- Do not cache our search results: For the Distribusion search flow we recommend having live search calls straight to the Distribusion API. This means that customers are receiving the most up to date content available, with no issues created from large caching. If this isn’t possible, we recommend keeping the search cache as small as possible. Our search information - both pricing and vacancy - is frequently changing and therefore to reduce any change or errors on the front-end for your customers, the most up to date information is required.
- List all fare classes available: To give users the ability to find the best options available from the carriers we recommend displaying all the fare classes available, instead of just the cheapest one.
- Display all fare features with icons and descriptions (including fare amenities): The fare features/amenities allow users to understand more about the differences in prices, so we recommend you make them visible alongside the other details of the fares.
- Display the cancellation, refund and amendment policies for each fare class: Whether they are presented as
fare_featuresorfare_conditions, it is important to highlight these clearly to users to help them understand what is allowed for each fare. We recommend showing them separetely from the generalfare_featuressuch as WiFi or Power Socket. - Choose the ideal currency: Distribusion can display the prices in 160+ currencies. You can allow your users to select the currency they need in your interface and send all the requests using the matching currency. When the carrier currency doesn't match the currency of the request, Distribusion applies our standard conversion rate to deliver the prices to you. In order to mitigate a difference in prices in comparison to the carrier’s own website, we recommend requesting the carrier’s local currency, which can be identified through the currency parameter in the /marketing_carriers/{marketing_carrier_id} endpoint.
API Examples
Sample Request to /connections/find
https://api.demo.distribusion.com/retailers/v4/connections/find?locale=en¤cy=EUR&departure_stations[]=GBLONLHB&arrival_city=GBLON&departure_date=2024-09-05&departure_start_time=23:45&passengers[][pax]=1&passengers[][max_age]=40Sample Response from /connections/find
{
"data": [
{
"attributes": {
"arrival_time": "2024-09-06T00:25",
"booked_out": false,
"cheapest_fare_class_code": "FARE-1",
"cheapest_total_adult_price": 2968,
"departure_time": "2024-09-05T23:57",
"duration": 1680,
"electronic_ticket_available": false, "leg_type": "outbound",
"offer_bundle": null,
"offer_id": null,
"total_seats_left": null
},
"id": "HEXR-GBLONLHB-GBLONLPB-2024-09-05T23:57-2024-09-06T00:25",
"relationships": {
"arrival_station": {
"data": {
"id": "GBLONLPB",
"type": "stations"
}
},
"departure_station": {
"data": {
"id": "GBLONLHB",
"type": "stations"
}
},
"fares": {
"data": [
{
"fare_class": {
"code": "FARE-1",
"id": "HEXR-FARE-1",
"type": "fare_classes"
},
"id": "HEXR-GBLONLHB-GBLONLPB-2024-09-05T23:57-2024-09-06T00:25-FARE-1",
"original_price": 2968,
"price": 2968,
"type": "fares"
},
{
"fare_class": {
"code": "FARE-3",
"id": "HEXR-FARE-3",
"type": "fare_classes"
},
"id": "HEXR-GBLONLHB-GBLONLPB-2024-09-05T23:57-2024-09-06T00:25-FARE-3",
"original_price": 3799,
"price": 3799,
"type": "fares"
},
{
"fare_class": {
"code": "FARE-2",
"id": "HEXR-FARE-2",
"type": "fare_classes"
},
"id": "HEXR-GBLONLHB-GBLONLPB-2024-09-05T23:57-2024-09-06T00:25-FARE-2",
"original_price": 4571,
"price": 4571,
"type": "fares"
},
{
"fare_class": {
"code": "FARE-4",
"id": "HEXR-FARE-4",
"type": "fare_classes"
},
"id": "HEXR-GBLONLHB-GBLONLPB-2024-09-05T23:57-2024-09-06T00:25-FARE-4",
"original_price": 6530,
"price": 6530,
"type": "fares"
}
]
},
"marketing_carrier": {
"data": {
"id": "HEXR",
"type": "marketing_carriers"
}
},
"segments": {
"data": [
{
"id": "HEXR-GBLONLHB-GBLONLPB-2024-09-05T23:57-2024-09-06T00:25-0",
"type": "segments"
}
]
}
},
"type": "connections"
}
],
"included": [
{
"attributes": {
"arrival_time": "2024-09-06T00:25",
"departure_time": "2024-09-05T23:57",
"index": 0
},
"id": "HEXR-GBLONLHB-GBLONLPB-2024-09-05T23:57-2024-09-06T00:25-0",
"relationships": {
"amenities": {
"data": []
},
"arrival_station": {
"data": {
"id": "GBLONLPB",
"type": "stations"
}
},
"departure_station": {
"data": {
"id": "GBLONLHB",
"type": "stations"
}
},
"fares": {
"data": []
},
"marketing_carrier": {
"data": {
"id": "HEXR",
"type": "marketing_carriers"
}
},
"operating_carrier": {
"data": {
"id": "HEXR",
"type": "operating_carriers"
}
},
"vehicle": {
"data": {
"id": "TRAIN-HEXR-GBLONLHB-GBLONLPB-2024-09-05T23:57-2024-09-06T00:25-0",
"type": "vehicles"
}
}
},
"type": "segments"
},
{
"id": "TRAIN-HEXR-GBLONLHB-GBLONLPB-2024-09-05T23:57-2024-09-06T00:25-0",
"relationships": {
"vehicle_type": {
"data": {
"id": "TRAIN",
"type": "vehicle_types"
}
}
},
"type": "vehicles"
},
{
"attributes": {
"code": "TRAIN"
},
"id": "TRAIN",
"type": "vehicle_types"
},
{
"attributes": {
"booked_out": null,
"original_price": 2968,
"price": 2968,
"seats_left": null
},
"id": "HEXR-GBLONLHB-GBLONLPB-2024-09-05T23:57-2024-09-06T00:25-FARE-1",
"relationships": {
"applied_cards": {
"data": []
},
"conditions": {
"data": []
},
"fare_class": {
"data": {
"id": "HEXR-FARE-1",
"type": "fare_classes"
}
}
},
"type": "fares"
},
{
"attributes": {
"booked_out": null,
"original_price": 3799,
"price": 3799,
"seats_left": null
},
"id": "HEXR-GBLONLHB-GBLONLPB-2024-09-05T23:57-2024-09-06T00:25-FARE-3",
"relationships": {
"applied_cards": {
"data": []
},
"conditions": {
"data": []
},
"fare_class": {
"data": {
"id": "HEXR-FARE-3",
"type": "fare_classes"
}
}
},
"type": "fares"
},
{
"attributes": {
"booked_out": null,
"original_price": 4571,
"price": 4571,
"seats_left": null
},
"id": "HEXR-GBLONLHB-GBLONLPB-2024-09-05T23:57-2024-09-06T00:25-FARE-2",
"relationships": {
"applied_cards": {
"data": []
},
"conditions": {
"data": []
},
"fare_class": {
"data": {
"id": "HEXR-FARE-2",
"type": "fare_classes"
}
}
},
"type": "fares"
},
{
"attributes": {
"booked_out": null,
"original_price": 6530,
"price": 6530,
"seats_left": null
},
"id": "HEXR-GBLONLHB-GBLONLPB-2024-09-05T23:57-2024-09-06T00:25-FARE-4",
"relationships": {
"applied_cards": {
"data": []
},
"conditions": {
"data": []
},
"fare_class": {
"data": {
"id": "HEXR-FARE-4",
"type": "fare_classes"
}
}
},
"type": "fares"
},
{
"attributes": {
"booking_fee": 0,
"code": "HEXR",
"legal_name": "Heathrow Express Services LTD",
"markup_fee_percentage": 0.0,
"trade_name": "Heathrow Express"
},
"id": "HEXR",
"relationships": {
"extra_types": {
"data": []
},
"fare_classes": {
"data": [
{
"id": "HEXR-FARE-1",
"type": "fare_classes"
},
{
"id": "HEXR-FARE-2",
"type": "fare_classes"
},
{
"id": "HEXR-FARE-3",
"type": "fare_classes"
},
{
"id": "HEXR-FARE-4",
"type": "fare_classes"
}
]
},
"passenger_types": {
"data": [
{
"id": "PNOS",
"type": "passenger_types"
},
{
"id": "PCIL",
"type": "passenger_types"
}
]
}
},
"type": "marketing_carriers"
},
{
"attributes": {
"code": "HEXR",
"legal_name": "Heathrow Express Services LTD",
"trade_name": "Heathrow Express"
},
"id": "HEXR",
"type": "operating_carriers"
},
{
"attributes": {
"code": "PNOS",
"description": "",
"max_age": 99,
"min_age": 16,
"name": "Adult"
},
"id": "PNOS",
"type": "passenger_types"
},
{
"attributes": {
"code": "PCIL",
"description": "",
"max_age": 15,
"min_age": 0,
"name": "Child"
},
"id": "PCIL",
"type": "passenger_types"
},
{
"attributes": {
"code": "GBLONLHB",
"description": "The train platform is located in Heathrow Airport T5 Train Station. Passengers should find the exact platform on the information display board based on the departure time and the destination.",
"latitude": 51.47150211170094,
"longitude": -0.48800687700041,
"name": "London Heathrow Airport T5 Train Station",
"street_and_number": "Heathrow Terminal 5",
"time_zone": "Europe/London",
"zip_code": "TW6 2GA"
},
"id": "GBLONLHB",
"relationships": {
"area": {
"data": {
"id": "GBLONLA",
"type": "areas"
}
},
"city": {
"data": {
"id": "GBLON",
"type": "cities"
}
}
},
"type": "stations"
},
{
"attributes": {
"code": "GBLONLPB",
"description": "The train platform is located in London Paddington Train Station. Passengers should find the exact platform on the information display board based on the departure time and the destination.",
"latitude": 51.516653,
"longitude": -0.176815,
"name": "London Paddington Train Station",
"street_and_number": "Praed St 146",
"time_zone": "Europe/London",
"zip_code": "W2 1RH"
},
"id": "GBLONLPB",
"relationships": {
"area": {
"data": null
},
"city": {
"data": {
"id": "GBLON",
"type": "cities"
}
}
},
"type": "stations"
},
{
"attributes": {
"code": "GBLON",
"name": "London"
},
"id": "GBLON",
"type": "cities"
},
{
"attributes": {
"code": "GBLONLA",
"name": "London Heathrow Airport "
},
"id": "GBLONLA",
"type": "areas"
},
{
"attributes": {
"code": "FARE-1",
"iata_category": null,
"journey_type": "single",
"name": "Standard"
},
"id": "HEXR-FARE-1",
"relationships": {
"fare_features": {
"data": [
{
"id": "HEXR-WIFI",
"type": "fare_features"
},
{
"id": "HEXR-MSYS",
"type": "fare_features"
},
{
"id": "HEXR-AAFR",
"type": "fare_features"
},
{
"id": "HEXR-REFU",
"type": "fare_features"
}
]
}
},
"type": "fare_classes"
},
{
"attributes": {
"code": "FARE-2",
"iata_category": null,
"journey_type": "open_return",
"name": "Standard return"
},
"id": "HEXR-FARE-2",
"relationships": {
"fare_features": {
"data": [
{
"id": "HEXR-WIFI",
"type": "fare_features"
},
{
"id": "HEXR-MSYS",
"type": "fare_features"
},
{
"id": "HEXR-AAFR",
"type": "fare_features"
},
{
"id": "HEXR-REFU",
"type": "fare_features"
}
]
}
},
"type": "fare_classes"
},
{
"attributes": {
"code": "FARE-3",
"iata_category": null,
"journey_type": "single",
"name": "First class"
},
"id": "HEXR-FARE-3",
"relationships": {
"fare_features": {
"data": [
{
"id": "HEXR-WIFI",
"type": "fare_features"
},
{
"id": "HEXR-TOIL",
"type": "fare_features"
},
{
"id": "HEXR-PSOC",
"type": "fare_features"
},
{
"id": "HEXR-MSYS",
"type": "fare_features"
},
{
"id": "HEXR-AAFR",
"type": "fare_features"
},
{
"id": "HEXR-REFU",
"type": "fare_features"
}
]
}
},
"type": "fare_classes"
},
{
"attributes": {
"code": "FARE-4",
"iata_category": null,
"journey_type": "open_return",
"name": "First Class return"
},
"id": "HEXR-FARE-4",
"relationships": {
"fare_features": {
"data": [
{
"id": "HEXR-WIFI",
"type": "fare_features"
},
{
"id": "HEXR-TOIL",
"type": "fare_features"
},
{
"id": "HEXR-PSOC",
"type": "fare_features"
},
{
"id": "HEXR-MSYS",
"type": "fare_features"
},
{
"id": "HEXR-AAFR",
"type": "fare_features"
},
{
"id": "HEXR-REFU",
"type": "fare_features"
}
]
}
},
"type": "fare_classes"
},
{
"attributes": {
"code": "AAFR",
"description": "The bus is easily accessible for people on wheelchairs.",
"name": "Accessible area for wheelchairs"
},
"id": "HEXR-AAFR",
"type": "fare_features"
},
{
"attributes": {
"code": "MSYS",
"description": "A media system is available on board.",
"name": "Media System"
},
"id": "HEXR-MSYS",
"type": "fare_features"
},
{
"attributes": {
"code": "PSOC",
"description": "Power supply is available at every seat.",
"name": "Power Socket"
},
"id": "HEXR-PSOC",
"type": "fare_features"
},
{
"attributes": {
"code": "REFU",
"description": "Passengers may be eligible for a refund depending on the type of ticket you have purchased. If you are eligible for a refund you can apply within 30 days of the expiry date on the tickets. The expiry date depends on the type of ticket you have purchased. Please check more information here: https://www.heathrowexpress.com/conditions-of-carriage#/",
"name": "Fully refundable"
},
"id": "HEXR-REFU",
"type": "fare_features"
},
{
"attributes": {
"code": "TOIL",
"description": "A toilet is available on board.",
"name": "Toilet"
},
"id": "HEXR-TOIL",
"type": "fare_features"
},
{
"attributes": {
"code": "WIFI",
"description": "Free wifi is available on board.",
"name": "Wifi"
},
"id": "HEXR-WIFI",
"type": "fare_features"
}
],
"jsonapi": {
"version": "1.0"
},
"meta": {
"currency": "EUR",
"locale": "en"
}
}For more sample responses, check the /connections/find endpoint page.
What made this section unhelpful for you?
On this page
- Searching for Trips