Related Searches API

Updated

The Related Searches API returns terms that are related to a supplied search phrase.

Endpoint

  • Method: GET
  • Endpoint pattern: https://app.searchstax.com/api/v1/<app_id>/related-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: Do not prefix this key with Token for this endpoint family.

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 related-search terms. Both dash and underscore language-code variants are accepted and normalized automatically.
search Yes query string Base search phrase used to retrieve related searches. Missing or empty values return an application-level validation error.

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 "search=site search" \
  "https://app.searchstax.com/api/v1/<app_id>/related-search/"

Response Example

This example shows a successful related-search response with multiple related phrases: 

{
  "responseHeader": {
    "zkConnected": true,
    "status": 0,
    "QTime": 0
  },
  "response": {
    "numFound": 3,
    "start": 0,
    "numFoundExact": true,
    "docs": [
      {
        "search_term": "account access",
        "related_search": "reset password",
        "related_score": 1
      },
      {
        "search_term": "account access",
        "related_search": "unlock account",
        "related_score": 1
      },
      {
        "search_term": "account access",
        "related_search": "update sign-in settings",
        "related_score": 1
      }
    ]
  }
}

The response uses a Solr-style envelope. Each row in docs maps the submitted search phrase to one related-search suggestion.

HTTP Status Codes and Error Handling

HTTP Code When It Happens Typical Response Body What to Do
200 Request succeeds. Some app-level validation failures also return 200 Search response envelope or {"success":false,...} payload Inspect response body for endpoint-level errors
403 Wrong auth format (for example Token prefix) {"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

Note: Missing or short search can return HTTP 200 with an application-level error payload instead of a non-2xx code.

Pagination

This endpoint has no explicit pagination request controls. Responses can include numFound and start, but paging is not a documented contract.

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