# Using the autocomplete endpoint

**Retrieve ranked destination suggestions for real-time search experiences.**

## Overview

→ Use the [/common/autocomplete endpoint](/demand/docs/open-api/3.2-beta/demand-api/commonautocomplete) to help travellers find destinations quickly while typing.

The endpoint is optimised for low-latency, "as-you-type" search and returns ranked suggestions based on the search query, destination popularity, and the provided context.

Autocomplete supports:

* Prefix matching.
* Basic typo tolerance.
* Localised destination names.
* Destination type filtering.


The endpoint can be used across accommodation, car rental, attractions, and AI-powered travel experiences.

### When to use this endpoint

Use autocomplete when you need to:

✅ Help travellers quickly find destinations while typing. 
✅ Reduce search friction and spelling errors.
✅ Support multi‑language destination discovery.
✅ Power conversational or AI-driven travel flows.

Avoid using it for:

* Batch destination resolution.
* Exact destination ID lookups.
* Back-office data synchronisation.


### Typical flow

1. A traveller starts typing a destination, for example “Amst” in the search box.
2. Your application sends a request to /common/autocomplete with `query="Amst"`.
3. The endpoint returns ranked destination suggestions including “Amsterdam”.
4. The traveller selects a suggestion.
5. Use the returned destination ID in downstream Demand API endpoints. For example: /accommodations/availability or accommodations/search.


## Create the request body

### Required fields

The request must include:

| Field | Description |
|  --- | --- |
| `query` | Free-text search query. Must contain between 3 and 200 characters. Leading and trailing whitespace is ignored. |
| `country` | ISO 3166-1 alpha-2 country code used as the primary search context for autocomplete ranking. |


### Optional fields

| Field | Description |
|  --- | --- |
| `language` | Language used to localise names in the response. Defaults to `en-gb`. |
| `filters.types` | Restricts results to specific destination types. |


#### Supported destination types

You can filter results using:

* airport
* hotel
* landmark
* city
* district
* region
* country


If `filters` is provided, it should contain at least one filter value. Do not send an empty filters object.

### Example request


```json
{
  "query": "ams",
  "language": "es",
  "country": "nl",
  "filters": {
    "types": ["city"]
  }
}
```

## Understand the response

The response returns ranked suggestions matching the search query.

### Top-level fields:

| Field | Description |
|  --- | --- |
| `request_id` | Unique identifier for request tracking and support. |
| `data` | Array of suggestions. |


### Suggestion fields

Each suggestion contains:

| Field | Description |
|  --- | --- |
| `type` | Destination type (for example, `city`, `hotel`, `airport`). |
| `id` | Destination identifier. |
| `name` | Localised display name (single language) |
| `location` | Geographic context for the suggestion. |


### Location fields

The `location` object may contain:

| Field | Description |
|  --- | --- |
| `city` | City identifier. |
| `city_name` | Localised city name. |
| `coordinates` | Latitude and longitude coordinates. |
| `country` | Country code. |
| `country_name` | Localised country name. |


### Example response


```json
{
  "request_id": "01kt6z680dmdkx76v7fbmtv2sp",
  "data": [
    {
      "id": "-2140479",
      "location": {
        "city": -2140479,
        "city_name": {
          "es": "Ámsterdam"
        },
        "coordinates": {
          "latitude": 52.3729,
          "longitude": 4.893
        },
        "country": "nl",
        "country_name": {
          "es": "Países Bajos"
        }
      },
      "name": {
        "es": "Ámsterdam"
      },
      "type": "city"
    },
    {
      "id": "-2140475",
      "location": {
        "city": -2140475,
        "city_name": {
          "es": "Amstelveen"
        },
        "coordinates": {
          "latitude": 52.3034,
          "longitude": 4.85654
        },
        "country": "nl",
        "country_name": {
          "es": "Países Bajos"
        }
      },
      "name": {
        "es": "Amstelveen"
      },
      "type": "city"
    },
```

## Implementation recommendations

