This guide instructs you on migrating custom search integrations from the legacy autocomplete endpoint to the supported Tweakwise suggestion endpoints. The legacy autocomplete endpoint is deprecated, making it necessary to transition custom implementations to maintain long-term compatibility, improved performance, and access to rich suggestion features.
This document answers the following key technical question: How do you replace deprecated autocomplete API calls with supported Tweakwise suggestion endpoints in custom search integrations?
Migration involves three sequential steps:
- Updating API Endpoints and Request Parameters
- Parsing Grouped Suggestion Responses
- Implementing Request Throttling and State Management
Instruction and Implementation
Step 1: Updating API Endpoints and Request Parameters
Replace all direct network requests to the deprecated autocomplete API with queries to the Tweakwise suggestion endpoints. For full endpoint specifications and request schemas, consult the Tweakwise API Reference.
When building your request:
- Pass the search query parameter entered by the user.
- Ensure all requests target the active endpoint URLs documented in the Tweakwise API Reference.
Step 2: Parsing Grouped Suggestion Responses
Unlike basic autocomplete calls, suggestion endpoints return categorized groups to give shoppers actionable results as they type. Update your API response handler to process the following suggestion types:
- Search Phrase Suggestions: Render search term recommendations that navigate to the main search result page when clicked.
- Category Suggestions: Display matching category items that route directly to specific category pages.
- Facet Suggestions: Show filtered dynamic facet options that navigate directly to pre-filtered search or category views.
- Product Suggestions: Render preview cards for specific products that link directly to product detail pages.
- Other Content Suggestions: Display blogs, articles, and other relevant content that link directly to their respective pages.
Step 3: Implementing Request Throttling and State Management
To deliver a responsive user experience and avoid unnecessary API overhead, apply input optimization techniques in your custom search component:
- Input Debouncing: Debounce input events (e.g., 250 ms) so requests are sent only after the user stops typing.
- Request Cancellation: Abort in-flight requests using an AbortController or signal mechanism when new keypresses occur to ensure only the latest request updates the UI.
- Zero-State Suggestions: Store recent search terms in local storage to display when a user focuses an empty search input, or fall back to popular search terms when no history exists.
Notes and Important Considerations
- Deprecation Scope: The legacy autocomplete endpoint is formally deprecated and will not receive new functionality or algorithm updates. You should complete this migration to ensure continuous service availability.
- Stale Response Handling: Failing to cancel running in-flight requests can lead to race conditions where slower response payloads overwrite newer search results.
- Router Consistency: Ensure suggestion URLs match your storefront routing structure so users are directed seamlessly to category or product pages.
FAQ
How do I check full endpoint definitions for Tweakwise suggestion endpoints?
You can review complete request parameters, schemas, and response formats at the Tweakwise API Reference.
What happens if I do not migrate away from the legacy autocomplete endpoint?
Because the legacy endpoint is deprecated, custom search integrations relying on it risk future service interruption and will miss out on updated search features, dynamic facet suggestions, and performance enhancements.
Where should users be directed when selecting different suggestion items?
Search phrase suggestions should route to your search page with the query in state, category suggestions should navigate directly to the specific category page, and product suggestions should open the corresponding product detail page.