Popular Searches API

Updated

The Popular Searches API returns frequently searched terms for an app.

Endpoint

  • Method: GET
  • Endpoint pattern: https://app.searchstax.com/api/v1/<app_id>/popular-search/

UI Navigation

Find this endpoint and Discovery key in Site Search > App Settings > All APIs > Discovery.

Discovery API tab navigation in Site Search app settings.

Authentication

Use the Discovery API key as the raw header value. 

Authorization: <DISCOVERY_API_KEY>

Note: Using Authorization: Token <key> can return 403 Invalid token for this endpoint.

Request Parameters

Name Required Type Description
Authorization Yes header Use the Discovery API key in the Authorization header. Do not prefix it with Token.
language No query string Optional language code used to scope popular-search terms. Both dash and underscore language-code variants are accepted and normalized automatically.
num_results No query string Optional result-size hint for popular-search rows. Common values are 1 to 20. Larger values can still return HTTP 200 with an empty docs array.
page No query string Optional page selector for result retrieval.

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: <discovery-api-key>" \
  --data-urlencode "language=en" \
  --data-urlencode "num_results=10" \
  "https://app.searchstax.com/api/v1/<app_id>/popular-search/"

Response Example

This example shows a typical popular-search response with multiple top queries and counts: 

{
  "responseHeader": {
    "zkConnected": true,
    "status": 0,
    "QTime": 0
  },
  "response": {
    "numFound": 20,
    "start": 0,
    "docs": [
      {
        "query": "invoice status",
        "count": 112
      },
      {
        "query": "password reset",
        "count": 108
      },
      {
        "query": "account settings",
        "count": 103
      }
    ]
  }
}

docs contains the most frequent queries for the requested scope, and count shows how often each query occurred in the sampled result set.

HTTP Status Codes and Error Handling

HTTP Code When It Happens Typical Response Body What to Do
200 Request succeeds. Some endpoint-level failures also return 200 Search response envelope or {"success":false,"message":"Invalid API Key"} Inspect body for app-level error messages
403 Wrong auth format (for example token-prefixed key) {"detail":"Invalid token"} Use raw Discovery key header
414 Oversized request URL URI-too-large response Reduce query length
429 Shared app-level rate and plan limit condition Too-many-requests response Retry with backoff

Pagination

The endpoint supports the page parameter. It can still return first-page data for multiple page values (response.start can stay 0). Treat pagination support as limited and validate behavior in your app before relying on it.

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