Content

If it is in your plan to have content search, your team will use the Autocomplete and Search API endpoints in the same way they are used for search functionality. The only difference is any references to the siteId path parameter and query string parameter in the API endpoints will now need to use the siteId for the Athos account where content or blog data is indexed.

Query

The Query query string parameter (q) value should be sourced from the value the end user types in the searchbar to refine results that match against the indexed product data made available from the fields that are configured as a searchable field on the field settings page (must be logged in) in the Athos Management Console. This parameter will support a maximum of 256 characters.

Documentation:

Search API - See q query string parameter
Managing Field Settings - see Display

Background Filters

In the case your team needs to pre-filter results based on specific product data, the background filter parameter (bgfilter) should be used in Search API Requests and not the filter parameter (filter). Some examples of what fields you can pre-filter search results by could be search_only, availability, on_sale, etc. This allows for our reporting to differentiate between customer applied filters and background filter parameters for pre-filtering results.

Documentation:

Search API - See bgfilter query string parameter
Search API - Filtering Results - use cases

Filtering

Filtering Results

All filtering should be done by making requests to the Search API and using the filter query string parameter. Attempting to handle filtering client side will adversely affect Athos reporting and merchandising capabilities.

Documentation:

Search API - See filter query string parameter
Search API - Filtering Results - use cases

Rendering Filter Data

The filters displayed on a results page should be displayed in the order they are returned by the Search API in the facets object and be displayed as collapsed or expanded per the Search API response. It is important that the order of the filters follows the order seen in the Search API response. It is also important that the extra data returned for each facet in the API response is implemented as well as that data is used to describe each filters appearance and behavior. This is important as the data found within each facet can be configured within our tool.

Documentation:

Search API - See facets object in the 200 response code below the query string parameters
Filtering - How to configure filters
Merchandising - Custom Filter Order

Sorting

The sorting options displayed on a results page should be displayed in the order they are returned and use the labels returned in the Search API response. When initially loading a page a sort query string parameter should not be passed as part of the API request. This will allow for merchandising rules to be applied to the results.

All sorting should be done by making requests to the Search API, attempting to handle sorting client side will adversely affect Athos reporting and merchandising capabilities.

Documentation:

Results Per Page

Only the required number of results for the current page should be requested from the Search API. This is used to limit the number of results that should be returned in the API response. All results returned must be rendered.

Documentation:

Sorting & Pagination

Pagination

Your team can choose to utilize traditional pagination or opt to build an infinite scroll feature within your integration. To do this your team can reference the data returned within the pagination object in the API response to build this navigation.

All pagination should be done by making requests to the Search API, attempting to handle pagination client side will adversely affect Ahtos reporting and merchandising capabilities.

Documentation:

Sorting & Pagination

User Tracking Parameters

The query string parameters userId, sessionId, and pageLoadId, and domain are required for our reporting and personalization features to work properly for API requests.

userId will receive its value from the athosUserId cookie
sessionId will receive its value from the athosSessionId cookie
pageLoadId will be a randomly generated UUID v4 value. This should be updated with every physical page load. If the integration is a Single Page Application(SPA) or Headless, this value will change for every URL route change.
domain will receive its value from the current page URL. This shouled be sourced from window.location.href

Documentation:

Search API - see query string parameters userId, sessionId, pageLoadId, domain
Athos Cookies

Content Personalization Parameters

The Preflight API endpoint and the Search API query string parameters here are only applicable if the account is signed up and configured for Personalized Search & Merchandising. The first step is to ensure a call to the Preflight API is made when a shopper logs into your website and all relevant data is sent to the endpoint. If any of the relevant data notated in the endpoint changes as the customer is interacting with the website, ensure the new data is sent to the endpoint before a call to the Autocomplete API or Search API endpoints are made so that our system can allow personalization to occur within the returned result sets.

To learn more about the Personalized Search & Merchandising feature and the requirements, please refer to the following documents:

Query string parameters

shopper
cart
lastViewed

Documentation

Preflight API: GET - See query string parameters shopper, cart, and lastViewed
Preflight API: POST - See query string parameters shopper, cart, and lastViewed
Search API - See query string parameters shopper, cart, and lastViewed
Personalized Search & Merchandising
Can I use Personalized Search & Merchandising?

Beacon Tracking

Content results displayed from the search result pages require tracking events to capture shopper interactions with the search results, filters, and products. This includes tracking when results are rendered, which products are viewed (impressions), and when items are clicked or added to cart. For complete implementation details and event requirements, see the Search Tracking Guide.