{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-demand/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"Using the autocomplete endpoint","siteUrl":"https://developers.booking.com","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"using-the-autocomplete-endpoint","__idx":0},"children":["Using the autocomplete endpoint"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Retrieve ranked destination suggestions for real-time search experiences."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"overview","__idx":1},"children":["Overview"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["→ Use the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/demand/docs/open-api/3.2-beta/demand-api/commonautocomplete"},"children":["/common/autocomplete endpoint"]}," to help travellers find destinations quickly while typing."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Autocomplete supports:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Prefix matching."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Basic typo tolerance."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Localised destination names."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Destination type filtering."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The endpoint can be used across accommodation, car rental, attractions, and AI-powered travel experiences."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"when-to-use-this-endpoint","__idx":2},"children":["When to use this endpoint"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use autocomplete when you need to:"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["✅ Help travellers quickly find destinations while typing. ",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]}," ","✅ Reduce search friction and spelling errors.",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]}," ","✅ Support multi‑language destination discovery.",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]}," ","✅ Power conversational or AI-driven travel flows.",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Avoid using it for:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Batch destination resolution."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Exact destination ID lookups."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Back-office data synchronisation."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"typical-flow","__idx":3},"children":["Typical flow"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A traveller starts typing a destination, for example “Amst” in the search box."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Your application sends a request to /common/autocomplete with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["query=\"Amst\""]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The endpoint returns ranked destination suggestions including “Amsterdam”."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The traveller selects a suggestion."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use the returned destination ID in downstream Demand API endpoints. For example: /accommodations/availability or accommodations/search."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"create-the-request-body","__idx":4},"children":["Create the request body"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"required-fields","__idx":5},"children":["Required fields"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The request must include:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["query"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Free-text search query. Must contain between 3 and 200 characters. Leading and trailing whitespace is ignored."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["country"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["ISO 3166-1 alpha-2 country code used as the primary search context for autocomplete ranking."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"optional-fields","__idx":6},"children":["Optional fields"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["language"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Language used to localise names in the response. Defaults to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["en-gb"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["filters.types"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Restricts results to specific destination types."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"supported-destination-types","__idx":7},"children":["Supported destination types"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can filter results using:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["airport"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["hotel"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["landmark"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["city"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["district"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["region"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["country"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["filters"]}," is provided, it should contain at least one filter value. Do not send an empty filters object."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"example-request","__idx":8},"children":["Example request"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"query\": \"ams\",\n  \"language\": \"es\",\n  \"country\": \"nl\",\n  \"filters\": {\n    \"types\": [\"city\"]\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"understand-the-response","__idx":9},"children":["Understand the response"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The response returns ranked suggestions matching the search query."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"top-level-fields","__idx":10},"children":["Top-level fields:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["request_id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Unique identifier for request tracking and support."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Array of suggestions."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"suggestion-fields","__idx":11},"children":["Suggestion fields"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each suggestion contains:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Destination type (for example, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["city"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hotel"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["airport"]},")."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Destination identifier."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["name"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Localised display name (single language)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["location"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Geographic context for the suggestion."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"location-fields","__idx":12},"children":["Location fields"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["location"]}," object may contain:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["city"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["City identifier."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["city_name"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Localised city name."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["coordinates"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Latitude and longitude coordinates."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["country"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Country code."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["country_name"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Localised country name."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"example-response","__idx":13},"children":["Example response"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"request_id\": \"01kt6z680dmdkx76v7fbmtv2sp\",\n  \"data\": [\n    {\n      \"id\": \"-2140479\",\n      \"location\": {\n        \"city\": -2140479,\n        \"city_name\": {\n          \"es\": \"Ámsterdam\"\n        },\n        \"coordinates\": {\n          \"latitude\": 52.3729,\n          \"longitude\": 4.893\n        },\n        \"country\": \"nl\",\n        \"country_name\": {\n          \"es\": \"Países Bajos\"\n        }\n      },\n      \"name\": {\n        \"es\": \"Ámsterdam\"\n      },\n      \"type\": \"city\"\n    },\n    {\n      \"id\": \"-2140475\",\n      \"location\": {\n        \"city\": -2140475,\n        \"city_name\": {\n          \"es\": \"Amstelveen\"\n        },\n        \"coordinates\": {\n          \"latitude\": 52.3034,\n          \"longitude\": 4.85654\n        },\n        \"country\": \"nl\",\n        \"country_name\": {\n          \"es\": \"Países Bajos\"\n        }\n      },\n      \"name\": {\n        \"es\": \"Amstelveen\"\n      },\n      \"type\": \"city\"\n    },\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"implementation-recommendations","__idx":14},"children":["Implementation recommendations"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"search-behaviour","__idx":15},"children":["Search behaviour"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For the best user experience:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Trigger requests after at least 3 characters."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Apply a debounce of approximately 250–300 ms."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Cancel in-flight requests when the input changes."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Cache recent queries client‑side."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"language-handling","__idx":16},"children":["Language handling"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Send a single language per request."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Ensure the user interface matches the requested language."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The response returns names in the requested language only."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"filtering","__idx":17},"children":["Filtering"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["filters.types"]}," when your use case is limited to specific destination types."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Avoid unnecessary filtering when broad destination discovery is required."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"response-handling","__idx":18},"children":["Response handling"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You should:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Treat destination IDs as opaque values."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use returned names exactly as provided."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Handle empty results gracefully."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Log the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["request_id"]}," for troubleshooting and support."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Typo tolerance"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The endpoint supports prefix matching and basic typo tolerance."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Do not rely on perfect spelling."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Always display relevant suggestions returned by the API."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"performance","__idx":19},"children":["Performance"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Caching and performance"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Cache recent successful queries client-side."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Cancel in-flight requests when input changes."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Limit results displayed in the UI."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Rate limits & throttling"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Autocomplete can generate high call volume."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Implement client-side throttling and debounce."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Apply retry/backoff logic for transient failures."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"ai-and-conversational-search","__idx":20},"children":["AI and conversational search"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The autocomplete endpoint is suitable for AI-powered travel experiences because it provides:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Structured destination identifiers."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Localised destination names."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Geographic context."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Consistent destination resolution before downstream API calls."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For best results:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Pass the user's preferred language."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use complete user queries rather than extracting keywords."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Resolve destinations through autocomplete before calling search or availability endpoints."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"common-implementation-patterns","__idx":21},"children":["Common implementation patterns"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"pattern-1--global-search-bar","__idx":22},"children":["Pattern 1 — Global search bar"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Best for:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["OTAs"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Metasearch platforms."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Multi‑vertical experiences."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Configuration:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["No ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["filters.types"]}," restriction."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Include ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["country"]}," filter."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Limit: 5–8 results in UI."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"pattern-2--travel-service-specific-search","__idx":23},"children":["Pattern 2 — Travel-service specific search"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Best for:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Cars pickup flows."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Attractions search."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Accommodation‑only experiences."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Configuration:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["filters.types"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Include ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["country"]}," filter."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Display ~5 results"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"pattern-3--ai--conversational-flows","__idx":24},"children":["Pattern 3 — AI / conversational flows"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Best for:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Chatbots."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Voice assistants."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["AI trip planners."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Configuration:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Always pass ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["language"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Include ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["country"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use full free-text queries."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"quick-reference","__idx":25},"children":["Quick reference"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Recommendation"},"children":["Recommendation"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"✅ Do"},"children":["✅ Do"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"❌ DON'T"},"children":["❌ DON'T"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Use autocomplete for real-time search"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Trigger requests as the user types (minimum 3 characters)."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Wait for full query submission."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Debounce requests"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Apply a 250–300 ms debounce"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Call the endpoint on every keystroke."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Filter when relevant"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["filters.types"]}," when your use case is scoped to specific destination types."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Over-filter unnecessarily."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Display returned names"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Use the names returned by the API."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Retranslate or modify them."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Store queries"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Store recent successful searches for a short period."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Cache results indefinitely."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Handle empty results"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Display a clear empty state or allow travellers to continue refining their search."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Leave users without feedback."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Optimise performance"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Keep request payloads minimal."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Include unnecessary parameters."]}]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"error-handling","__idx":26},"children":["Error handling"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Handle validation and transient errors appropriately."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Examples include:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Queries shorter than 3 characters."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Unsupported destination types in filters.types."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Temporary service interruptions."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Recommendations:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Retry only transient failures."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Do not automatically retry validation errors."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Log ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["request_id"]}," values for support investigations."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Respect API rate limits."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"best-practices","__idx":27},"children":["Best practices"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["✓ Trim and sanitise query input before sending requests."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["✓ Use destination IDs returned by autocomplete in downstream API calls."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["✓ Preserve the ranking returned by the API."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["✓ Keep search interactions responsive with debounce and request cancellation."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["✓ Use filtering only when it improves the traveller experience."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["✓ Handle empty search results clearly in the user interface."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["✓ Pass the user's preferred language whenever possible."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Curious to know more?"},"children":[{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/demand/docs/open-api/3.2-beta/demand-api/commonautocomplete/common/autocomplete"},"children":["/common/autocomplete specifications"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/demand/docs/support/error-handling/about-errors"},"children":["General error handling guide"]}]}]}]}]},"headings":[{"value":"Using the autocomplete endpoint","id":"using-the-autocomplete-endpoint","depth":1},{"value":"Overview","id":"overview","depth":2},{"value":"When to use this endpoint","id":"when-to-use-this-endpoint","depth":3},{"value":"Typical flow","id":"typical-flow","depth":3},{"value":"Create the request body","id":"create-the-request-body","depth":2},{"value":"Required fields","id":"required-fields","depth":3},{"value":"Optional fields","id":"optional-fields","depth":3},{"value":"Supported destination types","id":"supported-destination-types","depth":4},{"value":"Example request","id":"example-request","depth":3},{"value":"Understand the response","id":"understand-the-response","depth":2},{"value":"Top-level fields:","id":"top-level-fields","depth":3},{"value":"Suggestion fields","id":"suggestion-fields","depth":3},{"value":"Location fields","id":"location-fields","depth":3},{"value":"Example response","id":"example-response","depth":3},{"value":"Implementation recommendations","id":"implementation-recommendations","depth":2},{"value":"Search behaviour","id":"search-behaviour","depth":3},{"value":"Language handling","id":"language-handling","depth":3},{"value":"Filtering","id":"filtering","depth":3},{"value":"Response handling","id":"response-handling","depth":3},{"value":"Performance","id":"performance","depth":3},{"value":"AI and conversational search","id":"ai-and-conversational-search","depth":2},{"value":"Common implementation patterns","id":"common-implementation-patterns","depth":2},{"value":"Pattern 1 — Global search bar","id":"pattern-1--global-search-bar","depth":3},{"value":"Pattern 2 — Travel-service specific search","id":"pattern-2--travel-service-specific-search","depth":3},{"value":"Pattern 3 — AI / conversational flows","id":"pattern-3--ai--conversational-flows","depth":3},{"value":"Quick reference","id":"quick-reference","depth":2},{"value":"Error handling","id":"error-handling","depth":2},{"value":"Best practices","id":"best-practices","depth":2}],"frontmatter":{"title":"Retrieve suggestions","description":"Learn how to use the /common/autocomplete endpoint to retrieve ranked destination suggestions for real-time search experiences across accommodation, car rental and attractions journeys.","tags":["demand-api","autocomplete","destinations","search","suggestions"],"api":["/common/autocomplete"],"keywords":["autocomplete API","destination search","destination suggestions","travel search","destination discovery"],"x-redocly":{"seo":{"title":"Retrieve destination suggestions with the Booking.com Demand API","description":"Learn how to use the /common/autocomplete endpoint to power fast, real-time destination search experiences with ranked suggestions and location context."},"audience":["developer","partners","business"],"apiVersion":"Beta"},"seo":{"title":"Using the autocomplete endpoint"}},"lastModified":"2026-06-03T15:05:41.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/demand/docs/development-guide/common-autocomplete","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}