Analytics Reporting REST API

This page describes how a SearchStax Studio Enterprise Plan client can use the SearchStax® Analytics Tracking REST API to retrieve search events and items from the Search App.

The Tracking REST API can also perform Power Searches of searches and items.  

Reporting URL and Key

On the Settings page of your Search App, the Analytics API tab contains the Analytics Reporting API Endpoint and the Analytics Reporting API Key. The key is used to identify the Search App.

The Analytics Reporting API Endpoint is https://analytics-us.searchstax.com.

Reports

The Analytics Reporting REST API supports the following reporting actions:

Each type of report has its own set of required properties, which are detailed below.

Report Searches

To create a report of Most-Popular Searches, No-Result Searches, and No-Click Searches, use a cURL command in this general format:

curl '<Reporting API Endpoint>/api/rest/analytics/v1/reporting/searches/searches' -H 'authorization: Token <Key>'

A fully-expanded example resembles this:

curl 'https://analytics-us.searchstax.com/api/rest/analytics/v1/reporting/searches/searches?&startDate=2022-02-06T07:00:00&endDate=2022-02-28T06:59:59&offset=0&limit=10&language=en' -H 'authorization: Token 4Qp1Sv9MnALbAGbixW9ZaW95338fwm6i'

Parameter Description Example
key:
required
string		 Unique Analytics Reporting API Key 4Qp1Sv9MnALbAGbixW9ZaW95338fwm6i
startdate:
optional
datetime		 The date and time (UTC) of the earliest events in the report. Defaults to the last 31 days. 2022-02-06T07:00:00
enddate:
optional
string		 The date and time (UTC) of the latest events in the report. Default to the last 31 days. Max end date is 31 days after the start date. 2022-02-28T06:59:59
offset:
optional
number		 This index begins at 0. It is used for how far down in the results for most popular searches, no result searches, and searches with no clicks tables to start collecting in the report. Defaults to 0. 0
limit:
optional
number		 This number begins at 0. It is used for how far down in the results for most popular searches, no result searches, and searches with no clicks tables to end the collection of data in the report.Defaults to the end of the results. 10
language:
optional
string		 A two-letter language code. Defaults to the default language. en

The returned value is a JSON document describing searches. The parameters map into the values shown in the Studio Searches screen. A partial sample is shown below.

