XSearch Service

The XSearch service provides four main capabilities:

Run a standard search query to retrieve results with full control over pagination, sorting, and filters
Pull all possible property values for a collection to power facets and filter menus
View trending search terms to understand what shoppers are looking for most.
View search suggestions terms for a user’s current query.

Methods

// Returns a search response containing the results
xg.search.getResults({query: 'coat', options: {collection: '<collection>', deploymentId:'<deployment_id>'}});

// Returns a list of property values for the given collection
xg.search.getResultValues({collection: '<collection>'});

// Returns a list of trending search terms for the given collection
xg.search.getTrendingSearches({collection: '<collection>'});

// Returns a list of search suggestions from the given collection
xg.search.getSearchSuggestions({collection: '<collection>', query: '<query>'});

getResults

getResults

Description: Gets recommendation results by a single search experience id.

Parameters

Name	Type	Required	Description
`query`	`string`	✅	The ID of the element
`options`	`object`	✅	Options object that allows you to control the search result response
↳ `options.collection`	`string`	✅	Collection to get items from
↳ `options.deploymentId`	`string`	✅	The deploymentId to get search results for
↳ `options.locale`	`string`	❌	The locale used for tracking (it is recommended to provide this globally when initializing the `XGenClient`)
↳ `options.page`	`number`	❌	The page of results
↳ `options.pageSize`	`number`	❌	The number of results per page (max is 120). Default is 60.
↳ `options.facets`	`boolean \| 'v1' \| 'v2'`	❌	If facets is passed as `true` or `v2` it will use the v2 faceting engine. If facets is passed as `v1` it will use the v1 facet engine.
↳ `options.forceDeepSearch`	`boolean`	❌	If deep search should be forced. Useful for Type to Search.
↳ `options.sortBy`	`'price' \| 'update_date'`	❌	Sort by price or update date
↳ `options.sortOrder`	`'asc' \| 'desc'`	❌	Sort order
↳ `options.context`	`object`	❌	Context object used for dynamic filtering
↳ `options.url`	`string`	❌	The url used for tracking purposes. This will be passed by default in the browser.
↳ `options.referrer`	`string`	❌	The referrer used for tracking purposes. This will be passed by default in the browser.
`autoTrack`	`boolean`	❌ (defaults to `true`)	Can turn off auto tracking of `search` and `search_result` events
`queryId`	`string`	❌	An optional queryId passed to cancel a request

Returns

A Promise resolving to the object below:

{
  items: SearchProduct[];
  facets: { [key: string]: unknown };
  isFromCache: boolean;
  page: number;
  keyword: string;
  isUrlRedirect: boolean;
  urlRedirect: string;
  isQueryTranslated: boolean;
  isCachedFilterApplied: boolean;
  isKeywordConfigApplied: boolean;
  behaviorId: string;
  responseEngine: string;
  totalResults: number;
  sortedBy: string;
  variantMapping?: { [key: string]: string };
  searchTermMatches?: string[];
  filter: { [key: string]: unknown }[];
  queryId: string;
}

getResultValues

getResultValues

Description: Gets the possible properties of a search result.

Parameters

Name	Type	Required	Description
`collection`	`string`	✅	Collection to get items from
`productId`	`string`	❌	Can specify a specific product to get values for

Returns

A Promise resolving to the object below:

{
  [key: string]: {
    name: string;
    count: number;
  }
}

getTrendingSearches

getTrendingSearches

Description: Returns a list of trending search terms for the given collection.

Parameters

Name	Type	Required	Description
`collection`	`string`	✅	Collection to get items from

Returns

A Promise resolving to the array below:

string[];

getSearchSuggestions

getSearchSuggestions

Description: Returns a list of search suggestions based on search_result events. This has a look back period of 5 days and the query sent must be 3 characters or more to get results. (note: this endpoint will return empty results if there is not enough event data being sent)

Parameters

Name	Type	Required	Description
`collection`	`string`	✅	Collection to get items from
`query`	`string`	✅	The query to get suggestions for.
`options`	`object`	❌	Options object that allow you to control the search suggestions response
↳ `options.devMode`	`boolean`	❌	If `dev_mode` is set to `true`, a static list of search suggestions will be returned. This is useful when not enough event data is available but when in development, you still want to get a response.

Returns

A Promise resolving to the array below:

string[];