Elbuz smart search returns the widget's results through a REST API: your own search page or mobile app gets products, categories, filters and suggestions with your site's key.
When you need this:
- You want your own search page, not the widget — the search route returns products and categories.
- The page must show brands and a price range — the
facetsparameter adds them. - Your site's code must open the search window with a query — use the
window.SmartSearchobject. - Clicks in your own interface must reach analytics — use the events route.
Where to start: get the URL and key in the “API” block of the widget card.
What the search API can do
- Searches with your site's key — 100 requests per minute, responses in .
- Returns products, categories, suggestions and popular items — and accepts events for analytics.
- Adds blocks on request — brands, stock, attributes, price range.
- Controls the search window — opens it, fills in a query, reads the shopper's cart.
How to connect to the API
If you need your own search page or mobile app rather than the ready-made widget, the same service has a . The URL and key are shown in the widget card, in the API block.
| Parameter | Value |
|---|---|
| Base URL | https://widget-ess.elbuz.com/api/v1 |
| Authentication | the X-Api-Key header with your site's key (this is the account ) |
| Method | GET for reading, POST for events |
| Limit | 100 requests per minute per key; what's left is shown in the X-RateLimit-Remaining and X-RateLimit-Reset headers |
| Format | JSON: success, data, meta.execution_time_ms; on error — success: false and a code |
What routes the API has
| Route | What for |
|---|---|
GET /products/search | product search: q, limit, page, sort, category_id, filters, lang |
GET /suggest | lightweight autocomplete for the search box |
GET /products/{id} | product card with reviews |
GET /products?ids=1,2,3 | several products from a list of IDs |
GET /categories, /categories/{id}, /categories/{id}/filters | category tree and available filters |
GET /popular/queries, /popular/products, /popular/categories | popular items for a period |
POST /events | send an event to analytics: a click, an add to cart |
How to get brands, stock and filters
By default, search returns only products and categories — this is the fastest option. Extra blocks are added with the facets parameter, comma-separated:
brands— brands with product counts;stock— stock statuses with counts;attributes— filters by attributes;price_range— minimum and maximum price.
Each facet adds time to the response, so request only what the page actually shows.
curl -H "X-Api-Key: YOUR_SITE_KEY" \
"https://widget-ess.elbuz.com/api/v1/products/search?q=asus&limit=20&facets=brands,price_range&lang=uk"
The response has two different numbers: products_count is how many products are in this response (subject to limit), total_found is how many were found in the database overall. Use the second for pagination and the first to check whether anything came back. Mixing them up is the most common integration mistake.
Sorting can be set in two ways: with a prefix (price — ascending, -price — descending) or with a suffix (price_asc, price_desc). Without the sort parameter, products are ranked by relevance, taking stock into account.
How to control the search window from your site's code
On a page with the widget, the window.SmartSearch object is available: your site's code uses it to open search, fill in a query and read the shopper's lists.
| Method | What it does |
|---|---|
SmartSearch.search('query') | searches and opens the window with results |
SmartSearch.setQuery('query', true, {filters}) | fills the query and filters into the search box; true — search right away |
SmartSearch.openWidget(), closeWidget(), isWidgetOpen() | open or close the window, check whether it is open |
SmartSearch.openCategoryProducts({...}) | show a category's products in the search window |
SmartSearch.clearFilters(), getSelectedFilters() | reset or read the shopper's filters |
SmartSearch.getCart(), getWishlist(), getCompare(), onShoppingDataChange(fn) | the shopper's cart, wishlist and comparison list, and a subscription to their changes |
What to do when the API returns an error
| What you see | Why | What to do |
|---|---|---|
| The API returns 401 | the X-Api-Key header is missing or the key is wrong | take the key from the API block in the widget card |
| The API returns 429 | more than 100 requests per minute | wait for the window to reset; check X-RateLimit-Reset |
The response has fewer products than total_found | this is expected: it is the total number of matches, not the page size | page through results with the page parameter |
FAQ
Where do I get the API key?
In the widget card, in the “API” block: it shows the service URL and your site's key. The key is sent in the X-Api-Key header; the limit is one hundred requests per minute.
Why does search through the API return products without brands and filters?
Because by default only the base layer is returned — products and categories. Brands, stock, attribute filters and the price range are added with the facets parameter; each of them adds time to the response.
How many requests can I make to the API?
100 per minute per key. What's left is shown in the X-RateLimit-Remaining and X-RateLimit-Reset headers; once you exceed it, the API returns 429.
How do I sort results by price?
With the sort parameter: price — ascending, -price — descending, or price_asc / price_desc. Without sort, products are ranked by relevance, taking stock into account.
How do I find out how many products were found in total?
Use total_found — that is all matches in the database. products_count is only the products in this response, subject to limit.
Where it is and who has access
- Menu
- Directories → Categories → the “Widget settings - Smart search” tile, “Settings” tab, “API” block
- Access right
- the “Smart product search widget” window in “Group permissions”
- Prepare
- smart search turned on and the search index built
Related topics
- If you need the big picture — smart search on your website: what it does and where to start.
- If the ready-made search window is enough — how to connect the widget to your site.
- If you need to exchange account data rather than search — Elbuz API.
- If you are choosing search for your site — what it gives your store.
