Suggestion Service
Our suggestion service enhances the search experience by giving suggestions of locations to users while they search in your interface. You can view the suggestion service in action in our booking engine solution.
Suggestion Options
We can provide 2 solutions using this endpoint:
- Popular Destinations: This solution provides a list of the most popular destinations in terms of searches and bookings based on the carriers you have access to.
- Dynamic Search: This solution provides a list of possible locations in response to what users type into a depature and arrival location fields based on the carriers you have access to.
Please note that this is an enterprise API feature. Reach out to your Partnership Manager for more information about unlocking this and other advanced features.
API Workflow For Popular Destinations
- When the user clicks on the departure location field in your UI make a GET request to the /locations endpoint. This will populate the most common list of departure locations. Use the response to show as suggestions in the field.
API Workflow For Dynamic Search
- When the user starts typing, update the drop-down based on the user's input. To do that make another request to the /locations endpoint by adding the
qparameter with the value input by the user. For exampleq=berlin. - Each time the text input by the user changes, you should make a new call. To make the experience better we recommend adding a delay of 300ms for the user to stop typing and then make a new request to the /locations.
- When the user selects a departure from the list and move to the arrival location field make a new request to /locations adding the location into the depature parameters. For example, if the user selects the city of Berlin from the list, add the parameters
departureLocation=DEBERanddepartureLocationType=city. This will show the list of popular arrival locations. - When the user starts typing the arrival location, update the drop-down based on the user's input again. Make another request to the /locations endpoint by adding the
qparameter alongside thedepartureLocation=DEBERanddepartureLocationType=cityparameters.
This endpoint currently doesn't require authentication and is available via the URL https://global-api.distribusion.com/.
Parameters
rpn: Set the retailer partner number (RPN). Contact your partnership manager to receive yours. Reference value: 012345.q: Letters typed by the user into your UI field.locale: Set the language for the content of the response. The field accepts ISO 639 language codes. If the content in the specified language is unavailable, English will be returned. For more details check our Languages guide. Reference value: en.limitTopLevel: Number of results. Reference value: 10.departureLocation: Selected departure location code. Only used to get arrival results based on the departure location selected by the user. It can be a station, area or city. Reference value: CHGVA.departureLocationType- Selected departure location type. Only used to get arrival results based on the departure location selected by the user. It can be station, area or city. Reference value: city.
API Examples
Sample Request to /locations
Plain text
https://global-api.distribusion.com/suggestion-service/v3/locations?rpn={retailer_partner_number}&limitTopLevel=10&locale=en&q=berlinSample Response from /locations
JSON
{
"locations": [
{
"timestamp": 1729832408388,
"type": "city",
"code": "DEBER",
"countryCode": "DE",
"subdivisionCode": null,
"parentLocations": [],
"names": [
{
"languageCode": "en",
"name": "Berlin"
}
],
"score": 6978.9,
"bestMatch": "\u003Cem\u003EBerlin\u003C/em\u003E",
"childrenLocations": [
{
"timestamp": 1729832408388,
"type": "area",
"code": "DEBERBB",
"countryCode": "DE",
"subdivisionCode": null,
"parentLocations": [
{
"code": "DEBER",
"type": "city"
}
],
"names": [
{
"languageCode": "en",
"name": "Berlin Airport BER"
}
],
"score": 2773.9,
"bestMatch": "\u003Cem\u003EBerlin\u003C/em\u003E Airport BER",
"childrenLocations": [
{
"timestamp": 1729832408388,
"type": "station",
"code": "DEBERBFB",
"countryCode": "DE",
"subdivisionCode": null,
"parentLocations": [
{
"code": "DEBERBB",
"type": "area"
},
{
"code": "DEBER",
"type": "city"
}
],
"names": [
{
"languageCode": "en",
"name": "Berlin Airport BER Terminal 1&2 Train Station"
}
],
"score": 2762.5,
"bestMatch": "\u003Cem\u003EBerlin\u003C/em\u003E Airport BER Terminal 1&2 Train Station",
"childrenLocations": []
}
]
},
{
"timestamp": 1729832408388,
"type": "area",
"code": "DEBERBC",
"countryCode": "DE",
"subdivisionCode": null,
"parentLocations": [
{
"code": "DEBER",
"type": "city"
}
],
"names": [
{
"languageCode": "en",
"name": "Berlin Central Train Station"
}
],
"score": 1006.7,
"bestMatch": "\u003Cem\u003EBerlin\u003C/em\u003E Central Train Station",
"childrenLocations": [
{
"timestamp": 1729832408388,
"type": "station",
"code": "DEBERHBF",
"countryCode": "DE",
"subdivisionCode": null,
"parentLocations": [
{
"code": "DEBERBC",
"type": "area"
},
{
"code": "DEBER",
"type": "city"
}
],
"names": [
{
"languageCode": "en",
"name": "Berlin Central Train Station"
}
],
"score": 1006.7,
"bestMatch": "\u003Cem\u003EBerlin\u003C/em\u003E Central Train Station",
"childrenLocations": []
}
]
},
{
"timestamp": 1729832408388,
"type": "station",
"code": "DEBERBAB",
"countryCode": "DE",
"subdivisionCode": null,
"parentLocations": [
{
"code": "DEBER",
"type": "city"
}
],
"names": [
{
"languageCode": "en",
"name": "Berlin Alexanderplatz Train Station"
}
],
"score": 950.2,
"bestMatch": "\u003Cem\u003EBerlin\u003C/em\u003E Alexanderplatz Train Station",
"childrenLocations": []
},
{
"timestamp": 1729832408388,
"type": "area",
"code": "DEBERBE",
"countryCode": "DE",
"subdivisionCode": null,
"parentLocations": [
{
"code": "DEBER",
"type": "city"
}
],
"names": [
{
"languageCode": "en",
"name": "Berlin Central Bus Station"
}
],
"score": 731,
"bestMatch": "\u003Cem\u003EBerlin\u003C/em\u003E Central Bus Station",
"childrenLocations": [
{
"timestamp": 1729832408388,
"type": "station",
"code": "DEBERCBS",
"countryCode": "DE",
"subdivisionCode": null,
"parentLocations": [
{
"code": "DEBERBE",
"type": "area"
},
{
"code": "DEBER",
"type": "city"
}
],
"names": [
{
"languageCode": "en",
"name": "Berlin Central Bus Station"
}
],
"score": 699.7,
"bestMatch": "\u003Cem\u003EBerlin\u003C/em\u003E Central Bus Station",
"childrenLocations": []
}
]
},
{
"timestamp": 1729832408388,
"type": "area",
"code": "DEBERBI",
"countryCode": "DE",
"subdivisionCode": null,
"parentLocations": [
{
"code": "DEBER",
"type": "city"
}
],
"names": [
{
"languageCode": "en",
"name": "Berlin Südkreuz Train Station"
}
],
"score": 402.9,
"bestMatch": "\u003Cem\u003EBerlin\u003C/em\u003E Südkreuz Train Station",
"childrenLocations": [
{
"timestamp": 1729832408388,
"type": "station",
"code": "DEBERSDE",
"countryCode": "DE",
"subdivisionCode": null,
"parentLocations": [
{
"code": "DEBERBI",
"type": "area"
},
{
"code": "DEBER",
"type": "city"
}
],
"names": [
{
"languageCode": "en",
"name": "Berlin Südkreuz"
}
],
"score": 402.9,
"bestMatch": "\u003Cem\u003EBerlin\u003C/em\u003E Südkreuz",
"childrenLocations": []
}
]
}
]
}
]
}
Was this section helpful?
On this page
- Suggestion Service