Search Analytics REST API


This page describes how to add SearchStax® Analytics Events to your search page. SearchStax Analytics API describes how you can use a helper Javascript library to push Analytics events. This document describes how the same events can be pushed using just a REST API.

  

Analytics URL, Key and the REST Endpoint

On the Settings page of your Site Search App, the Analytics API tab contains the base URL for the API and the Analytics Key. Analytics key will be used to identify the SiteSearch App.

The Analytics REST endpoint is <Analytics URL>/api/v2/track/.

Example: https://analytics-us.searchstax.com/api/v2/track/

Different events can be pushed to this endpoint as described in the sections below.









Events

An “event” is a user action on your search page, such as searching for a keyword or clicking on a search result. SearchStax supports the following event messages:

  • _search : This event is used to track Searches and Impressions
  • _searchclick : This event is used to track the search results that were clicked
  • _searchSatisfaction : This event is used to collection qualitative feedback about the search experience

Each type of event has its own set of required properties, which are detailed below. The following are the common properties across all events:

PropertyDescriptionExample
key:
required
string  
This is the unique analytics app key as shown in the “Analytics API” tab of your App within Site Search App Management ‘IeDTTDD1ubJdfPMmu7MMxxVjUMdw6vo52BjPixxqwcQ’
session:
required
string  
The ID of the web session or mobile application session. If omitted, some analytics features cannot be fully reported.‘qqMKt4fxhcud0T5c3UJ5spgug’
_vid:
required
string 
Unique Identifier to identify a visitor‘d7cc372a-2be6-ee1e-26e8-0f903fa36e67’

session can be obtained using the following helper function:

getSession : function(name){
	var name = 'searchcookie';
	var session = document.cookie.match(new RegExp('(^| )' + name + '=([^;]+)'));
	return session[2];
}

   

Track Searches and Impressions

To track searches, create a data object as below, which specifies the event type as _search

var searchObj = {
  "event": "_search",
  "properties": {
    "key": "imDMrs56aTaDJc6jihDejUkDZYj3Gm8riJHlR0V1S58",
    "query": "sitecore",
    "shownHits": 3,
    "totalHits": 12,
    "pageNo": 1,
    "latency": 6,
    "session": "r6ivpxkd3e294kJ299V0tVb1q",
    "impressions": [
      {
        "cDocId": "https://www.searchstax.com/solutions/sitecore-solr/",
        "cDocTitle": "Managed Solr Service for Sitecore | SearchStax",
        "position": 1
      },
      {
        "cDocId": "https://www.searchstax.com/blog/site-search-for-sitecore-video/",
        "cDocTitle": "Site Search for Sitecore - Video | The Search Experience Blog",
        "position": 2
      },
      {
        "cDocId": "https://www.searchstax.com/sitecore-azure-to-solr-migration/",
        "cDocTitle": "Migrate Azure Search to Solr for Sitecore | SearchStax",
        "position": 3
      }
    ],
    "_vid": "d7cc372a-2be6-ee1e-26e8-0f903fa36e67"
  }
}

PropertyDescriptionExample
event:
required
string
Type of user action on the search page.‘_search’
key:
required
string
Unique Analytics API Key‘IeDTTDD1ubJdfPMmu7MMxxVjUMdw6vo52BjPixxqwcQ’
user:
optional
string
A token identifying the webpage user. This datum is stored but is not currently used.‘smith123’
session:
required
string
The ID of the web session or mobile application session. ‘qqMKt4fxhcud0T5c3UJ5spgug’
query:
required
string
The query string from your search page, or q from the response document.‘sitecore plugin’
shownHits:
optional
number
The number of hits shown in the response document.10
totalHits:
optional
number
The number of hits in the index, from the response document.

