Search API

The SearchStax Studio’s Search API lets you request basic and advanced search results from you Search App.

The Search Endpoint (/emselect) for your Search App is available within your Apps Management page as shown below:

Your Search endpoints are protected using Token Authentication or Basic Authentication in certain circumstances. When using the endpoints for search, it is recommended to use the Read Only Credentials.

This is a cURL example illustrating Token Authentication with a simple query:

curl -H "Authorization: Token e3y545ere45gff654nnhf651ng5d15g1g6" --request GET 'https://ss123456-cvrfzabx-us-east-1-aws.searchstax.com/12345/testexample-12/emselect?q=*:*'

This is a cURL example illustrating Basic Authentication with a simple query:

curl -u 'app40-api:paSSw0Rd' --request GET 'https://ss123456-cvrfzabx-us-east-1-aws.searchstax.com/solr/<search-app-name>/emselect?q=*:*'

Contents of this page:

Authentication
Basic Search
Language
Pagination
Sorting
Faceting
Spelling Suggestions
Advance Search API Options
Personalisation / Search using different models

Authentication

Token Authentication

For apps using Token Authentication, the Access Tokens are cryptographically secure 20 bytes tokens that do not expire, but can be rotated.

Token Management

You can manage your tokens and rotate them if needed.

Click on the Create Token button – this will create an enabled Read Only token by default.
If you need to change an access right for a token, select the appropriate access right in the dropdown.
Leave the old token enabled until ready to rotate.
Once ready, disable the token by clicking on the toggle (turning it to red) or delete the token.

*If you are rotating your token, the new token will need to be deployed out through your dev process as well

Basic Authentication

For apps using Basic Authentication, the Search APIs are protected using a sets of an auto-generated User-IDs and passwords set by the user.

You may change the passwords (but not the user IDs) on this screen. Click the Save button when finished.

Basic Search

For performing basic search, simply pass the query as the 'q' parameter as shown below:

https://ss123456-cvrfzabx-us-east-1-aws.searchstax.com/solr/ss123456-SearchStudioCorpSite/emselect?q=sitecore&language=en

This returns the search results as configured by your Search App for your default model as shown below:

