Skip to main content

Overview

Introduction​

The Autosuggest API returns a list of places that match a specified searchTerm.

tip

You can see examples of the nearest geo endpoints with this postman collection: Run in Postman

tip

You can see examples of the flights autosuggest endpoints with this postman collection: Run in Postman

How Its Used At Skyscanner​

We use the Autosuggest API to suggest a list of places to a user based on their input.

For example: in our flight search, we pass the user's partially complete searchTerm to the Autosuggest API to get a list of places that the user might be searching for.

We also use the data returned from Autosuggest to perform word highlighting on the results, and to populate the parameters for the flight search.

Concepts

The Autosuggest api returns results of places (i.e. PLACE_TYPE_CITY, PLACE_TYPE_AIRPORT, PLACE_TYPE_COUNTRY for flights) based on a searchTerm.

The API will return the closest match to the searchTerm, which will contain the necessary details to make a call to our Flights Live Prices APIor Flights Indicative API

Autosuggest example skyscanner

Highlighting (Flights)​

The highlighting field specifies which parts of a text can be emphasized as matching the searchTerm. It contains an array of arrays of index ranges, each indicating a subsection of the hierarchy value to be highlighted. The indices follow a zero-based numbering system, where the first character of hierarchy is at index 0.

Since the raw hierarchy value is typically not displayed to users, custom logic is often required to apply highlighting correctly in a user-facing context.

Example (Skyscanner Implementation)​

// ...
{
  "name": "London Heathrow",
  "hierarchy": "London Heathrow (LHR), London|England|United Kingdom",
  "type": "PLACE_TYPE_AIRPORT",
  "highlighting": [
    [0, 10],
    [23, 29]
  ]
}

Given:

  • The seachTerm - "London Hea"
  • The returned hierarchy value - "London Heathrow (LHR), London|England|United Kingdom"
  • And the highlighting ranges: [0, 10] and [23, 29]

Then:

  • The substrings to highlight are:
    • London Hea (indices 0–10)
    • London (indices 23–29)

However, since Skyscanner does not display the hierarchy value to the user, custom logic ensures that only the relevant visible parts are highlighted. In this case, the final highlighted output shown to users is: "London Heathrow (LHR)"

Autosuggest example skyscanner

Highlighting (Carhire and Hotels)​

For Carhire and Hotels, the highlighting comes in the form of a html emphasis tag.

For example, for the search term madri

{
  "highlight": {
    "hierarchy": "Province of <em>Madri</em>d|Community of <em>Madri</em>d|Spain",
    "name": "<em>Madri</em>d"
  }
}

Score (Hotels)​

The score is used to indicate which place is the most relevant (input + popularity etc) given the searchTerm.

Results are ranked by the highest score.

Flights Live Prices Use Case​

We will assume the user is searching in the flights vertical, and we want to feed the results into Flights Live Prices.

Since the Flights Live Prices only accepts PLACE_TYPE_CITY and PLACE_TYPE_AIRPORT, we will filter these in our request.

We will make a call to the AutoSuggest API on each character inputted, and assume the user has typed in London and hit enter.

The request to the Autosuggest API would look something like this:

curl --location --request POST 'https://partners.api.skyscanner.net/apiservices/v3/autosuggest/flights' \
--header 'x-api-key: your-api-key' \
--header 'Content-Type: application/json' \
--data-raw '{
  "query":{
    "market": "UK",
    "locale": "en-GB",
    "searchTerm": "London",
     "includedEntityTypes": [ "PLACE_TYPE_CITY", "PLACE_TYPE_AIRPORT"]
  }
}   '

In the response we see the closest matching types:

{
  "places": [
    {
      "entityId": "27544008",
      "iataCode": "LON",
      "parentId": "27544008",
      "name": "London",
      "countryId": "UK",
      "countryName": "United Kingdom",
      "cityName": "London",
      "location": "51.5041174139,-0.0943465343",
      "hierarchy": "London|England|United Kingdom",
      "type": "PLACE_TYPE_CITY",
      "highlighting": [[0, 6]]
    }
    // ... other places
  ]
}

We can choose to now take the entityId or the iataCode to feed that into Flights Live Prices. In this example, we will use the entityId of London, 27544008.

This will be placed under the origin_place_id or destination_place_id of the Flights Live Prices request.

curl --location --request POST 'https://partners.api.skyscanner.net/apiservices/v3/flights/live/search/create' \
--header 'x-api-key: your-api-key' \
--header 'Content-Type: application/json' \
--data-raw '{
    "query": {
        "market": "UK",
        "locale": "en-GB",
        "currency": "GBP",
        "query_legs": [
            {
                "origin_place_id": {
                    "entityId": "27544008"
                },
                "destination_place_id": {
                    "iata": "EDI"
                },
                "date": {
                    "year": 2022,
                    "month": 12,
                    "day": 22
                }
            }
        ],
        "adults": 1,
        "children_ages": [],
        "cabin_class": "CABIN_CLASS_ECONOMY",
        "excluded_agents_ids": [],
        "excluded_carriers_ids": [],
        "included_agents_ids": [],
        "included_carriers_ids": []
    }
}'

Flights Indicative Prices Use Case​

Since flights indicative allows for PLACE_TYPE_CITY, PLACE_TYPE_AIRPORT, PLACE_TYPE_COUNTRY, we do not need to filter the entity types.

We will make a call to the Autosuggest API to fetch places matching the searchTerm "United States".

curl --location --request POST 'https://partners.api.skyscanner.net/apiservices/v3/autosuggest/flights' \
--header 'x-api-key: your-api-key' \
--header 'Content-Type: application/json' \
--data-raw '{
  "query":{
    "market": "UK",
    "locale": "en-GB",
    "searchTerm": "United States"
  }
}   '

Taking the first result, we will use the entityId of the first result (29475437) and feed that into the Flights Indicative API

{
  "places": [
    {
      "entityId": "29475437",
      "iataCode": "US",
      "parentId": "29475437",
      "name": "United States",
      "countryId": "US",
      "countryName": "United States",
      "cityName": "",
      "location": "45.7566336986,-112.6892486287",
      "hierarchy": "United States",
      "type": "PLACE_TYPE_COUNTRY",
      "highlighting": [[0, 13]]
    }
    // ... other places
  ]
}

The Flights Indicative request to search from the United States to LAX (Los Angeles International Airport) over 2 months would look like this:

curl --location --request POST 'https://partners.api.skyscanner.net/apiservices/v3/flights/indicative/search' \
--header 'x-api-key: your-api-key' \
--header 'Content-Type: application/json' \
--data-raw '{
   "query":{
      "currency":"USD",
      "locale":"en-US",
      "market":"UK",
      "queryLegs":[
         {
            "destinationPlace":{
                "queryPlace":{
                    "entityId": "29475437"
                }

            },
            "originPlace":{
               "queryPlace":{
                    "iata": "LAX"
                }
            },
            "dateRange":{
               "startDate":{
                  "year":2024,
                  "month":6
               },
               "endDate":{
                  "year":2024,
                  "month":7
               }
            }
         }
      ],
      "dateTimeGroupingType": "DATE_TIME_GROUPING_TYPE_BY_MONTH"
   }
}'