Note: To track searches that returned no results, set totalHits to 0.
1890
latency:
optional
number
The number of milliseconds to execute a search. You define the semantics. (One possibility is to use Qtime from the response document). Without this value, Analytics will not calculate average latency.150
pageNo:
optional
number
The page number of the displayed results, from the response document.1
impressions:
optional
array
An array of dictionaries, each describing a search result “impression.”
It lets the Analytics App track the documents that were displayed to the user as search results, whether the user clicked on them or not
[
{'cDocId': 'aDocId1', 'cDocTitle': 'aDocTitle1', 'position': 1},
{'cDocId': 'aDocId2', 'cDocTitle': 'aDocTitle2', 'position': 2}, ..
]

where cDocId is the unique ID of the document and cDocTitle is the title that is displayed for the search result.
The position numbers should start with 1
_vid:
required
string
Unique Identifier for the visitor.d7cc372a-2be6-ee1e-26e8-0f903fa36e67

Calling the Analytics REST endpoint (/track API)

To call the REST API and insert the event, the event objects should be encoded to Base64 and passed as the data. For example, for the above request, you can use online base64 encoders such as https://www.base64encode.org/ to encode the object and then call the API endpoint as follows:

curl -vL "https://analytics-us.searchstax.com/api/v2/track/?data=ewogICJldmVudCI6ICJfc2VhcmNoIiwKICAicHJvcGVydGllcyI6IHsKICAgICJrZXkiOiAiaW1ETXJzNTZhVGFESmM2amloRGVqVWtEWllqM0dtOHJpSkhsUjBWMVM1OCIsCiAgICAicXVlcnkiOiAic2l0ZWNvcmUiLAogICAgInNob3duSGl0cyI6IDMsCiAgICAidG90YWxIaXRzIjogMTIsCiAgICAicGFnZU5vIjogMSwKICAgICJsYXRlbmN5IjogNiwKICAgICJzZXNzaW9uIjogInI2aXZweGtkM2UyOTRrSjI5OVYwdFZiMXEiLAogICAgImltcHJlc3Npb25zIjogWwogICAgICB7CiAgICAgICAgImNEb2NJZCI6ICJodHRwczovL3d3dy5zZWFyY2hzdGF4LmNvbS9zb2x1dGlvbnMvc2l0ZWNvcmUtc29sci8iLAogICAgICAgICJjRG9jVGl0bGUiOiAiTWFuYWdlZCBTb2xyIFNlcnZpY2UgZm9yIFNpdGVjb3JlIHwgU2VhcmNoU3RheCIsCiAgICAgICAgInBvc2l0aW9uIjogMQogICAgICB9LAogICAgICB7CiAgICAgICAgImNEb2NJZCI6ICJodHRwczovL3d3dy5zZWFyY2hzdGF4LmNvbS9ibG9nL3NpdGUtc2VhcmNoLWZvci1zaXRlY29yZS12aWRlby8iLAogICAgICAgICJjRG9jVGl0bGUiOiAiU2l0ZSBTZWFyY2ggZm9yIFNpdGVjb3JlIC0gVmlkZW8gfCBUaGUgU2VhcmNoIEV4cGVyaWVuY2UgQmxvZyIsCiAgICAgICAgInBvc2l0aW9uIjogMgogICAgICB9LAogICAgICB7CiAgICAgICAgImNEb2NJZCI6ICJodHRwczovL3d3dy5zZWFyY2hzdGF4LmNvbS9zaXRlY29yZS1henVyZS10by1zb2xyLW1pZ3JhdGlvbi8iLAogICAgICAgICJjRG9jVGl0bGUiOiAiTWlncmF0ZSBBenVyZSBTZWFyY2ggdG8gU29sciBmb3IgU2l0ZWNvcmUgfCBTZWFyY2hTdGF4IiwKICAgICAgICAicG9zaXRpb24iOiAzCiAgICAgIH0KICAgIF0sCiAgICAiX3ZpZCI6ICJkN2NjMzcyYS0yYmU2LWVlMWUtMjZlOC0wZjkwM2ZhMzZlNjciCiAgfQp9"

The above method returns an HTTP status code of 201/204 if the event was successfully added.

DATA = base64encode(searchObj)
curl -v "https://analytics-us.searchstax.com/api/v2/track/?data=$DATA"

Track Search Clicks

To start generating data around click-through events, search quality and relevance, have /track send _searchclick event to the Analytics App.