{
  "responseHeader": {
    "zkConnected": true,
    "status": 0,
    "QTime": 2,
    "params": {
      "spellcheck.dictionary": "studio_spellcheck_dictionary",
      "hl": "true",
      "echoParams": "all",
      "fl": "content_type,title,paths,url,content,date,id,author_name,[elevated]",
      "f.author_name.facet.sort": "index asc",
      "f.meta_keywords_facet.facet.mincount": "1",
      "f.content_type.facet.mincount": "1",
      "defType": "edismax",
      "qf": "title^77.0 meta_description^35.0 content^6.0 meta_keywords url",
      "f.content_type.facet.sort": "count",
      "model": "CorpSiteModel",
      "f.content_type.facet.limit": "5",
      "wt": "json",
      "facet.field": [
        "content_type",
        "author_name",
        "meta_keywords_facet"
      ],
      "f.author_name.facet.mincount": "1",
      "rows": "2",
      "spellcheck.extendedResults": "true",
      "hl.snippets": "4",
      "q": "sitecore",
      "language":"en",
      "spellcheck": "on",
      "spellcheck.accuracy": "0.9",
      "spellcheck.count": "1",
      "f.author_name.facet.limit": "5",
      "f.meta_keywords_facet.facet.sort": "count",
      "facet": "true",
      "uniqueId": "url",
      "f.meta_keywords_facet.facet.limit": "5"
    }
  },
  "response": {
    "numFound": 138,
    "start": 0,
    "docs": [
      {
        "content_type": [
          "Webpage"
        ],
        "url": "https://site-dev.searchstax.com/solutions/sitecore-solr/",
        "title": [
          "Sitecore Solr Search: Get fast and relevant search results | SearchStax"
        ],
        "paths": [
          "solutions / sitecore-solr"
        ],
        "content": [
          "Create on-demand or scheduled backups of your deployments. SearchStax provides various disaster recovery options to meet your RPO and RTO objectives.. 100s of Sitecore deployments already use SearchStax. Plus SearchStax is the service that powers Solr for Sitecore Managed Cloud.."
        ],
        "[elevated]": true
      },
      {
        "content_type": [
          "Blog"
        ],
        "url": "https://site-dev.searchstax.com/blog/searchstax-solr-plugin-for-sitecore-10/",
        "title": [
          "SearchStax Solr Plugin for Sitecore 10 | The Search Experience Blog"
        ],
        "paths": [
          "blog / searchstax-solr-plugin-for-sitecore-10"
        ],
        "content": [
          "We are pleased to announce that we have added Sitecore 10 support for our Sitecore Solr Plugin. The Sitecore Solr Plugin accelerates the process and automates a number of manual tasks involved with connecting a Sitecore installation to a SearchStax Solr instance. Setting up Solr with the Plugin takes just a few minutes and will save you hours of time and effort.."
        ],
        "date": "2020-08-26T00:00:00Z",
        "author_name": "Tom Humbarger",
        "[elevated]": true
      }
    ]
  },
  "facet_counts": {
    "facet_queries": {},
    "facet_fields": {
      "content_type": [
        "documentation", 67,
        "blog", 44,
        "webpage", 15,
        "case", 9,
        "study", 9
      ],
      "author_name": [
        "Bruce Clayton", 5,
        "Christophe Cremault", 5,
        "Dipsy Kapoor", 2,
        "Eric Melz", 1,
        "Karan Jeet Singh", 4
      ]
    },
    "facet_ranges": {},
    "facet_intervals": {},
    "facet_heatmaps": {}
  },
  "highlighting": {
    "https://site-dev.searchstax.com/solutions/sitecore-solr/": {
      "meta_description": [
        "Optimize your <em>Sitecore</em> Solr search. Get the latest version of Solr and custom plugin support for your <em>Sitecore</em> deployment with SearchStax"
      ],
      "title": [
        "<em>Sitecore</em> Solr Search: Get fast and relevant search results | SearchStax"
      ],
      "content": [
        ".. 100s of <em>Sitecore</em> deployments already use SearchStax. Plus SearchStax is the service that powers Solr for <em>Sitecore</em> Managed Cloud.. Development nodes"
      ]
    },
    "https://site-dev.searchstax.com/blog/searchstax-solr-plugin-for-sitecore-10/": {
      "meta_description": [
        "We have added <em>Sitecore</em> 10 support for our <em>Sitecore</em> Solr Plugin. The Plugin automates connecting <em>Sitecore</em> to a SearchStax Solr instance."
      ],
      "title": [
        "SearchStax Solr Plugin for <em>Sitecore</em> 10 | The Search Experience Blog"
      ],
      "content": [
        "We are pleased to announce that we have added <em>Sitecore</em> 10 support for our <em>Sitecore</em> Solr Plugin. The <em>Sitecore</em> Solr Plugin accelerates the process",
        " and automates a number of manual tasks involved with connecting a <em>Sitecore</em> installation to a SearchStax Solr instance. Setting up Solr with the Plugin takes just",
        " a few minutes and will save you hours of time and effort.. As a <em>Sitecore</em> Technology Alliance Program partner, we know how important it is to stay in step",
        " with and support the new <em>Sitecore</em> 10 release. We continue to empower and support the <em>Sitecore</em> community by making Solr easier to install and manage on the <em>Sitecore</em>"
      ]
    }
  },
  "spellcheck": {
    "suggestions": [],
    "correctlySpelled": true
  },
  "metadata": {
    "facets": [
      {
        "name": "content_type",
        "label": "Content Type"
      },
      {
        "name": "author_name",
        "label": "Author"
      },
      {
        "name": "meta_keywords_facet",
        "label": "Keywords"
      }
    ]
  }
}

