API Reference

POST /v1/stats/{index public key}

Reports search and click events.

Payload for a click event

{
  "action": "click",
  "session": "session_name",
  "keyword": "test query",
  "docid": "abc123",
  "position": 1
}

Payload for a search event

{
  "action": "search",
  "session": "session_name",
  "keyword": "test query",
  "numberOfResults": 4
}

Search event parameters

ParameterDescriptionTypeNote
actionThe type of the user's actionstringMust be "search"
sessionUser's search session identifierstringA sequence of characters, not longer than 32 characters
keywordSearch termsstringMultiple keywords may be split with spaces
numberOfResultsThe number of results returned for the search queryintIf 0, the search is recorded as "No hit" in the analytics overview
tagA tag that can be used to filter analytics in the dashboard. For more information read the article.stringThe maximum length of a tag is 50 characters.

Click event parameters

ParameterDescriptionTypeNote
actionThe type of the user's actionstringMust be "click"
sessionUser's search session identifierstringA sequence of characters, not longer than 32 characters
keywordSearch termsstringMultiple keywords may be split with spaces
docidThe id of the clicked documentstringDocument id is the MD5 hash of a full URL with protocol and possible query parameters. For example the doc id of https://www.addsearch.com/ is 3b1d053e2fdf65f178dc5d1b5bd00f75

The maximum length of a docid is 32 characters.
positionThe position of the clicked document in the search resultsintNumeration starts with 1.
tagA tag that can be used to filter analytics in the dashboard. For more information read the article.stringThe maximum length of a tag is 50 characters.

Returns HTTP 200 OK if successful.

Note: searches made via search API endpoint are reported automatically unless you have the collectAnalytics parameter set to false. Click events should be reported via this endpoint to reflect your search performance in the AddSearch analytics dashboard and adjust ranking based on your users’ behaviour.

Was this helpful?

Need more help?

We’re always happy to help with code or other questions you might have. Search our documentation, contact support, or connect with our sales team.