Related Searches API

The SearchStax Site Search solution provides an API that retrieves the Related Searches defined for a specific search phrase in the Search App.

Related Searches allows users to manually define Search terms that are related, and augments them from search terms learned using Artificial Intelligence using Analytics data. For the AI augmented related searches, Analytics should be connected with your Search page and there should be enough searches with clicks available.

This page describes how to retrieve a Json document of related-search strings for display on your search page.

The API can be accessed through any tool that assembles HTTP requests and dispatch them to a server. Among these would be the Python coreapi package, the Postman tool, and cURL. For Windows, use PowerShell 7.

Symbols enclosed in carets (< and >) such as <username> are metavariables. Substitute your local values when you encounter them in the examples.

Related Search

This method returns a list of Related Searches from a Search App.

GET <related-searches-URL>?search=<search-phrase>

where <related-searches-URL> is an endpoint from the Discovery API Tab of the App Settings screen, and <search-phrase> is the base query that has related searches defined on the Related Searches screen.

This method uses SearchAPIKey authorization. The Search API key is displayed on the Discovery API Tab. It must be passed in the header of the request.

When invoked from Linux (Bash script):

URL="https://app.searchstax.com/api/v1/nn/related-search/"
APIKEY="456cwe54sasb8e5lu5y6k48j55u95338slas"
KEYWORD="sitecore"

SEARCHES=$(curl -H "Authorization: $APIKEY" "$URL?search=$KEYWORD")

When invoked from Windows Powershell:

# Removes TLS obstacles from connection. Otherwise connections fail. 
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls -bor [Net.SecurityProtocolType]::Tls11 -bor [Net.SecurityProtocolType]::Tls12

$URL = "https://app.searchstax.com/api/v1/nn/related-search/"
$APIKEY = "81c09977fedb7e89310c87df81d7bc787301155e"
$KEYWORD = "Sitecore"

# Set up HTTP header for authorization token
$headers = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"
$headers.Add("Authorization", $APIKEY)

$RESPONSE = Invoke-RestMethod -Method Get -ContentType 'application/json' -Headers $headers `
              -uri $($URL+"?search=$KEYWORD") 
$RESPONSE = $RESPONSE | ConvertTo-Json -Depth 3

Write-Host $RESPONSE

The response is a JSON document containing a list of related searches.

{
  "responseHeader": {
    "zkConnected": true,
    "status": 0,
    "QTime": 0
  },
  "response": {
    "numFound": 5,
    "start": 0,
    "numFoundExact": true,
    "docs": [
      {
        "search_term": "sitecore",
        "related_search": "sitecore 10",
        "related_score": 1
      },
      {
        "search_term": "sitecore",
        "related_search": "sitecore plugin",
        "related_score": 1
      },
      {
        "search_term": "sitecore",
        "related_search": "sitecore replace azure",
        "related_score": 1
      },
      {
        "search_term": "sitecore",
        "related_search": "site search for sitecore",
        "related_score": 1
      },
      {
        "search_term": "sitecore",
        "related_search": "managed solr for sitecore",
        "related_score": 1
      }
    ]
  }
}

The fields of each related search have the following meanings:

  • search_term: This is the search string that keys to the Related Searches.
  • related_search: Each entry contains the string of a single Related Search.
  • related_score: A measure of similarity to the search_term. The range of values is 0 to 1. Higher values are more similar.

Questions?

Do not hesitate to contact the SearchStax Support Desk.