Skip to content
API REFERENCES/
/Autocomplete

Autocomplete

Use this endpoint to retrieve ranked suggestions based on a free-text query. Designed for real-time "as-you-type" autocomplete experiences.

Operations

Retrieve autocomplete suggestions

Request

Returns ranked destination suggestions for a free-text query. Use this endpoint to provide suggestions as a user types.

Results are ranked using destination popularity and the supplied country context. The endpoint supports prefix matching and basic typo tolerance. Use filters.types to restrict results to specific destination types.

Each result includes a destination type, identifier, localised name and geographic context. Geographic details vary by destination type and may be unavailable.

Security
BearerAuth
Headers
X-Affiliate-Idintegerrequired

Include here your Affiliate identifier number

Bodyapplication/jsonrequired
querystring, [ 3 .. 200 ] charactersrequired

Free-text query used to generate suggestions. Leading and trailing whitespace is ignored when matching. Provide between 3 and 200 characters.

languagestring(languageId)^[a-z]{2}(-[a-z]{2})?$

Language code used to localise names in the response. Only one language can be specified per request.

Default:"en-gb"
Example:"en-us"
countrystring(countryId)^[a-z]{2}$required

Lowercase ISO 3166-1 alpha-2 country code used as the primary country context for ranking suggestions.

Example:"nl"
filtersobject(AutoCompleteFilters)

Optional filters for restricting results by destination type. Omit this property to include all destination types.

curl -i -X POST \
  https://demandapi.booking.com/3.3/common/autocomplete \
  -H 'Authorization: Bearer <YOUR_string_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'X-Affiliate-Id: 0' \
  -d '{
    "query": "amster",
    "language": "en-gb",
    "country": "nl",
    "filters": {
      "types": [
        "city"
      ]
    }
  }'

Responses

Successful response containing ranked suggestions. The data array may be empty when no suggestions match the query.

Bodyapplication/json
request_idstring(requestId)

Uniquely identifies the request. Please provide this identifier when contacting support.

dataArray of objects(AutoCompleteResultOutput)

Suggestions ranked by relevance. This array is empty when no suggestions match the query.

Response
{
  "request_id": "01khs9q981dta9fptx2edvq9r3",
  "data": [
    { … }
  ]
}