Method Signature getSearchResults ( query : string , parameters ?: SearchParameters , networkParameters ?: NetworkParameters ): Promise < SearchResponse >
Retrieve search results for a text query with support for filtering, sorting, pagination, and faceting.
Parameters query The search term to query. Must be a non-empty string.
parameters Optional parameters to refine the result set. The page number of results to return. Cannot be used together with offset. Zero-indexed.
The number of results to skip from the beginning. Cannot be used together with page.
The number of results per page to return. Default varies by account configuration.
Key-value mapping of filters to refine results. Keys are facet names, values can be strings or arrays. Example: { size: 'medium', color: ['red', 'blue'] }
sortBy
string
default: "relevance"
The field to sort results by (e.g., 'relevance', 'price').
sortOrder
string
default: "descending"
The sort order for results. Valid values: 'ascending' or 'descending'.
The section name for results. Typically used to separate different content types.
Format options to refine result groups and data structure. Maximum depth for group hierarchies.
Where to start in the group hierarchy: 'current', 'top', or 'group_id:ID'.
Array of hidden metadata fields to return in results.
Whether to include hidden fields in the response.
How to return variations: 'default', 'all', or 'matched'.
See the Constructor.io API documentation for full details. Faceting expression to scope search results before applying other filters. Useful for creating collections or categories. See Collections documentation for expression syntax. Array of hidden metadata field names to return in result data.
Array of hidden facet names to return in the facets list.
Configuration for aggregating product variations. Array of objects specifying how to group variations: [{ name: string , field: string }]
Object mapping field names to aggregation strategies: { [ key : string ]: { aggregation: 'first' | 'min' | 'max' | 'all' , field: string } }
Data type for variations: 'array' or 'object'.
See Variations Mapping documentation for details. Alternative way to pass parameters as a serialized JSON object. Parameters can be passed either directly or through this field.
Specifies how results should match filters. Keys are filter names, values are 'all', 'any', or 'none'. Example: { size: 'all', color: 'any' } means results must match all size filters but can match any color filter.
networkParameters Parameters relevant to the network request. Request timeout in milliseconds.
Response Returns a Promise that resolves to a SearchResponse object.
The processed request parameters sent to the API. The page number requested.
Number of results per page.
The search results and metadata, or redirect information. Array of product results. Product metadata including id, url, image_url, and custom fields.
Array of search terms that matched this result.
Whether the result is a slotted/sponsored item.
Labels applied to this result.
Array of product variations if variations mapping is used.
Unique identifier for tracking (automatically appended by the SDK).
Array of available facets for filtering. Human-readable facet name.
Facet type: 'multiple', 'single', 'range', or 'hierarchical'.
Available facet values (for option facets).
Minimum value (for range facets).
Maximum value (for range facets).
Whether this facet is hidden by default.
Array of product groups/categories.
Total number of matching results across all pages.
Available sorting options. Current status of this option.
Information about how results were matched (token vs. embeddings).
Active personalization and optimization features.
Additional curated content for this search.
Redirect information if a redirect rule is triggered. When present, the response contains redirect data instead of results. Redirect metadata including url, rule_id, and match_id.
Terms that triggered the redirect.
Unique identifier for this search request. Used for tracking and analytics. This is automatically appended to each result item in the results array.
Examples Basic Search const results = await constructorio . search . getSearchResults ( 'laptop' ); console . log ( results . response . total_num_results ); console . log ( results . response . results );
const results = await constructorio . search . getSearchResults ( 'shoes' , { page: 2 , resultsPerPage: 24 });
Search with Filters const results = await constructorio . search . getSearchResults ( 't-shirt' , { resultsPerPage: 40 , filters: { size: 'medium' , color: [ 'red' , 'blue' ] }, filterMatchTypes: { size: 'all' , color: 'any' } });
Search with Sorting const results = await constructorio . search . getSearchResults ( 'laptop' , { sortBy: 'price' , sortOrder: 'ascending' , filters: { brand: 'Apple' } });
Search with Variations Mapping const results = await constructorio . search . getSearchResults ( 'shoes' , { variationsMap: { group_by: [ { name: 'style' , field: 'style_id' } ], values: { price: { aggregation: 'min' , field: 'price' }, color: { aggregation: 'all' , field: 'color' } }, dtype: 'object' } });
Search with Pre-Filter Expression // Only search within a specific collection const results = await constructorio . search . getSearchResults ( 'dress' , { preFilterExpression: { and: [ { name: 'collection' , value: 'summer-2024' }, { name: 'price' , range: [ 0 , 100 ] } ] } });
Search with Hidden Fields const results = await constructorio . search . getSearchResults ( 'phone' , { hiddenFields: [ 'internal_id' , 'warehouse_location' ], hiddenFacets: [ 'supplier' ] }); // Access hidden fields in results results . response . results . forEach ( result => { console . log ( result . data . internal_id ); });
Search with Timeout try { const results = await constructorio . search . getSearchResults ( 'laptop' , {}, { timeout: 5000 // 5 seconds }); } catch ( error ) { console . error ( 'Search timed out:' , error ); }
Handling Redirects const response = await constructorio . search . getSearchResults ( 'sale' ); if ( response . response . redirect ) { // Redirect rule was triggered window . location . href = response . response . redirect . data . url ; } else { // Normal search results displayResults ( response . response . results ); }
Error Handling The method throws an error if:
query is not provided or is not a stringNetwork request fails
Response data is malformed
try { const results = await constructorio . search . getSearchResults ( 'laptop' ); } catch ( error ) { if ( error . message === 'query is a required parameter of type string' ) { console . error ( 'Invalid query parameter' ); } else { console . error ( 'Search failed:' , error ); } }
See Also 