--- title: "XSearch Service" slug: "xsearch-services" updated: 2026-11-02T16:10:21Z published: 2026-11-02T16:10:21Z canonical: "docs.xgen.ai/xsearch-services" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.xgen.ai/llms.txt > Use this file to discover all available pages before exploring further. # XSearch Service 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 ```javascript // Returns a search response containing the results xg.search.getResults({query: 'coat', options: {collection: '', deploymentId:''}}); // Returns a list of property values for the given collection xg.search.getResultValues({collection: ''}); // Returns a list of trending search terms for the given collection xg.search.getTrendingSearches({collection: ''}); // Returns a list of search suggestions from the given collection xg.search.getSearchSuggestions({collection: '', 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: ```typescript {  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: ```typescript {  [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: ```typescript 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: ```typescript 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](https://docs.zoovu.com/api/guides/platform/navigational-queries) 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. ```javascript // 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](https://docs.zoovu.com/api/platform-api/search-products-and-content-get), 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](https://docs.zoovu.com/api/guides/platform/filters-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`. ```typescript { searchResults: Record[]; totalResults: number; showAllResults: boolean; offset: number; limit: number; interpretedQuery: unknown; relatedQueries: unknown[]; suggestedFilters: Record[] | null; answerText: string | null; matchedIntentId: unknown; activeSortingOption: unknown; sortingOptions: Record[]; activeRanking: unknown; activeFilterOptions: Record[]; activePreSetFilterOptions: Record[]; filterGroups: Record[]; filterOptions: Record[]; filterMapping: Record; activeGuidedQuestions: Record[]; guidedQuestion: unknown; banner: Record | null; } ``` ---