For new users, we recommend using our Elasticsearch-native tools, rather than the standalone Workplace Search product. See this blog post for more information about upgrading your internal knowledge search, to make it an amazing experience for your users!
« OAuth Service API Reference Synonyms API reference »
Elastic Docs › ›Workplace Search API Reference

Analytics event API reference

edit

Analytics event API reference

edit

Record users' interactions with search results as events within the Workplace Search analytics logs.

POST <ENTERPRISE_SEARCH_BASE_URL>/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

edit

Click event request template:

curl \
--request 'POST' \
--url '<ENTERPRISE_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 '<ENTERPRISE_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 string feedback. 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 the results 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 the results 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 at 1). Use the value meta.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 the page parameter (above).
  • per_page is the number of documents per page of results. Use the value meta.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 the results 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

edit

Click event request examples:

curl \
--request 'POST' \
--url '<ENTERPRISE_SEARCH_BASE_URL>/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 '<ENTERPRISE_SEARCH_BASE_URL>/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 '<ENTERPRISE_SEARCH_BASE_URL>/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 '<ENTERPRISE_SEARCH_BASE_URL>/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.

« OAuth Service API Reference Synonyms API reference »