All Products
Search
Document Center

OpenSearch:Drop-down suggestions

Last Updated:Oct 19, 2026

Drop-down suggestions are a basic feature of search services. While a user types a query, the feature intelligently recommends candidate queries to reduce typing and help the user quickly find the desired content. In addition to common capabilities such as Chinese prefix matching, full pinyin queries, and abbreviated pinyin queries based on pinyin initials, OpenSearch drop-down suggestions intelligently identify queries based on the content of your documents. With simple configurations in the console, you can have your own customized drop-down suggestions. The console also provides the blacklist and recommended entry features, which allow you to further control the results of drop-down suggestions for more flexible customization. For more information about how to use drop-down suggestions, see Product usage documentation.

URL

/v3/openapi/apps/{appName}/suggest/{suggestName}/search
  • {appName} specifies the name of your application.

  • {suggestName} specifies the name of your drop-down suggestion model.

  • Request header parameters and encoding are omitted from the preceding URL.

  • The host address used to access the application is omitted from the preceding URL.

Supported format

JSON

HTTP request method

GET

Query parameters

Parameter

Type

Required

Valid values

Default value

Description

query

String

Yes

The search keyword. If the keyword contains Chinese characters, it must be URL-encoded.

hit

int

No

[1-10]

10

The number of drop-down suggestions to return.

user_id

String

No

Identifies the end user who initiates the current drop-down suggestion request. The value of user_id must be URL-encoded. We recommend that you keep this value consistent with the user_id parameter in search requests of the application. For more information, see Search processing.

re_search

String

No

Completion-based retrieval for homophones and typos is enabled by default. You can set re_search="disable" to disable this feature.

Note: The query parameter for drop-down suggestions is different from the query parameter of the search API. The query parameter for drop-down suggestions is the raw text that the user enters in the search box and does not require an index field name. You can directly specify query=mp3, where mp3 is the query entered by the user.

Response parameters

Parameter

Type

Description

request_id

string

The record ID of the query. It is mainly used for troubleshooting.

searchtime

float

The time taken by the engine to process the query. Unit: seconds.

suggestions

array

The drop-down suggestion results. Each value in the array represents one result.

errors

array

The error details. message indicates the error message. For the meanings of error codes in code, see Error codes.

Examples

Request (request header parameters and encoding are omitted):

http://$host/v3/openapi/apps/app_demo/suggest/suggest_demo/search?hit=10&query=dres&user_id=xxx

Successful response:

{
    "request_id": "150116615820104116121674",
    "searchtime": 0.002654,
    "suggestions": [
        {
            "suggestion": "dress"
        },
        {
            "suggestion": "dress spring collection"
        },
        {
            "suggestion": "dress vintage style"
        }
    ]
}

Error response:

{
    "request_id": "150116635320104116122572",
    "searchtime": 0.037484,
    "suggestions": [],
    "errors": [
        {
            "code": 2551,
            "message": "suggester not found"
        }
    ]
}