# Retrieve autocomplete suggestions

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.

Endpoint: POST /common/autocomplete
Version: 3.3
Security: BearerAuth

## Security:

  - `BearerAuth` (unknown)
    http bearer string

## Header parameters:

  - `X-Affiliate-Id` (integer, required)
    Include here your Affiliate identifier number

## Request fields (application/json):

  - `query` (string, required)
    Free-text query used to generate suggestions. Leading and trailing whitespace is ignored when matching. Provide between 3 and 200 characters.

  - `language` (string)
    A [IETF language tag code](https://en.wikipedia.org/wiki/IETF_language_tag) that uniquely identifies a supported human language or dialect. **Note:** Demand API only accepts lowercase for the language codes. Examples: "nl" for Dutch/Nederlands or "en-us" for English (US). To retrieve the full list of supported languages, call the `/common/languages` endpoint.
    Example: en-us

  - `country` (string, required)
    A two-letter code that uniquely identifies a country. This code is defined by the ISO 3166-1 alpha-2 standard (ISO2) as described here: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2. The full list can be obtained by calling the /common/locations/countries endpoint.
    Example: nl

  - `filters` (object)
    Filters the suggestions by destination type.

  - `filters.types` (array)
    Destination types to include in the results. If omitted from the request, suggestions may include any destination type.

## Request examples:

  - `Search for cities beginning with "amster" in the Netherlands` (unknown)

## Response 200:

  - `200` (unknown)
    Successful response containing ranked suggestions. The data array may be empty when no suggestions match the query.

## Response 200 fields (application/json):

  - `request_id` (string)
    Uniquely identifies the request. Please provide this identifier when contacting support.

  - `data` (array)
    Suggestions ranked by relevance. This array is empty when no suggestions match the query.

  - `data.type` (string)
    The type of destination represented by an autocomplete suggestion.
    Enum: "airport", "hotel", "landmark", "city", "district", "region", "country"

  - `data.name` (object)
    A string localised in multiple languages.

  - `data.id` (string)
    The identifier of the destination. The format depends on the destination type.

  - `data.location` (object)
    Geographic details for a suggestion, such as its city, country or coordinates. Available fields depend on the destination type.

  - `data.location.city` (integer)
    A signed integer number that uniquely identifies a city. The full list can be obtained by calling common/locations/cities.

  - `data.location.coordinates` (object)

  - `data.location.coordinates.latitude` (number)

  - `data.location.coordinates.longitude` (number)

  - `data.location.country` (string)
    A two-letter code that uniquely identifies a country. This code is defined by the ISO 3166-1 alpha-2 standard (ISO2) as described here: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2. The full list can be obtained by calling the /common/locations/countries endpoint.
    Example: nl

## Response 400:

  - `400` (unknown)
    The request is invalid or contains unsupported parameter values (for example, query too short or invalid `filters.types`). Refer to the [Error handling section](/demand/docs/support/error-handling/about-errors) for more details.

## Response 400 fields (application/json):

  - `request_id` (string, required)
    Uniquely identifies the request. Please provide this identifier when contacting support.

  - `errors` (array, required)

  - `errors.id` (string, required)

  - `errors.message` (string, required)

## Response 500:

  - `500` (unknown)
    Internal server error.

## Response 200 examples:

  - `City suggestions matching the request` (unknown)