Skip to main content

How to Send Analytics Data from AddSearch Search API Usage

When you develop a custom search interface using the AddSearch Search API, you can track user search behavior and clicks by sending analytics data to the AddSearch Analytics backend. This guide explains how to set up this tracking manually.

What Analytics Data is Collected Automatically​

By default, when using the Search API, AddSearch Analytics collects:

  • The keywords users enter in the search box
  • Keywords that return no search results

To improve insights, you can also track which search results users click.

Sending Click Data to AddSearch Analytics​

AddSearch provides a JavaScript client library with a method to send search result click events.

Step 1: Include the AddSearch JS Client Library​

Add this script tag to your search results page's HTML template, replacing YOUR_SITEKEY with your public sitekey:

<script async src="https://cdn.addsearch.com/api/client.js" defer></script>
<script>
  var client = new AddSearchClient('YOUR_SITEKEY');
</script>

Step 2: Send Click Events Using sendStatsEvent​

When a user clicks a search result link, call sendStatsEvent to record the event:

client.sendStatsEvent('click', keyword, {
  documentId: id,
  position: n
});
  • keyword: The search keyword string used to generate results.
  • documentId: The unique ID of the clicked search result (32-character string).
  • position: The 1-based position index of the clicked result in the current result list.

Add listener attributes to your search result elements to detect clicks or activation:

  • Use onpointerdown to capture mouse clicks and touch events.
  • Use onkeyup with keyboard keys (especially Enter) for accessibility.

Example:

<a href="result-url" 
   onpointerdown="client.sendStatsEvent('click', keyword, {documentId: id, position: n});" 
   onkeyup="if(event.key === 'Enter') client.sendStatsEvent('click', keyword, {documentId: id, position: n});">
  Result title
</a>

Replace keyword, id, and n with the appropriate dynamic values.

Additional Resources​

About the Self-Learning Algorithm​

The click data sent through sendStatsEvent helps improve your search quality by feeding into AddSearch's self-learning algorithm.

This algorithm uses user interaction data to optimize ranking and relevance over time.

Note: Verify you use your correct public sitekey when initializing AddSearchClient to ensure data reports to the right Analytics project.