{
  "aggMetrics": [
    {
      "resultSearchCount": 58,
      "totalSearchCount": 61,
      "clickThroughRate": 36.0655737704918,
      "clickCount": 21,
      "sessionCount": 7,
      "sessionWithSearchCount": 6,
      "sessionWithSearchPercent": 85.71428571428571,
      "avgClickPosition": 2.380952380952381,
      "meanReciprocalRank": 0.6373015873015873,
      "noResultSearchCount": 3,
      "noResultSearchPercent": 4.918032786885246,
      "searchWithClickCount": 22,
      "searchExitCount": 1,
      "searchExitPercent": 14.285714285714285,
      "searchPerSessionCount": 8.714285714285714,
      "startDate": "2022-02-06T07:00:00+00:00",
      "endDate": "2022-02-28T06:59:59+00:00"
    }
  ],
  "topNoClickSearches": [
    {
      "searchCount": 6,
      "sumClicks": 0,
      "clickThroughRate": 0,
      "avgLatency": 21.166666666666668,
      "avgHits": 403,
      "query": "search",
      "ofTotal": 9.836065573770492
    },
    {
      "searchCount": 5,
      "sumClicks": 0,
      "clickThroughRate": 0,
      "avgLatency": 121.2,
      "avgHits": 80,
      "query": "drupal",
      "ofTotal": 8.19672131147541
    },
    {
      "searchCount": 5,
      "sumClicks": 0,
      "clickThroughRate": 0,
      "avgLatency": 18.4,
      "avgHits": 173,
      "query": "sitecore plugin",
      "ofTotal": 8.19672131147541
    },

Report Items

To create a report of Most-Clicked and Least-Clicked Items, use a cURL command in this general format:

curl '<Analytics Reporting API Endpoint>/api/rest/analytics/v1/reporting/clicks/clicks' -H 'authorization: Token <Key>'

A fully-expanded example resembles this:

curl 'https://analytics-us.searchstax.com/api/rest/analytics/v1/reporting/clicks/clicks?&startDate=2022-02-06T07:00:00&endDate=2022-02-28T06:59:59&offset=0&limit=10&language=en' -H 'authorization: Token V3B2XGcj9nmA8cMJiEp5UURb1eZzQMiKL953384dszU'

Parameter Description Example
key:
required
string		 Unique Analytics Reporting API Key 4Qp1Sv9MnALbAGbixW9ZaW95338fwm6i
startdate:
optional
datetime		 The date and time (UTC) of the earliest events in the report. Defaults to the last 31 days. 2022-02-06T07:00:00
enddate:
optional
string		 The date and time (UTC) of the latest events in the report. Default to the last 31 days. Max end date is 31 days after the start date. 2022-02-28T06:59:59
offset:
optional
number		 This index begins at 0. It is used for how far down in the results for most popular searches, no result searches, and searches with no clicks tables to start collecting in the report. Defaults to 0. 0
limit:
optional
number		 This number begins at 0. It is used for how far down in the results for most popular searches, no result searches, and searches with no clicks tables to end the collection of data in the report.Defaults to the end of the results. 10
language:
optional
string		 A two-letter language code. Defaults to the default language. en

The returned value is a JSON document describing items. The parameters map into the values shown in the Studio Items screen. A partial sample is shown below.

{
  "aggMetrics": [
    {
      "impressionCount": 663,
      "clickCount": 21,
      "contentClickThroughRate": 3.167420814479638,
      "avgClickPosition": 2.380952380952381,
      "startDate": "2022-02-06T07:00:00+00:00",
      "endDate": "2022-02-28T06:59:59+00:00"
    }
  ],
  "mostClicked": [
    {
      "clickCount": 1,
      "ofTotal": 4.761904761904762,
      "cDocId": "095c1ffe-d2bb-4bc3-82ae-8c13075e5021",
      "cDocTitle": "Microsoft Azure | SearchStax Partners",
      "impressionCount": 2,
      "contentClickThroughRate": 50,
      "avgClickPosition": 2
    },
    {
      "clickCount": 1,
      "ofTotal": 4.761904761904762,
      "cDocId": "0a13ade1-da89-4a78-9531-50efacfc48b4",
      "cDocTitle": "Sitecore 10.0 - SearchStax Docs",
      "impressionCount": 7,
      "contentClickThroughRate": 14.285714285714285,
      "avgClickPosition": 5
    },
    {
      "clickCount": 1,
      "ofTotal": 4.761904761904762,
      "cDocId": "1115779e-6aa5-456c-bb39-2a372c589bd6",
      "cDocTitle": "Solr Version Policy | SearchStax",
      "impressionCount": 1,
      "contentClickThroughRate": 100,
      "avgClickPosition": 3
    },

Power Search (Searches)

To perform a Power Search of Searches using the REST API, use a cURL command in this general format:

curl '<Reporting API Endpoint>/api/rest/analytics/v1/reporting/searches/power-search/searches?&filterName=<Filter Name>&filterOperator=<Filter Operator>&filterValue=<Filter Value>&ordering=<Ordering>' -H 'authorization: Token <Key>'

A fully-expanded example resembles this:

curl 'https://analytics-us.searchstax.com/api/rest/analytics/v1/reporting/searches/power-search/searches?filterName=clickThroughRate&filterOperator=gt&filterValue=3&ordering=-clickThroughRate&startDate=2022-02-06T07:00:00&endDate=2022-02-28T06:59:59&offset=0&limit=10&language=en' -H 'authorization: Token V3B2XGcj9nmA8cMJiEp5UURb1eZzQMiKL953384dszU'

Note that you can use up to three filterName=”name”&filterOperator=”operator”&filterValue=”value” constructions in sequence to apply multiple filters.

Parameter Description Example
key:
required
string		 Unique Analytics Reporting API Key 4Qp1Sv9MnALbAGbixW9ZaW95338fwm6i
filterName:
required
string		 The name of the filter as seen on the Power Search screen. clickThroughRate
avgHits
searchCount
sumClicks
avgClickPosition
avgLatency
filterOperator
required
string		 The filter operator to be applied. Must appear between filterName and filterValue. gt
gte
lt
lte
eq
filterValue
required
number		 The value that the filter will test. 50
ordering
required
string		 The results are ordered by the filterName specified. This defaults to sort by ascending. Applying a ‘-’ before the filterName will produce a descending sort. -clickThroughRate
startdate:
optional
datetime		 The date and time (UTC) of the earliest events in the report. Defaults to the last 31 days. 2022-02-06T07:00:00
enddate:
optional
string		 The date and time (UTC) of the latest events in the report. Default to the last 31 days. Max end date is 31 days after the start date. 2022-02-28T06:59:59
offset:
optional
number		 This index begins at 0. It is used for how far down in the results for most popular searches, no result searches, and searches with no clicks tables to start collecting in the report. Defaults to 0. 0
limit:
optional
number		 This number begins at 0. It is used for how far down in the results for most popular searches, no result searches, and searches with no clicks tables to end the collection of data in the report.Defaults to the end of the results. 10
language:
optional
string		 A two-letter language code. Defaults to the default language. en

The returned value is a JSON document describing searches. The parameters map into the values shown in the Studio Power Search screen. A partial sample is shown below.

{
  "results": [
    {
      "searchCount": 1,
      "sumClicks": 3,
      "clickThroughRate": 100,
      "avgLatency": 34,
      "avgHits": 67,
      "query": "partner",
      "ofTotal": 1.639344262295082,
      "avgClickPosition": 2.3333333333333335
    },
    {
      "searchCount": 1,
      "sumClicks": 2,
      "clickThroughRate": 100,
      "avgLatency": 39,
      "avgHits": 35,
      "query": "private",
      "ofTotal": 1.639344262295082,
      "avgClickPosition": 2.5
    },
    {
      "searchCount": 1,
      "sumClicks": 3,
      "clickThroughRate": 100,
      "avgLatency": 69,
      "avgHits": 432,
      "query": "solr",
      "ofTotal": 1.639344262295082,
      "avgClickPosition": 2
    },

Power Search (Items)

To perform a Power Search of Items using the REST API, use a cURL command in this general format:

curl '<Reporting API Endpoint>/api/rest/analytics/v1/reporting/clicks/power-search/clicks?&filterName=<Filter Name>&filterOperator=<Filter Operator>&filterValue=<Filter Value>&ordering=<Ordering>' -H 'authorization: Token <Key>'

A fully-expanded example resembles this:

curl 'https://analytics-us.searchstax.com/api/rest/analytics/v1/reporting/clicks/power-search/clicks?filterName=contentClickThroughRate&filterOperator=lte&filterValue=20&ordering=-contentClickThroughRate&startDate=2022-02-06T07:00:00&endDate=2022-02-28T06:59:59&offset=0&limit=10&language=en' -H 'authorization: Token V3B2XGcj9nmA8cMJiEp5UURb1eZzQMiKL953384dszU'

Note that you can use up to three filterName=”name”&filterOperator=”operator”&filterValue=”value” constructions in sequence to apply multiple filters.

Parameter Description Example
key:
required
string		 Unique Analytics Reporting API Key 4Qp1Sv9MnALbAGbixW9ZaW95338fwm6i
filterName:
required
string		 The name of the filter as seen on the Power Search screen. contentClickThroughRate
impressionCount
clickCount
filterOperator
required
string		 The filter operator to be applied. Must appear between filterName and filterValue. gt
gte
lt
lte
eq
filterValue
required
number		 The value that the filter will test. 50
ordering
required
string		 The results are ordered by the filterName specified. This defaults to sort by ascending. Applying a ‘-’ before the filterName will produce a descending sort. -contentClickThroughRate
startdate:
optional
datetime		 The date and time (UTC) of the earliest events in the report. Defaults to the last 31 days. 2022-02-06T07:00:00
enddate:
optional
string		 The date and time (UTC) of the latest events in the report. Default to the last 31 days. Max end date is 31 days after the start date. 2022-02-28T06:59:59
offset:
optional
number		 This index begins at 0. It is used for how far down in the results for most popular searches, no result searches, and searches with no clicks tables to start collecting in the report. Defaults to 0. 0
limit:
optional
number		 This number begins at 0. It is used for how far down in the results for most popular searches, no result searches, and searches with no clicks tables to end the collection of data in the report.Defaults to the end of the results. 10
language:
optional
string		 A two-letter language code. Defaults to the default language. en

The returned value is a JSON document describing items. The parameters map into the values shown in the Studio Power Search screen. A partial sample is shown below.

{
  "results": [
    {
      "clickCount": 1,
      "ofTotal": 4.761904761904762,
      "cDocId": "0a13ade1-da89-4a78-9531-50efacfc48b4",
      "cDocTitle": "Sitecore 10.0 - SearchStax Docs",
      "impressionCount": 7,
      "contentClickThroughRate": 14.285714285714285,
      "avgClickPosition": 5
    },
    {
      "clickCount": 1,
      "ofTotal": 4.761904761904762,
      "cDocId": "4e33c9c8-008a-43f9-bc08-85f8fc5e68c0",
      "cDocTitle": "Free Disk Space - SearchStax Docs",
      "impressionCount": 7,
      "contentClickThroughRate": 14.285714285714285,
      "avgClickPosition": 1
    },
    {
      "clickCount": 1,
      "ofTotal": 4.761904761904762,
      "cDocId": "6289d367-00f2-4817-8659-00a5b0172ad3",
      "cDocTitle": "Sitecore Archives - SearchStax Docs",
      "impressionCount": 18,
      "contentClickThroughRate": 5.555555555555555,
      "avgClickPosition": 1
    },

Questions?

Do not hesitate to contact the SearchStax Support Desk.