Best Practices
Follow these guidelines to ensure optimal performance and relevance when integrating Luigi's Box Search.
1. Always Filter by Main Type
Do: explicitely request the main content type you want to search.
Why: The API indexes everything (products, categories, queries). Without a filter, you'll get mixed results.
Incorrect:
q=ukulele (Returns products, brands, and categories mixed together)
Correct:
q=ukulele&f[]=type:product
2. Use quicksearch_types for Universal Search
Do: Use quicksearch_types to fetch secondary results (e.g., matching brands or categories) in the same request as products.
Why: It reduces HTTP requests and latency.
Example Request:
f[]=type:product&quicksearch_types=category,brand&q=ukulele
3. Limit Payload Size (hit_fields)
Do: Request only the fields you need for the search results card (e.g., title, image, price, url).
Why: Default responses include all indexed attributes. Limiting fields can reduce payload size by 4x-5x, significantly improving mobile performance.
Example:
hit_fields=title,image_link,price_amount,url
4. Use Pagination Efficiently
Do: Request a small initial size (e.g., 10-24) and load more pages as needed.
Why: Large page sizes increase server processing time and transfer time.
See pagination parameters in the reference.
5. Be Careful with Explicit Sorting
Caution: Using the sort parameter overrides our AI ranking algorithms.
Consequence: When you sort by "Price Ascending", you lose the relevance ranking. Users might see cheap accessories (pick, string) instead of the actual instrument (guitar) they searched for.
Explicit sorting also affects quicksearch_types. Since secondary results are inferred from the top hits, sorting by price might push relevant brands/categories out of the 'quicksearch' scope.
6. Use Dynamic Facets
Do: Use dynamic_facets_size instead of hardcoding facets.
Why: The AI automatically selects relevant filters for each query (e.g., "Lens Type" for cameras vs. "Fabric" for shirts), providing a better UX without manual configuration.