Event: Search Term

The Search Term event API is designed to track search activities performed by users.

This event is triggered when a user performs a search (i.e. triggers a Search event by clicking the Search button or pressing enter in a Search Input Box), capturing critical data about the search term used and the results generated.

This information is critical for understanding search behavior in order to optimize search models.

• Method: POST

• URL: https://<PA_END_POINT>/3.0/events/search-terms

• Headers:

  • Content-Type: application/json
  • Authorization: Bearer ACCESS_TOKEN

• Request Body Parameters:

  • customerId (GUID) [REQUIRED]: Unique identifier for the customer, obtained from the Config API. This identifier persists throughout the customer's lifetime on the platform. For details on retrieving a customer ID, please refer to the Config API documentation.

  • sessionId (GUID) [REQUIRED]: Unique identifier for the session, consistent throughout the session's duration. For information on obtaining a session ID, please refer to the Config API documentation.

  • events: Array of objects detailing Search Term event. Each Search Term event object will contain following properties:

    • eventTime (dateTime) [REQUIRED]: UTC timestamp of when the checkout happened.

    • searchTerm (string) [REQUIRED]: The search query input by the user.

    • numberOfResults (integer) [REQUIRED]: The number of results returned by the search query.

    • widgetId (GUID) [REQUIRED]: Identifier for the widget a slot belongs to. This information is available as part of the Recommendations API response payload from where the slot's data was collected.

    • routeId (GUID) [REQUIRED]: Route identifier that led to the widget display. This information is available as part of the Recommendations API response payload from where the slot’s data was collected.

• Here is an example payload:

  {
      "customerId": "xxxxxxxxxxxxxxxxxxxxxxx",
      "sessionId": "xxxxxxxxxxxxxxxxxxxxxxx",
      "events": [
          {
              "currentUrl": "https://www.example.com/",
              "eventTime": "2024-03-01T14:00:00.000Z",
              "searchTerm": "T Shirt",
              "numberOfResults": 100,
              "widgetId": "xxxxxxxxxxxxxxxxxxxxxxx",
              "routeId": "xxxxxxxxxxxxxxxxxxxxxxx"
          }
      ]
  }

• Returned Payload:

  On successful update, the returned status code will be ‘202’, and the payload will contain the status message “Accepted” and a transaction ID.

  {
      "transactionId": "xxxxxxxxxxxxxxxxxxxxxxx",
      "status": "Accepted"
  }

  If there are any errors, the response status code will not be ‘202’, and the relevant error messages will be provided as part of “errors” in the returned message. Here is an example -

  {
    "errors": {
        "events[0].refId": [
            "Product must contain a RefId"
        ]
    },
    "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
    "title": "One or more validation errors occurred.",
    "status": 400,
    "traceId": "xxxxxxxxxxxxxxxxxxx"
  }

Here’s an example code snippet using JavaScript’s Fetch API:

const url = 'https://<PA_END_POINT>/3.0/events/search-terms';
const accessToken = 'YOUR_ACCESS_TOKEN'; // Replace with your actual access token
const body = {
  customerId: 'xxxxxxxxxxxxxxxxxxx',
  sessionId: 'xxxxxxxxxxxxxxxxxxx',
  events: [
    {
      currentUrl: "https://www.example.com/",
      eventTime: "2024-03-01T14:00:00.000Z",
      searchTerm: "T Shirt",
      numberOfResults: 100,
      widgetId: "xxxxxxxxxxxxxxxxxxx",
      routeId: "xxxxxxxxxxxxxxxxxxx"
    }
  ]
};

fetch(url, {
  method: 'POST',
  headers: {
    "Authorization": `Bearer ${accessToken}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify(body)
})
  .then(response => response.json())
  .then(data => console.log('Search Term Recorded:', data))
  .catch(error => console.error('Error recording search term:', error));

Summary:

This document is about the Search Term event API, its purpose, request details, response, and example code snippet.

• The Search Term event API tracks user search activities to capture critical data about search terms and results.

• The method for this API is POST, with the URL being https://<PA_END_POINT>/3.0/events/search-terms.

• Request body parameters include customer ID, session ID, and an array containing details of the event.

• On successful update, the returned status code will be ‘202’, and the payload will contain the status message “Accepted” and a transaction ID.

• An example code snippet using JavaScript’s Fetch API is provided for recording search terms.