Skip to content
/
Autocomplete
Last updated

Using the autocomplete endpoint

Retrieve ranked destination suggestions for real-time search experiences.

Overview

→ Use the /common/autocomplete endpoint 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:

FieldDescription
queryFree-text search query. Must contain between 3 and 200 characters. Leading and trailing whitespace is ignored.
countryISO 3166-1 alpha-2 country code used as the primary search context for autocomplete ranking.

Optional fields

FieldDescription
languageLanguage used to localise names in the response. Defaults to en-gb.
filters.typesRestricts 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

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

Understand the response

The response returns ranked suggestions matching the search query.

Top-level fields:

FieldDescription
request_idUnique identifier for request tracking and support.
dataArray of suggestions.

Suggestion fields

Each suggestion contains:

FieldDescription
typeDestination type (for example, city, hotel, airport).
idDestination identifier.
nameLocalised display name (single language)
locationGeographic context for the suggestion.

Location fields

The location object may contain:

FieldDescription
cityCity identifier.
city_nameLocalised city name.
coordinatesLatitude and longitude coordinates.
countryCountry code.
country_nameLocalised country name.

Example response

{
  "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.

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 searchTrigger requests as the user types (minimum 3 characters).Wait for full query submission.
Debounce requestsApply a 250–300 ms debounceCall the endpoint on every keystroke.
Filter when relevantUse filters.types when your use case is scoped to specific destination types.Over-filter unnecessarily.
Display returned namesUse the names returned by the API.Retranslate or modify them.
Store queriesStore recent successful searches for a short period.Cache results indefinitely.
Handle empty resultsDisplay a clear empty state or allow travellers to continue refining their search.Leave users without feedback.
Optimise performanceKeep 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?
Previous page
Next page