### Search behaviour

For the best user experience:

* Trigger requests after at least 3 characters.
* Apply a debounce of approximately 250–300 ms.
* Cancel in-flight requests when the input changes.
* Cache recent queries client‑side.


### Language handling

* Send a single language per request.
* Ensure the user interface matches the requested language.
* The response returns names in the requested language only.


### Filtering

* Use `filters.types` when your use case is limited to specific destination types.
* Avoid unnecessary filtering when broad destination discovery is required.


### Response handling

You should:

* Treat destination IDs as opaque values.
* Use returned names exactly as provided.
* Handle empty results gracefully.
* Log the `request_id` for troubleshooting and support.


**Typo tolerance**

* The endpoint supports prefix matching and basic typo tolerance.
* Do not rely on perfect spelling.
* Always display relevant suggestions returned by the API.


### Performance

**Caching and performance**

* Cache recent successful queries client-side.
* Cancel in-flight requests when input changes.
* Limit results displayed in the UI.


**Rate limits & throttling**

* Autocomplete can generate high call volume.
* Implement client-side throttling and debounce.
* Apply retry/backoff logic for transient failures.


## AI and conversational search

The autocomplete endpoint is suitable for AI-powered travel experiences because it provides:

* Structured destination identifiers.
* Localised destination names.
* Geographic context.
* Consistent destination resolution before downstream API calls.


For best results:

* Pass the user's preferred language.
* Use complete user queries rather than extracting keywords.
* Resolve destinations through autocomplete before calling search or availability endpoints.


## Common implementation patterns

### Pattern 1 — Global search bar

Best for:

* OTAs
* Metasearch platforms.
* Multi‑vertical experiences.


**Configuration:**

* No `filters.types` restriction.
* Include `country` filter.
* Limit: 5–8 results in UI.


### Pattern 2 — Travel-service specific search

Best for:

* Cars pickup flows.
* Attractions search.
* Accommodation‑only experiences.


**Configuration:**

* Use `filters.types`
* Include `country` filter.
* Display ~5 results


### Pattern 3 — AI / conversational flows

Best for:

* Chatbots.
* Voice assistants.
* AI trip planners.


**Configuration:**

* Always pass `language`.
* Include `country`
* Use full free-text queries.


## Quick reference

| Recommendation | ✅ Do | ❌ DON'T |
|  --- | --- | --- |
| Use autocomplete for real-time search | Trigger requests as the user types (minimum 3 characters). | Wait for full query submission. |
| Debounce requests | Apply a 250–300 ms debounce | Call the endpoint on every keystroke. |
| Filter when relevant | Use `filters.types` when your use case is scoped to specific destination types. | Over-filter unnecessarily. |
| Display returned names | Use the names returned by the API. | Retranslate or modify them. |
| Store queries | Store recent successful searches for a short period. | Cache results indefinitely. |
| Handle empty results | Display a clear empty state or allow travellers to continue refining their search. | Leave users without feedback. |
| Optimise performance | Keep request payloads minimal. | Include unnecessary parameters. |


## Error handling

Handle validation and transient errors appropriately.

Examples include:

* Queries shorter than 3 characters.
* Unsupported destination types in filters.types.
* Temporary service interruptions.


Recommendations:

* Retry only transient failures.
* Do not automatically retry validation errors.
* Log `request_id` values for support investigations.
* Respect API rate limits.


## Best practices

✓ Trim and sanitise query input before sending requests.

✓ Use destination IDs returned by autocomplete in downstream API calls.

✓ Preserve the ranking returned by the API.

✓ Keep search interactions responsive with debounce and request cancellation.

✓ Use filtering only when it improves the traveller experience.

✓ Handle empty search results clearly in the user interface.

✓ Pass the user's preferred language whenever possible.

Curious to know more?
- [/common/autocomplete specifications](/demand/docs/open-api/3.2-beta/demand-api/commonautocomplete/common/autocomplete)
- [General error handling guide](/demand/docs/support/error-handling/about-errors)