TURBO for Developers

Home > widget-integration > InstantSearchAPI

InstantSearchAPI class

API service for instant search operations.

Technical Support teams can extend this service for custom API behavior:

Signature:

export declare class InstantSearchAPI extends BoostAPI

Extends: BoostAPI

Example

window.boostWidgetIntegration.extend('InstantSearchAPI', (InstantSearchAPI) => {
  return class CustomInstantSearchAPI extends InstantSearchAPI {
    // Add custom headers
    protected buildHeaders() {
      return {
        ...super.buildHeaders(),
        'X-Custom-Header': 'value'
      };
    }
  };
});

Constructors

Constructor	Modifiers	Description
(constructor)(platformLoader, appService, b2bService, recentSearchService)		Constructs a new instance of the `InstantSearchAPI` class

Properties

Property	Modifiers	Type	Description
appService	`protected`	AppService
b2bConfig	`protected` `readonly`	{ enabled: boolean; companyLocationId?: string; }	Get B2B configuration.
b2bService	`protected`	B2BService
baseUrl	`protected` `readonly`	string	Get the base search API URL.
debugMode	`protected`	boolean	Enable debug logging
locale	`protected` `readonly`	string	Get the current locale.
platformLoader	`protected`	PlatformLoader
recentSearchService	`protected`	RecentSearchService
searchSettings	`protected` `readonly`	Partial<SearchSettings$1>	Get search settings from app config.
shopDomain	`protected` `readonly`	string	Get the tenant/shop domain.
templateUrl	`protected` `readonly`	string	Get the template API URL.

Methods

Method	Modifiers	Description
buildApiUrl(endpoint)	`protected`	Build API URL for external Boost search service. NOTE: The locale is passed as a query parameter (`&locale=en`) via `addCurrencyParams()` / `addLocalizationParams()`
buildHeaders()	`protected`	Build request headers. Override to add custom headers.
buildQueryParams(params, options)	`protected`	Build query parameters for API requests. Legacy: buildQueryParams() in api/search.js New: Method on API service with better typing Handles: - Array values (appended as multiple params) - Custom params from window.boostSdCustomParams - Customer ID from platform
buildRequestBody(params, options)	`protected`	Build request payload enriched with shared localization, customer, and optional B2B data.
buildRequestParams(params, options)	`protected`	Build query parameters enriched with shared localization, customer, and B2B data.
buildWidgetRequestParams(params, settings, customParams)	`protected`	Build the raw request parameters object for a suggestion API call. Primary extension point for TS teams who need to inject custom search parameters, override default values, or add shop-specific query flags without re-implementing the full `getSuggestions()` method. Called by `getSuggestions()` before `buildQueryParams()` serialises to URL.
enrichWidgetResponse(response)	`protected`	Enrich a suggestion response with shop-specific data. Called by `handleWidgetResponse()`. Override this method to re-rank products, inject promotions, append custom metadata, or pin specific results.
getProductsByHandle(handles, options)		Fetch products by handles. Legacy: getProductsDetailByHandle(context, handle, searchQuery) New: getProductsByHandle(handles, options?) with typed response Features migrated from legacy: - Single or multiple handles support - Product availability filtering - B2B support - POST method for larger payloads
getProductsById(ids, options)		Fetch products by IDs. Legacy: getProductsDetail(context, ids) New: getProductsById(ids, options?) with typed response Features migrated from legacy: - Product availability filtering - B2B support - Locale params
getRedirects(terms)		Fetch redirect mappings for search terms. Legacy: getRedirects(context, terms) New: getRedirects(terms?) with typed response Features migrated from legacy: - Multiple terms support - B2B support - Locale params - Proper response transformation
getSuggestions(params, searchSettings, customParams, signal)		Fetch search suggestions. Legacy: getSuggestionSearch(context, query, customizeSearchParams) New: getSuggestions(params, searchSettings?, customParams?) with typed response Features migrated from legacy: - Timestamp cache busting (t param) - Did-you-mean suggestions (re_run_if_typo) - Suggestion blocks with limits - Recent search integration - Fuzzy search options - Product availability filtering - B2B support - Locale/currency params
getTemplate(templateId)		Fetch ISW template by ID. Legacy: getTemplateByIds() in api/template.js New: getTemplate(templateId) with proper typing Query params must match the legacy format exactly: - `shop` – shop domain - `theme_lib` – theme name lib (NOT `theme`) - `widgets[]` – `name:id` format, bracket suffix required (NOT `ids`, NOT `widgets`) NOTE: This endpoint does NOT accept `customer_id` or custom boost params, so we build URLSearchParams directly instead of using `this.buildQueryParams()`.
handleWidgetResponse(response)	`protected`	Handle a raw suggestion API response before returning it to the service. Delegates to `enrichWidgetResponse()`, giving TS teams a clean hook to intercept and modify results without overriding the entire `getSuggestions()` method.
log(message, data)	`protected`	Log debug messages when debug mode is enabled.
requestJson(url, init)	`protected`	Execute a JSON request with shared error handling.
saveQueryString(query)	`protected`	Save query string to localStorage.
setDebugMode(enabled)		Enable or disable debug mode for API logging.
stripHtml(text)	`protected`	Strip HTML tags from text.

← Back to Library Reference