API

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.

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 q parameter with the value input by the user. For example q=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=DEBER and departureLocationType=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 q parameter alongside the departureLocation=DEBER and departureLocationType=city parameters.

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=berlinhttps://global-api.distribusion.com/suggestion-service/v3/locations?rpn={retailer_partner_number}&limitTopLevel=10&locale=en&q=berlin

Sample 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": []
            }
          ]
        }
      ]
    }
  ]
}

Sections