What is Bing Autosuggest?

If you send queries to any of the Bing Search APIs, you can use the Bing Autosuggest API to improve your search box experience. The Bing Autosuggest API returns a list of suggested queries based on the partial query string the user enters in the search box. Display the suggestions in the search box's drop-down list. The suggested terms are based on suggested queries that other users have searched on and user intent.

Typically, you'd call this API each time the user types a new character in the search box. The completeness of the query string impacts the relevance of the suggested query terms that the API returns. The more complete the query string, the more relevant the list of suggested query terms are. For example, the suggestions that the API may return for s are likely to be less relevant than the queries it returns for sailing dinghies.

Getting suggested search terms

The following example shows a request that returns the suggested query strings for sail. Remember to URL encode the user's partial query term when you set the q query parameter. For example, if the user entered sailing les, set q to sailing+les or sailing%20les.

GET https://api.cognitive.microsoft.com/bing/v7.0/suggestions?q=sail&mkt=en-us HTTP/1.1
Ocp-Apim-Subscription-Key: 123456789ABCDE
X-MSEdge-ClientIP: 999.999.999.999
X-Search-Location: lat:47.60357;long:-122.3295;re:100
X-MSEdge-ClientID: <blobFromPriorResponseGoesHere>
Host: api.cognitive.microsoft.com

The following response contains a list of SearchAction objects that contain the suggested query terms.

    "url" : "https:\/\/www.bing.com\/search?q=sailing+lessons+seattle&FORM=USBAPI",
    "displayText" : "sailing lessons seattle",
    "query" : "sailing lessons seattle",
    "searchKind" : "WebSearch"
}, ...

Each suggestion includes a displayText, query and, url field. The displayText field contains the suggested query that you use to populate your search box's drop-down list. You must display all suggestions that the response includes, and in the given order.

The following shows an example of drop-down search box with suggested query terms.

Autosuggest drop-down search box list

If the user selects a suggested query from the drop-down list, you'd use the query term in the query field to call the Bing Web Search API and display the results yourself. Or, you could use the URL in the url field to send the user to the Bing search results page instead.

Throttling requests

The service and your subscription type determine the number of queries per second (QPS) that you can make. Make sure your application includes the logic to stay within your quota. If the QPS limit is met or exceeded, the request fails and an HTTP 429 status code is returned. The response includes the Retry-After header, which indicates how long you must wait before sending another request.

Denial-of-service versus throttling

The service makes a differentiation between a denial-of-service (DoS) attack and a QPS violation. If the service suspects a DoS attack, the request succeeds (HTTP status code is 200 OK). However, the body of the response is empty.

Next steps

To get started quickly with your first request, see Making Your First Query.

Familiarize yourself with the Bing Autosuggest API v7 reference. The reference contains the list of endpoints, headers, and query parameters that you'd use to request suggested query terms, and the definitions of the response objects.

Learn how to search the web by using the Bing Web Search API.

Be sure to read Bing Use and Display Requirements so you don't break any of the rules about using the search results.