Search API


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

The Search Endpoint (/emselect) for your Site Search 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

This returns the search results as configured by your Site Search 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",
      "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 Site 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.
  5. facet_counts.facet_fields contains dynamically generated Facet name as counts. The Facets returned are configured from the Site 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.
  6. highlighting gives the highlighted content if Search highlighting is selected in the Site Search 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*
  

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":{..}
}

  

Personalisation / Search using different models

Site Search 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 Site Search 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