Suggesting query terms
Warning
On October 30, 2020, the Bing Search APIs moved from Azure AI services to Bing Search Services. This documentation is provided for reference only. For updated documentation, see the Bing search API documentation. For instructions on creating new Azure resources for Bing search, see Create a Bing Search resource through the Azure Marketplace.
Typically, you'd call the Bing Autosuggest API each time a user types a new character in your application's 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.
Example request
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"
}, ...
Using suggested query terms
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 example shows a drop-down search box with suggested query terms from the Bing Autosuggest API.
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.