var searchClickObj = {
  "event": "_searchclick",
  "properties": {
    "key": "imDMrs56aTaDJc6jihDejUkDZYj3Gm8riJHlR0V1S58",
    "query": "sitecore",
    "shownHits": 12,
    "totalHits": 143,
    "pageNo": 1,
    "latency": 6,
    "session": "jtVM0lqSBMEfmBDYBHaUjodIL",
    "cDocId": "https://www.searchstax.com/blog/site-search-for-sitecore-video/",
    "cDocTitle": "Site Search for Sitecore - Video | The Search Experience Blog",
    "position": 2,
    "_vid": "d7cc372a-2be6-ee1e-26e8-0f903fa36e67"
  }
}

PropertyDescriptionExample
event:
required
string
Type of user action on search page.‘_searchclick’
key:
required
string
Unique Analytics API Key‘IeDTTDD1ubJdfPMmu7MMxxVjUMdw6vo52BjPixxqwcQ’
user:
optional
string
A token identifying the webpage user. This datum is stored but is not currently used.‘smith123’
session:
required
string
The ID of the web session or mobile application session. ‘qqMKt4fxhcud0T5c3UJ5spgug’
query:
required
string
The query string from your search page, or q from the response document.‘sitecore’
cDocId:
required
string
The document ID from the response document.‘https://www.searchstax.com/blog/site-search-for-sitecore-video/’
cDocTitle
optional
string
The document title from the response document. Note: In some applications, the document title may change. Analytics can be calculated as long as cDocID remains constant.‘Site Search for Sitecore – Video | The Search Experience Blog’
position:
required
number
Absolute position of the document in the full list of results. If we’re showing ten items per page, the first result on the 5th page is position in position 41. First item on the first page has position as 12
pageNo:
optional
number
The page number of the displayed results, from the response document.1
pageUrl:
optional
string
The URL of the page that is sending the tracking request‘https://searchstudio.searchstax.com/search’
shownHits:
optional
number
The number of hits shown in the response document.10
totalHits:
optional
number
The number of hits in the index, from the response document.1890
_vid:
required
string
Unique Identifier for the visitor.d7cc372a-2be6-ee1e-26e8-0f903fa36e67

To call the REST API and insert the event, the event object should be encoded to Base64 and passed as the data, just like for the _search event

DATA = base64encode(searchClickObj)
curl -v "https://analytics-us.searchstax.com/api/v2/track/?data=$DATA"

The above method returns an HTTP status code of 201/204 if the event was successfully added.





Track Search Satisfaction

SearchStax provides the ability to collect qualitative feedback about the search experience using the event _searchSatisfaction as shown below:

var searchSatisfactionObj = {
  "event": "_searchSatisfaction",
  "properties": {
    "key": "imDMrs56aTaDJc6jihDejUkDZYj3Gm8riJHlR0V1S58",
    "email": "user1@searchstax.com",
    "score": 10,
    "comments": "Very good search experience",
    "_vid": "d7cc372a-2be6-ee1e-26e8-0f903fa36e67"
  }
}
PropertyDescriptionExample
key:
required
string
Unique Analytics API Key.‘imDMrs56aTaDJc6jihDejUkDZYj3Gm8riJHlR0V1S58’
session:
required
string
The ID of the web session or mobile application session.‘qqMKt4fxhcud0T5c3UJ5spgug’
email:
optional
string
Email ID of the user submitting the feedback‘user123@searchstax.com’
comments:
optional
string
Feedback about the search experience as a comment‘Very good search experience’
score:
required
string
0-10 score, rating the search experience10
_vid:
required
string
Unique Identifier for the visitord7cc372a-2be6-ee1e-26e8-0f903fa36e67″

To call the REST API and insert the event, the event object should be encoded to Base64 and passed as the data, just like for the _search event

DATA = base64encode(searchSatisfactionObj)
curl -v "https://analytics-us.searchstax.com/api/v2/track/?data=$DATA"

The above method returns an HTTP status code of 201/204 if the event was successfully added.