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.
Get category and landing page results from Zoovu for visual merchandising
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>'});
// Returns the Zoovu search response for a category or landing page
xg.search.getVisualMerchandisingResults({ projectId: 12345, categoryPath: ['Shoes', 'Running'] });getResults
getResults
Description: Gets recommendation results by a single search experience id.
Parameters
Name | Type | Required | Description |
|
| ✅ | The ID of the element |
|
| ✅ | Options object that allows you to control the search result response |
↳ |
| ✅ | Collection to get items from |
↳ |
| ✅ | The deploymentId to get search results for |
↳ |
| ❌ | The locale used for tracking (it is recommended to provide this globally when initializing the |
↳ |
| ❌ | The page of results |
↳ |
| ❌ | The number of results per page (max is 120). Default is 60. |
↳ |
| ❌ | If facets is passed as |
↳ |
| ❌ | If deep search should be forced. Useful for Type to Search. |
↳ |
| ❌ | Sort by price or update date |
↳ |
| ❌ | Sort order |
↳ |
| ❌ | Context object used for dynamic filtering |
↳ |
| ❌ | The url used for tracking purposes. This will be passed by default in the browser. |
↳ |
| ❌ | The referrer used for tracking purposes. This will be passed by default in the browser. |
|
| ❌ (defaults to | Can turn off auto tracking of |
|
| ❌ | 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 to get items from |
|
| ❌ | 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 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 to get items from |
|
| ✅ | The query to get suggestions for. |
|
| ❌ | Options object that allow you to control the search suggestions response |
↳ |
| ❌ | If |
Returns
A Promise resolving to the array below:
string[];getVisualMerchandisingResults
getVisualMerchandisingResults
Description: Returns product listings for a category page or landing page from Zoovu category navigation, for visual merchandising. The SDK calls Zoovu's public search endpoint (GET https://api.search.zoovu.com/search) directly and builds the navigational query for you. No XGen key, secret, or access token is sent to Zoovu. This method does not auto-track. Call xg.track.categoryView yourself if you need it.
// Category page by path. A `#` inside a name is escaped for you ("Catalog #1" → "Catalog \#1")
xg.search.getVisualMerchandisingResults({
projectId: 12345,
categoryPath: ['Catalog #1', 'Shoes', 'Running'],
});
// Category page by leaf concept id (keeps working if display names change)
xg.search.getVisualMerchandisingResults({ projectId: 12345, conceptIdName: 'running_shoes' });
// Landing page: omit the category and constrain results with pre-set filters
xg.search.getVisualMerchandisingResults({
projectId: 12345,
options: {
preSetFilters: [{ conceptIdName: 'BRAND', values: ['Acme'] }],
},
});
// Paging: second page of 24
xg.search.getVisualMerchandisingResults({
projectId: 12345,
categoryPath: ['Shoes'],
options: { offset: 24, limit: 24 },
});
// Server-side (SSR / Node): forward the shopper's IP
xg.search.getVisualMerchandisingResults({
projectId: 12345,
categoryPath: ['Shoes'],
options: { clientIp: req.ip },
});Notes:
projectIdis your Zoovu project id. It is required and must be a number. An id read from an environment variable as a string is rejected.Pass
categoryPathorconceptIdName, never both. Pass neither for a landing page.Options use the same names as Zoovu's search API docs, so you can follow Zoovu's documentation directly. Pass JSON-valued options (
filters,preSetFilters,sortComplex,includeTags,includeContentGroups,excludeContentGroups,activeGuidedQuestions) as plain objects or arrays, and the SDK serializes them. See filters and sorting for their syntax.A session id is taken from the auth store automatically, and the same session is shared with your other XGen calls. Pass
options.sessionIdto override it. The auth store is left untouched when you do.Server-side callers should pass
options.clientIp. It is sent as theHTTP_CLIENT_IPheader, which Zoovu's per-IP rate limiting depends on. Some proxies (nginx, by default) drop header names that contain underscores. Omit it in the browser.Invalid input rejects with an
ErrorprefixedgetVisualMerchandisingResults:before any request is sent. Examples:limitabove 1000, an emptyrelationIds,relationIdswithoutrelationIdentifier, or amaskTypethat isn't one of the uppercase values below.A non-2xx Zoovu response rejects with
XGenClientResponseError.queryIdcancellation and thebeforeSend/afterSendhooks work as they do for other methods. Your hooks will see the Zoovu URL.
Parameters
Name | Type | Required | Description |
|---|---|---|---|
|
| ✅ | Zoovu project id (positive integer) |
|
| ❌ | Category names from root to leaf. Can't be combined with |
|
| ❌ | Leaf category concept id. Can't be combined with |
|
| ❌ | Optional Zoovu search params |
↳ |
| ❌ | Result offset (integer ≥ 0) |
↳ |
| ❌ | Page size (integer, 0–1000) |
↳ |
| ❌ | Overrides the auth store session id |
↳ |
| ❌ | Shopper IP, sent as the |
↳ |
| ❌ | User group for group-specific rules |
↳ |
| ❌ | Limits results to one Data Platform catalog (positive integer) |
↳ |
| ❌ | Search Studio sorting option name |
↳ |
| ❌ | Structured sorting. |
↳ |
| ❌ | Shopper-visible filters |
↳ |
| ❌ | Server-side filters hidden from the shopper (landing pages) |
↳ |
| ❌ | Content groups to include |
↳ |
| ❌ | Content groups to exclude |
↳ |
| ❌ | Relation tags to resolve on each product |
↳ |
| ❌ | Product to anchor relations to. Requires |
↳ |
| ❌ | Non-empty list of relation ids (sent comma-separated). Requires |
↳ |
| ❌ | Relation tag. Requires |
↳ |
| ❌ | AI Guided Questions selections |
↳ |
| ❌ | Toggles autocorrect |
↳ |
| ❌ | Toggles query term highlighting |
↳ |
| ❌ | Tag to separate analytics traffic |
↳ |
| ❌ | Response mask type (case-sensitive) |
↳ |
| ❌ | Shopper device |
|
| ❌ | Optional queryId passed to cancel a request |
Returns
A Promise resolving to the raw Zoovu search response below (ZoovuSearchResponse). It is not mapped to the XGen result shape returned by getResults.
{
searchResults: Record<string, unknown>[];
totalResults: number;
showAllResults: boolean;
offset: number;
limit: number;
interpretedQuery: unknown;
relatedQueries: unknown[];
suggestedFilters: Record<string, unknown>[] | null;
answerText: string | null;
matchedIntentId: unknown;
activeSortingOption: unknown;
sortingOptions: Record<string, unknown>[];
activeRanking: unknown;
activeFilterOptions: Record<string, unknown>[];
activePreSetFilterOptions: Record<string, unknown>[];
filterGroups: Record<string, unknown>[];
filterOptions: Record<string, unknown>[];
filterMapping: Record<string, unknown>;
activeGuidedQuestions: Record<string, unknown>[];
guidedQuestion: unknown;
banner: Record<string, unknown> | null;
}