API explorerChangelog
API

Sections

API explorer
Changelog

Theme switcher

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:

  1. 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.
  2. 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

  1. 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

  1. 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.
  2. 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.
  3. 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.
  4. 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.

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

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": []
            }
          ]
        }
      ]
    }
  ]
}
Was this section helpful?

What made this section unhelpful for you?

On this page
  • Suggestion Service
View as Markdown

Ask an AI

Open in ChatGPTOpen in ClaudeOpen in Perplexity

Code with AI

Open in Copilot