Share via


Configure your custom autosuggest experience

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.

Custom Autosuggest returns a list of suggested search query strings that are relevant to your search experience. The suggested query strings are based on a partial query string that the user provides in the search box. The list will contain a maximum of 10 suggestions.

You specify whether to return only custom suggestions or to also include Bing suggestions. If you include Bing suggestions, custom suggestions appear before the Bing suggestions. If you provide enough relevant suggestions, it's possible that the returned list of suggestions will not include Bing suggestions. Bing suggestions are always in the context of your Custom Search instance.

To configure search query suggestions for your instance, click the Autosuggest tab.

Note

To use this feature, you must subscribe to Custom Search at the appropriate level (see pricing).

It can take up to 24 hours for suggestions to be reflected in the serving endpoint (API or hosted UI).

Enable Bing suggestions

To enable Bing suggestions, toggle the Automatic Bing suggestions slider to the on position. The slider becomes blue.

Add your own suggestions

To add your own query string suggestions, add them to the list under User-defined suggestions. After adding a suggestion in the list, press the enter key or click the + icon. You can specify the suggestion in any language. You can add a maximum of 5,000 query string suggestions.

Upload suggestions

As an option, you can upload a list of suggestions from a file. The file must contain one search query string per line. To upload the file, click the upload icon and select the file to upload. The service extracts the suggestions from the file and adds them to the list.

Remove suggestions

To remove a query string suggestion, click the remove icon next to the suggestion you want to remove.

Block suggestions

If you include Bing suggestions, you can add a list of search query strings you don't want Bing to return. To add blocked query strings, click Show blocked suggestions. Add the query string to the list and press the enter key or click the + icon. You can add a maximum of 50 blocked query strings.

Publish or revert

Changes you make to a Custom Search instance are made in the Configuration tab so you can validate your changes. When you're done making changes and are ready to publish, click Publish. Changes are not reflected against your production endpoints until you publish.

Before publishing, if you decide that you don't want to keep the changes you've made, click Revert. When you revert your changes, the live state configuration is unchanged and the Configuration tab is reverted to match the live state.

Note

It may take up to 24 hours for Custom Autosuggest configuration changes to take effect.

Enabling Autosuggest in Hosted UI

To enable query string suggestions for your hosted UI, click Hosted UI. Scroll down to the Additional Configuration section. Under Web search, select On for Enable autosuggest. To enable Autosuggest, you must select a layout that includes a search box.

Calling the Autosuggest API

To get suggested query strings using the Bing Custom Search API, send a GET request to the following endpoint.

GET https://api.cognitive.microsoft.com/bingcustomsearch/v7.0/Suggestions 

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

        {  
            "displayText" : "sailing lessons seattle",  
            "query" : "sailing lessons seattle",  
            "searchKind" : "CustomSearch"  
        },  

Each suggestion includes a displayText and query field. The displayText field contains the suggested query string that you use to populate your search box's dropdown list.

If the user selects a suggested query string from the dropdown list, use the query string in the query field when calling the Bing Custom Search API.

Next steps