Auto-Suggest API

Updated

The Auto-Suggest API returns prefix-based suggestions for user input.

Endpoint

  • Method: GET
  • Endpoint suffix: /emsuggest

Note: This endpoint uses /emsuggest without a /solr/ segment in the base URL.

Find this endpoint in Site Search > App Settings > All APIs > Search & Indexing.

Search and Indexing endpoint panel in Site Search app settings.

Authentication

Use token-style authorization for this endpoint. 

Authorization: Token <read-only-token>

Request Parameters

Name Required Type Description
Authorization Yes header Use Authorization: Token <read-only-token>.
q Yes query string User-entered search prefix used to fetch suggest candidates.
language No query string Optional language code used to scope suggestion results. Both dash and underscore language-code variants are accepted and normalized automatically.

Note: Both dash and underscore language-code variants are accepted and normalized automatically, so use the language code your integration sends.

Request Examples 

curl -sS --get \
  -H "Authorization: Token <read-only-token>" \
  --data-urlencode "q=sea" \
  --data-urlencode "language=en" \
  "https://<search-host>/emsuggest"

Response Notes

Successful responses include metadata and suggest payload sections. When q is long enough, suggestion values appear under the suggest object.

Response Example

This example shows the typical suggest structure with multiple candidates and metadata fields: 

{
  "responseHeader": {
    "zkConnected": true,
    "status": 0,
    "QTime": 0
  },
  "suggest": {
    "studio_suggestor_en": {
      "invoice": {
        "suggestions": [
          {
            "term": "invoice template",
            "weight": 150,
            "payload": ""
          },
          {
            "term": "invoice status",
            "weight": 100,
            "payload": ""
          },
          {
            "term": "invoice history",
            "weight": 95,
            "payload": ""
          }
        ],
        "numFound": 3
      }
    }
  },
  "metadata": {
    "code": "en",
    "count": 3,
    "dictionary": [
      "studio_suggestor_en",
      "studio_suggestor_fuzzy_en"
    ],
    "enabled": true,
    "minPrefixChars": 2
  }
}

suggest contains the returned candidates keyed by the submitted prefix, and metadata shows language and dictionary configuration details that can help explain why suggestions do or do not appear.

HTTP Status Codes and Error Handling

HTTP Code When It Happens Typical Response Body What to Do
200 Success and metadata responses Suggest and metadata payload Process suggestions when present
401 Missing or invalid token auth {"message":"Unauthorized"} Use valid token header
414 Oversized request URL Request-line too-large response Reduce query size
429 Shared app-level rate and plan limit condition Too-many-requests response Retry with backoff

Pagination

Not applicable for suggest responses. The endpoint returns candidates for a prefix query, not paged result sets.

Rate Limits and Backoff

  • Shared app-level request guidance: 20+ requests/second.
  • Shared plan-limit behavior can return 429.
  • Retry-After is not guaranteed. Use client-side retry delays.

Shared API Foundations

Use these shared references for authentication, request and response structure, and pagination behavior used across Site Search APIs:

Articles in this section