responseHeader.params gives details of all parameters passed to the search request, including responseHeader.params.rows which gives the number of documents returned in the response
response.numFound gives the total number of documents that matched the query
response.start gives zero starting index of the search results
response.docs contains the documents that matched the query. It includes all fields that were selected during Result Configuration inside the Search App. It also always include the field that is marked as the “uniqueKey” in the schema, which is most cases is either "id" or "url"; and [elevated] which marks whether the result document is a “promoted/sponsored” item or a regular search result.
facet_counts.facet_fields contains dynamically generated Facet name as counts. The Facets returned are configured from the Search App. For each facet, the response contains the value of the facet, and a count of the number of documents that have that facet value.
highlighting gives the highlighted content if Search highlighting is selected in the Search App. It is organized by the unique id of the document
spellcheck contains spelling suggestions

SearchStax uses the eDisMax query parser and supports the standard Solr query Syntax. Some query examples are:

Get documents matching “sitecore plugin”, not necessarily together or containing both words – https://ss123456-cvrfzabx-us-east-1-aws.searchstax.com/solr/ss123456-SearchStudioCorpSite/emselect?q=sitecore plugin
Get documents matching “sitecore plugin” as a phrase (Phrase Query) – https://ss123456-cvrfzabx-us-east-1-aws.searchstax.com/solr/ss123456-SearchStudioCorpSite/emselect?q="sitecore plugin“
Get documents where “sitecore” and “plugin” are within 20 words of each other (Proximity Query) – https://ss123456-cvrfzabx-us-east-1-aws.searchstax.com/solr/ss123456-SearchStudioCorpSite/emselect?q="sitecore plugin“~20
Get documents containing words starting with site (Wildcard Query) – https://ss123456-cvrfzabx-us-east-1-aws.searchstax.com/solr/ss123456-SearchStudioCorpSite/emselect?q=site*

Language

If your Search App is configured for multiple languages, use the language parameter, providing the 2-digit code for the language. If omitted, this defaults to the default language. Example for Spanish (es):

https://ss123456-cvrfzabx-us-east-1-aws.searchstax.com/solr/ss123456-SearchStudioCorpSite/emselect?q=sitecore&language=es

If your dataset contains different documents for different languages in the same app, you might have to also add filter criteria to filter the results to only that language. You can do that as shown below in the example, or by using “Global Filters” in the app settings for the language. Example:

https://ss123456-cvrfzabx-us-east-1-aws.searchstax.com/solr/ss123456-SearchStudioCorpSite/emselect?q=sitecore&language=es&fq=language_s:"es_ES"

Pagination

start and rows parameters control the pagination. start is zero based index of the search results and rows is the number of results to return per page. Example:

https://ss123456-cvrfzabx-us-east-1-aws.searchstax.com/solr/ss123456-SearchStudioCorpSite/emselect?q=sitecore&start=4&rows=4

gives the second page of search results, if you are getting 4 results per page. The format of the result is the same as Basic Search.

Sorting

You can use the sort parameter to specify the field by which you would like to sort the search results. If the parameter is omitted, by default, the search results are sorted by relevance. Below are some examples showing sorting

Sort by Date Descending

https://ss123456-cvrfzabx-us-east-1-aws.searchstax.com/solr/ss123456-SearchStudioCorpSite/emselect?q=sitecore&sort=date%20desc

Sort by Date Ascending

https://ss123456-cvrfzabx-us-east-1-aws.searchstax.com/solr/ss123456-SearchStudioCorpSite/emselect?q=sitecore&sort=date%20asc

Sort by title Ascending

https://ss123456-cvrfzabx-us-east-1-aws.searchstax.com/solr/ss123456-SearchStudioCorpSite/emselect?q=sitecore&sort=title%20asc

Faceting / Facet Selection

In the search results facet_counts.facet_fields contains all the facets. To apply a facet and narrow down the search results, the fq parameter is used.

Add a facet on content_type, selecting Blog

https://ss123456-cvrfzabx-us-east-1-aws.searchstax.com/solr/ss123456-SearchStudioCorpSite/emselect?q=sitecore&fq=content_type:"blog"

