Integrate Drop-Down Search Suggestions via OpenSearch API - OpenSearch

Drop-down suggestions complete a user's search query as they type, showing up to 10 matching suggestions before the full query is entered. OpenSearch supports Chinese character prefixes, full pinyin spelling, and abbreviated pinyin (first-letter) input to power intelligent autocomplete.

To configure a drop-down suggestion model, set up blocklists, and add promoted queries, see Drop-down suggestions.

Query drop-down suggestions

Endpoint

GET /v3/openapi/apps/{appName}/suggest/{suggestName}/search

Path parameter	Description
`appName`	Name of your OpenSearch application
`suggestName`	Name of your drop-down suggestion model

The endpoint omits the host, request headers, and encoding details. For the full connection format, see Initiate search requests.

Supported format: JSON

Request parameters

Parameter	Type	Required	Valid values	Default	Description
`query`	STRING	Yes	—	—	The text entered in the search box. URL-encode the value if it contains Chinese characters.
`hit`	INT	No	1–10	10	Number of suggestions to return.
`user_id`	STRING	No	—	—	ID of the user sending the request. URL-encode the value. We recommend that you use the same `user_id` as in your data search requests.
`re_search`	STRING	No	`disable`	Enabled	Specifies whether to retrieve documents by replacing terms in search queries with homophones. Set to `disable` to turn off this feature.

Note: The query parameter here differs from query in data search requests. In drop-down suggestion requests, query is the raw text a user types in the search box — it does not need to be an index field name.

Response parameters

Parameter	Type	Description
`request_id`	STRING	The request ID, used for troubleshooting.
`searchtime`	FLOAT	Time taken by the engine to complete the query, in seconds.
`suggestions`	ARRAY	The matched suggestions. Each element is an object containing one suggestion string.
`errors`	ARRAY	Error details. The `message` field contains the error description. See Error codes.

Examples

Request

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

app_demo — the application name
suggest_demo — the suggestion model name
hit=10 — return up to 10 suggestions
query=One-piece dress — the text typed in the search box

Success response

{
    "request_id": "150116615820104116121674",
    "searchtime": 0.002654,
    "suggestions": [
        {"suggestion": "One-piece dress"},
        {"suggestion": "One-piece dress for Spring"},
        {"suggestion": "One-piece dress for art enthusiasts"}
    ]
}

Error response

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

For a full list of error codes, see Error codes.

What's next

Drop-down suggestions — configure suggestion models, blocklists, and promoted queries in the console
Initiate search requests — use the same user_id across suggestion and search requests