Method Signature getVoiceSearchResults ( query : string , parameters ?: Omit < SearchParameters , 'filters' | 'sortBy' | 'sortOrder' > , networkParameters ?: NetworkParameters ): Promise < SearchResponse >
Retrieve search results for natural language voice queries. This method uses Constructor.io’s natural language processing to interpret conversational queries like “show me lipstick” or “find red dresses under $50”.
Voice search does not support filters, sortBy, or sortOrder parameters as these are interpreted from the natural language query itself.
Parameters query The natural language search query. Can be conversational (e.g., “show me red dresses”, “find affordable laptops”).
parameters Optional parameters to refine the result set. Note that filtering and sorting are handled through natural language processing. 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.
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 natural language processing. 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.
networkParameters Parameters relevant to the network request. Request timeout in milliseconds.
Response Returns a Promise that resolves to a SearchResponse object. The response structure is identical to getSearchResults .
The processed request parameters sent to the API. The natural language query term.
The page number requested.
Number of results per page.
The search results and metadata, or redirect information. Array of product results matching the natural language query. Product metadata including id, url, image_url, and custom fields.
Array of terms extracted from the natural language query 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.
Array of product groups/categories.
Total number of matching results across all pages.
Available sorting options.
Information about how results were matched.
Active personalization and optimization features.
Additional curated content for this search.
Redirect information if a redirect rule is triggered.
Unique identifier for this search request. Used for tracking and analytics.
Examples Basic Voice Search const results = await constructorio . search . getVoiceSearchResults ( 'show me lipstick' ); console . log ( results . response . total_num_results ); console . log ( results . response . results );
Conversational Query with Price const results = await constructorio . search . getVoiceSearchResults ( 'find red dresses under fifty dollars' ); // Natural language processing automatically extracts: // - Product type: dresses // - Color filter: red // - Price filter: < $50
const results = await constructorio . search . getVoiceSearchResults ( 'show me affordable laptops' , { page: 1 , resultsPerPage: 20 } );
Voice Search with Section const results = await constructorio . search . getVoiceSearchResults ( 'find running shoes for women' , { section: 'Athletic Wear' } );
Voice Search with Hidden Fields const results = await constructorio . search . getVoiceSearchResults ( 'show me wireless headphones' , { hiddenFields: [ 'inventory_count' , 'supplier_id' ], fmtOptions: { show_hidden_fields: true } } ); // Access hidden fields in results results . response . results . forEach ( result => { console . log ( `Stock: ${ result . data . inventory_count } ` ); });
Voice Search with Pre-Filter Expression // Search within a specific collection using natural language const results = await constructorio . search . getVoiceSearchResults ( 'show me blue shirts' , { preFilterExpression: { name: 'collection' , value: 'new-arrivals' } } );
Voice Search with Variations Mapping const results = await constructorio . search . getVoiceSearchResults ( 'find sneakers' , { variationsMap: { group_by: [ { name: 'style' , field: 'style_id' } ], values: { price: { aggregation: 'min' , field: 'price' }, sizes: { aggregation: 'all' , field: 'size' } }, dtype: 'object' } } );
Voice Search with Timeout try { const results = await constructorio . search . getVoiceSearchResults ( 'show me smart watches' , {}, { timeout: 5000 } ); } catch ( error ) { console . error ( 'Voice search timed out:' , error ); }
Handling Redirects const response = await constructorio . search . getVoiceSearchResults ( 'show me clearance items' ); if ( response . response . redirect ) { // Redirect rule was triggered window . location . href = response . response . redirect . data . url ; } else { // Normal search results displayResults ( response . response . results ); }
Natural Language Processing Voice search automatically extracts and applies:
Product types - “show me dresses”Colors - “red shoes”, “blue shirts”Sizes - “medium t-shirts”, “size 10 shoes”Price ranges - “under 50 " , " b e t w e e n 50", "between 50" , " b e tw ee n Materials - “cotton sweaters”, “leather jackets”Brands - “Nike shoes”, “Apple products”Qualifiers - “affordable”, “premium”, “best”
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 . getVoiceSearchResults ( 'show me laptops' ); } catch ( error ) { if ( error . message === 'query is a required parameter of type string' ) { console . error ( 'Invalid query parameter' ); } else { console . error ( 'Voice search failed:' , error ); } }
Use Cases Voice Assistants // Integrate with voice assistant platforms voiceAssistant . onSpeech ( async ( transcript ) => { const results = await constructorio . search . getVoiceSearchResults ( transcript ); speakResults ( results . response . results . slice ( 0 , 3 )); });
Mobile Apps // Voice search button in mobile app const handleVoiceSearch = async ( voiceInput ) => { const results = await constructorio . search . getVoiceSearchResults ( voiceInput ); if ( results . response . total_num_results === 0 ) { showMessage ( 'No results found. Try rephrasing your query.' ); } else { displayResults ( results . response . results ); } };
Accessibility Features // Voice search for users with accessibility needs const enableVoiceSearch = () => { const recognition = new webkitSpeechRecognition (); recognition . onresult = async ( event ) => { const transcript = event . results [ 0 ][ 0 ]. transcript ; const results = await constructorio . search . getVoiceSearchResults ( transcript ); announceResults ( results . response . total_num_results ); displayResults ( results . response . results ); }; recognition . start (); };
Differences from getSearchResults Feature getSearchResults getVoiceSearchResults Query format Keywords Natural language Filters Manual via filters param Extracted from query Sorting Manual via sortBy/sortOrder Interpreted from query Use case Traditional search Voice interfaces API endpoint /search/search/natural_language
See Also 