Event: Search Term

The Search Term event is used to track user search activities. This data is essential for understanding customer search behavior and optimizing search results and product recommendations.

API Endpoint

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

Request Header

Name	Value
Content-Type	application/json
Authorization	Bearer ACCESS_TOKEN

Request Parameters (Body)

Parameter	Type	Required	Description
customerId	GUID	✅	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	✅	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	✅	Array of objects detailing search events. Each search event object will contain the following properties:

Event Object Definition

Parameter	Type	Required	Description
keyword	string	✅	The search term or keyword entered by the user.
currentUrl	string	✅	URL where the search was performed.
eventTime	dateTime	✅	UTC timestamp of when the search occurred.
resultCount	integer	❌	Number of search results returned.
departmentId	string	❌	Department ID if the search was performed within a specific department.
departmentName	string	❌	Department name if the search was performed within a specific department.
categoryId	string	❌	Category ID if the search was performed within a specific category.
categoryName	string	❌	Category name if the search was performed within a specific category.
filter	string	❌	Filter parameters applied to the search (e.g., price range, brand, etc.).
sort	string	❌	Sort order applied to the search results.
page	integer	❌	Page number of search results viewed.
referralUrl	string	❌	URL that referred the user to the search page.

Example Request Payload

{
  "customerId": "xxxxxxxxxxxxxxxxxxxxxxx",
  "sessionId": "xxxxxxxxxxxxxxxxxxxxxxx",
  "events": [
    {
      "keyword": "summer dresses",
      "currentUrl": "https://www.example.com/search?q=summer+dresses",
      "eventTime": "1970-01-01T14:00:00.000Z",
      "resultCount": 120,
      "departmentId": "women",
      "departmentName": "Women's Clothing",
      "categoryId": "dresses",
      "categoryName": "Dresses",
      "filter": "price:20-100,color:blue|red",
      "sort": "price_low_high",
      "page": 1,
      "referralUrl": "https://www.example.com/women"
    }
  ]
}

Response

On Success

On successful post, the returned status code will be 202, and the payload will contain the status message "Accepted" and a transaction ID.

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

On Error

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].Keyword": [
      "'Keyword' must not be empty."
    ]
  },
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "traceId": "xxxxxxxxxxxxxxxxxxx"
}

Example Usage (JavaScript)

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: 'xxxxxxxxxxxxxxxxxxxxxxx',
  sessionId: 'xxxxxxxxxxxxxxxxxxxxxxx',
  events: [
    {
      keyword: 'summer dresses',
      currentUrl: 'https://www.example.com/search?q=summer+dresses',
      eventTime: '1970-01-01T14:00:00.000Z',
      resultCount: 120,
      departmentId: 'women',
      departmentName: 'Women\'s Clothing',
      categoryId: 'dresses',
      categoryName: 'Dresses',
      filter: 'price:20-100,color:blue|red',
      sort: 'price_low_high',
      page: 1,
      referralUrl: 'https://www.example.com/women'
    }
  ]
};

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 provides details about the Search Term API, which is essential for tracking search behavior in your eCommerce application:

• The API is used to capture customer search activities for analytics and search optimization
• The endpoint uses a POST method with URL https://<PA_END_POINT>/3.0/events/search-terms
• Required parameters include customer ID, session ID, and search details such as keyword and URL
• Optional parameters allow for more detailed analysis, including result count, department/category information, and filters
• The API returns a 202 status code with a transaction ID on successful recording
• Error responses include relevant error messages and a 400 status code
• JavaScript example demonstrates how to implement the API call in your application