↑↓ selectEnter openEsc close

    1. Elbuz

    Smart search API: how to get results into your own site or app

    2 min readUpdated

    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 facets parameter adds them.
    • Your site's code must open the search window with a query — use the window.SmartSearch object.
    • 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

    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.

    ParameterValue
    Base URLhttps://widget-ess.elbuz.com/api/v1
    Authenticationthe X-Api-Key header with your site's key (this is the account )
    MethodGET for reading, POST for events
    Limit100 requests per minute per key; what's left is shown in the X-RateLimit-Remaining and X-RateLimit-Reset headers
    FormatJSON: success, data, meta.execution_time_ms; on error — success: false and a code

    What routes the API has

    RouteWhat for
    GET /products/searchproduct search: q, limit, page, sort, category_id, filters, lang
    GET /suggestlightweight autocomplete for the search box
    GET /products/{id}product card with reviews
    GET /products?ids=1,2,3several products from a list of IDs
    GET /categories, /categories/{id}, /categories/{id}/filterscategory tree and available filters
    GET /popular/queries, /popular/products, /popular/categoriespopular items for a period
    POST /eventssend 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.

    MethodWhat 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 seeWhyWhat to do
    The API returns 401the X-Api-Key header is missing or the key is wrongtake the key from the API block in the widget card
    The API returns 429more than 100 requests per minutewait for the window to reset; check X-RateLimit-Reset
    The response has fewer products than total_foundthis is expected: it is the total number of matches, not the page sizepage 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

    Was this article helpful?

    Missing a feature? Tell us.

    We will add it for free if other users need it too.

    If only you need it, we will agree on it separately.

    Article contents

    Suggest an improvement

    Try Elbuz free