XSearch Service

Prev Next

The XSearch service provides four main capabilities:

  1. Run a standard search query to retrieve results with full control over pagination, sorting, and filters

  2. Pull all possible property values for a collection to power facets and filter menus

  3. View trending search terms to understand what shoppers are looking for most.

  4. View search suggestions terms for a user’s current query.

  5. 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

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[];

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:

  • projectId is 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 categoryPath or conceptIdName, 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.sessionId to override it. The auth store is left untouched when you do.

  • Server-side callers should pass options.clientIp. It is sent as the HTTP_CLIENT_IP header, 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 Error prefixed getVisualMerchandisingResults: before any request is sent. Examples: limit above 1000, an empty relationIds, relationIds without relationIdentifier, or a maskType that isn't one of the uppercase values below.

  • A non-2xx Zoovu response rejects with XGenClientResponseError. queryId cancellation and the beforeSend / afterSend hooks work as they do for other methods. Your hooks will see the Zoovu URL.

Parameters

Name

Type

Required

Description

projectId

number

✅

Zoovu project id (positive integer)

categoryPath

string[]

❌

Category names from root to leaf. Can't be combined with conceptIdName

conceptIdName

string

❌

Leaf category concept id. Can't be combined with categoryPath

options

object

❌

Optional Zoovu search params

↳ options.offset

number

❌

Result offset (integer ≥ 0)

↳ options.limit

number

❌

Page size (integer, 0–1000)

↳ options.sessionId

string

❌

Overrides the auth store session id

↳ options.clientIp

string

❌

Shopper IP, sent as the HTTP_CLIENT_IP header (server-side only)

↳ options.userGroup

string

❌

User group for group-specific rules

↳ options.catalogId

number

❌

Limits results to one Data Platform catalog (positive integer)

↳ options.sort

string

❌

Search Studio sorting option name

↳ options.sortComplex

{ key, direction } | { conceptIdName, direction } | { rankingStrategyId, type: 'STRATEGY' }

❌

Structured sorting. direction is 'ASC' or 'DESC'

↳ options.filters

object[]

❌

Shopper-visible filters

↳ options.preSetFilters

object[]

❌

Server-side filters hidden from the shopper (landing pages)

↳ options.includeContentGroups

string[]

❌

Content groups to include

↳ options.excludeContentGroups

string[]

❌

Content groups to exclude

↳ options.includeTags

{ tag: string; limitPerRelation?: number }[]

❌

Relation tags to resolve on each product

↳ options.relationIdentifier

string

❌

Product to anchor relations to. Requires relationIds or relationTag

↳ options.relationIds

number[]

❌

Non-empty list of relation ids (sent comma-separated). Requires relationIdentifier

↳ options.relationTag

string

❌

Relation tag. Requires relationIdentifier

↳ options.activeGuidedQuestions

object[]

❌

AI Guided Questions selections

↳ options.autocorrect

boolean

❌

Toggles autocorrect

↳ options.highlightQueryTerms

boolean

❌

Toggles query term highlighting

↳ options.queryTag

string

❌

Tag to separate analytics traffic

↳ options.maskType

'PIM' | 'MINI_PDP' | 'REFINEMENT' | 'ZOE' | 'PASS_ON' | 'PASS_ON_SUGGESTION' | 'ASSISTANT' | 'MCP' | 'RELATIONS'

❌

Response mask type (case-sensitive)

↳ options.device

'mobile' | 'desktop' | 'tablet'

❌

Shopper device

queryId

string

❌

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;
}