Analytics event API reference
editAnalytics event API reference
editRecord users' interactions with search results as events within the Workplace Search analytics logs.
POST /api/ws/v1/analytics/event
Workplace Search’s default search application records users' clicks on search results as events within the analytics logs.
Similarly, when building your own search experiences for Workplace Search, use the analytics event API to record clicks and positive/negative feedback on search results.
Submit an API request for each event. Refer to the following sections for more details on the types of events and their parameters.
Request templates
editClick event request template:
curl \ --request 'POST' \ --url '<WORKPLACE_SEARCH_BASE_URL>/api/ws/v1/analytics/event' \ --header 'Authorization: Bearer <ACCESS_TOKEN>' \ --header 'Content-Type: application/json' \ --data '{ "type": "click", "query_id": "<STRING>", "page": <INT>, "content_source_id": "<STRING>", "document_id": "<STRING>", "rank": <INT>, "event": "<STRING>" }'
Feedback event request template:
curl \ --request 'POST' \ --url '<WORKPLACE_SEARCH_BASE_URL>/api/ws/v1/analytics/event' \ --header 'Authorization: Bearer <ACCESS_TOKEN>' \ --header 'Content-Type: application/json' \ --data '{ "type": "feedback", "query_id": "<STRING>", "page": <INT>, "content_source_id": "<STRING>", "document_id": "<STRING>", "rank": <INT>, "score": <INT> }'
Request headers
edit-
Authorization
-
Bearer token permitting API access. See Configuring the OAuth Application for Search.
-
Content-Type
-
application/json
Request body
edit-
type
(required) -
The string
click
or the stringfeedback
. The value specifies the type of analytics event.Submit a click event to indicate a user chose a document from a list of search results, such as clicking the result to view its details. The event represents implicit positive feedback from the user.
Submit a feedback event to indicate a user provided positive or negative feedback on a search result, such as clicking a heart, +1, or thumbs down for that result. The event represents explicit positive or negative feedback from the user. Use
score
to indicate if the feedback was positive or negative. -
query_id
(required) -
The string ID of the search API request that returned the result that received the event. Use the value
meta.request_id
from the search API response. -
document_id
(required) -
The string ID of the document within the results that received the event. Use the value
_meta.id
from the applicable document within theresults
of the search API response. -
content_source_id
(required) -
The string ID of the content source of the document that received the event. Use the value
_meta.content_source_id
from the applicable document within theresults
of the search API response. -
page
(required) -
The integer page number of the search API response that received the event. Must be greater than or equal to
1
(page numbers begin at1
). Use the valuemeta.page.current
from the search API response. -
rank
(required) -
The integer rank of the document within the entire result set. Must be greater than or equal to
0
. Calculate the value as follows:((page - 1) * per_page) + position
where:
-
page
is the value of thepage
parameter (above). -
per_page
is the number of documents per page of results. Use the valuemeta.page.size
from the search API response. -
position
is the position of the applicable document within the current page. Use the zero-based index of the document within theresults
array of the search API response.
-
-
event
(required) -
(Click events only) A string to label the source or target of the click. Analysts consuming the events in the analytics logs can filter on this value. Use any value that is meaningful to your team.
For example, if you have multiple search UIs, use different values to differentiate clicks within those UIs:
web
,mobile
.Or, perhaps results within a single UI have multiple click targets. One target expands details within the same page, while the other navigates to a new page. Differentiate those targets:
internal
,external
.Suggested default value:
api
. -
score
(required) -
(Feedback events only) The integer
1
or-1
, indicating positive or negative feedback, respectively.
Request examples
editClick event request examples:
curl \ --request 'POST' \ --url 'https://f3fae9ab3e4f423d9d345979331ef3a1.ent-search.us-east-1.aws.cloud.es.io:443/api/ws/v1/analytics/event' \ --header 'Authorization: Bearer 7ea05c8bd50ab5c75d2b71adbcb9ae71c4034d7a4f8d6c16a8940510a951cec7' \ --header 'Content-Type: application/json' \ --data '{ "type": "click", "query_id": "2992570ab570b581ac6c457bddf68835", "page": 1, "content_source_id": "5f91bf7888f9297b02a3d80c", "document_id": "product-123", "rank": 0, "event": "app" }'
curl \ --request 'POST' \ --url 'http://localhost:3002/api/ws/v1/analytics/event' \ --header 'Authorization: Bearer 64c51eee12c1f7a3be8ab0ecf9a2184106c1641e49736119414da0c0e85f3611' \ --header 'Content-Type: application/json' \ --data '{ "type": "click", "query_id": "4553570bc681c681ac6c457beed79946", "page": 1, "content_source_id": "6e82ce8999e8388c13b4e91d", "document_id": "product-456", "rank": 5, "event": "ui" }'
Feedback event request examples:
curl \ --request 'POST' \ --url 'https://f3fae9ab3e4f423d9d345979331ef3a1.ent-search.us-east-1.aws.cloud.es.io:443/api/ws/v1/analytics/event' \ --header 'Authorization: Bearer 7ea05c8bd50ab5c75d2b71adbcb9ae71c4034d7a4f8d6c16a8940510a951cec7' \ --header 'Content-Type: application/json' \ --data '{ "type": "feedback", "query_id": "2992570ab570b581ac6c457bddf68835", "page": 1, "content_source_id": "5f91bf7888f9297b02a3d80c", "document_id": "product-123", "rank": 0, "score": 1 }'
curl \ --request 'POST' \ --url 'http://localhost:3002/api/ws/v1/analytics/event' \ --header 'Authorization: Bearer 64c51eee12c1f7a3be8ab0ecf9a2184106c1641e49736119414da0c0e85f3611' \ --header 'Content-Type: application/json' \ --data '{ "type": "feedback", "query_id": "4553570bc681c681ac6c457beed79946", "page": 1, "content_source_id": "6e82ce8999e8388c13b4e91d", "document_id": "product-456", "rank": 5, "score": -1 }'
Responses
edit-
200 OK
-
The event was successfully created. The response body is empty.
-
401 Unauthorized
-
The authorization header was missing from the request, authentication failed, or the authenticated user does not have permission.
-
400 Bad Request
-
The request body was incomplete or invalid. The response body provides additional information.