Search API

This page describes how to use SearchStax® SearchStudio “Search API”.

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

This is the Search API screen from Site Search where you can get the Search URL, Suggest URL and Credentials for the Site Search app.

Your Solr endpoints are protected using Basic Authentication. When using the endpoints for search, it is recommended to use the Read-Only API Credentials.

Contents of this page:

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

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

This returns the search results as configured by your SearchStudio Application 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://www.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://www.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://www.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://www.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"
      }
    ]
  }
}
  1. 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
  2. response.numFound gives the total number of documents that matched the query
  3. response.start gives zero starting index of the search results
  4. response.docs contains the documents that matched the query. It includes all fields that were selected during Result Configuration inside the SearchStudio 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.
  5. facet_counts.facet_fields contains dynamically generated Facet name as counts. The Facets returned are configured from the SearchStudio 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.
  6. highlighting gives the highlighted content if Search highlighting is selected in the SearchStudio App. It is organized by the unique id of the document
  7. spellcheck contains spelling suggestions

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

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

Language

If your Studio Application 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://ss849763-cvrfzabx-us-east-1-aws.searchstax.com/solr/ss849763-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://ss849763-cvrfzabx-us-east-1-aws.searchstax.com/solr/ss849763-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://ss849763-cvrfzabx-us-east-1-aws.searchstax.com/solr/ss849763-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://ss849763-cvrfzabx-us-east-1-aws.searchstax.com/solr/ss849763-SearchStudioCorpSite/emselect?q=sitecore&sort=date%20desc
  • Sort by Date Ascending
https://ss849763-cvrfzabx-us-east-1-aws.searchstax.com/solr/ss849763-SearchStudioCorpSite/emselect?q=sitecore&sort=date%20asc
  • Sort by title Ascending
https://ss849763-cvrfzabx-us-east-1-aws.searchstax.com/solr/ss849763-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://ss849763-cvrfzabx-us-east-1-aws.searchstax.com/solr/ss849763-SearchStudioCorpSite/emselect?q=sitecore&fq=content_type:"blog"
  • Add 2 facets: To add multiple facets, simply pass multiple fq parameters
https://ss849763-cvrfzabx-us-east-1-aws.searchstax.com/solr/ss849763-SearchStudioCorpSite/emselect?q=sitecore&fq=content_type:"blog"&fq=author_name:"John Adams"

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

  

Spelling Correction

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

https://ss849763-cvrfzabx-us-east-1-aws.searchstax.com/solr/ss849763-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":{..}
}

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://ss849763-cvrfzabx-us-east-1-aws.searchstax.com/solr/ss849763-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://ss849763-cvrfzabx-us-east-1-aws.searchstax.com/solr/ss849763-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://ss849763-cvrfzabx-us-east-1-aws.searchstax.com/solr/ss849763-SearchStudioCorpSite/emselect?q=sitecore&metadata=false
  • flAdditional: You should select the list of fields to be returned from SearchStudio. However, of you any reason you would like to add additional parameters to the fields selected from SearchStudio, you can pass them as the flAdditional parameter. Example: 
https://ss849763-cvrfzabx-us-east-1-aws.searchstax.com/solr/ss849763-SearchStudioCorpSite/emselect?q=sitecore&flAdditional=geodist(),score

  

Personalisation / Search using different models

SearchStudio 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 SearchStudio Application.

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

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