Add 2 facets: To add multiple facets, simply pass multiple fq parameters

https://ss123456-cvrfzabx-us-east-1-aws.searchstax.com/solr/ss123456-SearchStudioCorpSite/emselect?q=sitecore&fq=content_type:"blog"&fq=author_name:"John Adams"

https://ss123456-cvrfzabx-us-east-1-aws.searchstax.com/solr/ss123456-SearchStudioCorpSite/emselect?q=sitecore&fq=content_type:"blog"&fq=author_name:"John Adams"

Spelling Suggestions

If a user misspells the search term, and a corresponding correction can be detected, spellcheck.suggestions will contain the spelling suggestions. Example:

https://ss123456-cvrfzabx-us-east-1-aws.searchstax.com/solr/ss123456-SearchStudioCorpSite/emselect?q=sitecole

gives back:

{
  "responseHeader":{..},
  "response":{"numFound":0,"start":0,"docs":[]
  },
  "facet_counts":{},
  "highlighting":{},
  "spellcheck":{
    "suggestions":[
      "sitecole",{
        "numFound":1,
        "startOffset":0,
        "endOffset":8,
        "suggestion":["sitecore"]}],
    "correctlySpelled":false},
  "metadata":{..}
}

There are two methods to apply Spell Check suggestions to a user:

1 .

Only provide a Suggestion: Results are displayed for the user’s original misspelled search input with a “Did you mean [suggested spelling]?” path. With this method, you do not need to add any special parameters to the API.

2 .

Autocorrection: The user’s original misspelled search input is autocorrected and results are displayed for the spell check suggestion returned with a “Search instead for [original search input]?” path. With this method, the parameter `spellcheck.correct` can be used. Example

https://ss123456-cvrfzabx-us-east-1-aws.searchstax.com/solr/ss123456-SearchStudioCorpSite/emselect?q=searchstaz&spellcheck.correct=true

When using the autocorrection method, there are two additional responseHeader.params:

originalQ that contains the original query, searchstaz
autoCorrectedQ that contains searchstax and is an indicator that the user’s query was misspelled and autocorrected to this value.

The spellcheck component is configured to return back 1 spelling suggestion. To retrieve more spelling suggestions, the parameter `spellcheck.count` can be used. Example

https://ss123456-cvrfzabx-us-east-1-aws.searchstax.com/solr/ss123456-SearchStudioCorpSite/emselect?q=sitecole&spellcheck.count=4

If you would like no spelling suggestions offered when there are any documents matching the query, pass spellcheck.maxResultsForSuggest=1

https://ss123456-cvrfzabx-us-east-1-aws.searchstax.com/solr/ss123456-SearchStudioCorpSite/emselect?q=sitecole&spellcheck.count=4&spellcheck.maxResultsForSuggest=1

Advance Search API Options

metadata: emselect endpoint returns additional metadata that can be useful for the User Interface. If you would not like that to be returned, you can pass ‘metadata=false’ to the API. Example:

https://ss123456-cvrfzabx-us-east-1-aws.searchstax.com/solr/ss123456-SearchStudioCorpSite/emselect?q=sitecore&metadata=false

flAdditional: You should select the list of fields to be returned from the Search App. However, if you would like to add additional fields to the results, you can pass them as the flAdditional parameter. Example:

https://ss123456-cvrfzabx-us-east-1-aws.searchstax.com/solr/ss123456-SearchStudioCorpSite/emselect?q=sitecore&flAdditional=geodist(),score

Personalisation / Search using different models

The Studio allows you to configure multiple models. These could be used for an experiment, or to provide personalized search results. To use a particular model, pass the model name as the model parameter. If no model is specified, the search engine uses what is specified as the “default” model in the Studio App.

Example: If you have a model named ‘experimentA’ you can pass it as shown below:

https://ss123456-cvrfzabx-us-east-1-aws.searchstax.com/solr/ss123456-SearchStudioCorpSite/emselect?q=sitecore&model=experimentA

Questions?

Do not hesitate to contact the SearchStax Support Desk.