Autocomplete API

Use the autocomplete API endpoint to get a search-as-you-type functionality.

To use this feature, you need to synchronize your product database with Luigi's Box search index. See Indexing the data for more details.

Luigi's Box Autocomplete can learn the best results ordering. In order to enable learning, you need to integrate Luigi's Box Search Analytics service with your website by following the instructions.

We strongly recommend that you do not implement the JSON API directly, but instead use our integrated Autocomplete.js library which allows you to build an autocomplete widget with minimum programming effort.

The autocomplete endpoint is publicly available and requires no authentication.

Get autocomplete results

GET https://live.luigisbox.com/autocomplete/v2

Required parameters


`tracker_id`	Identifier of your site within Luigi's Box. You can see this identifier in every URL in the Luigi's Box app once you are logged-in.
`q`	User input
`type`	Comma separated list of required types and their quantity, e.g. `item:6,category:3`

Optional parameters


`user_id`optional	If supplied and is equal to user id collected in analytics, it can drive personalization of results. In case you use identifiers of logged in users (`customer_id` in analytics), please put the ID of logged in user here and fill in parameter `client_id` as well.
`client_id`optional	Set this parameter to `client_id` (sent in analytics) in case you store identifier of logged in user into `user_id`.
`f_type[]`optional	Filter, where `type` part of the parameter name is a name of a requested type. The value itself is using key:value syntax. E.g., use `f_item[]=color:green` to filter hits of type `item` which have an attribute `color` with a value `green`. You can use several filters in one request, e.g., `f_item[]=color:green` together with `f_brand[]=promoted:true`. Filtering on top of numerical and date attributes supports ranges, using pipe as a separator, e.g., `f_item[]=price:5\|7`. This range can be left open from either side, e.g., `f_item[]=price:6\|`. If a combination of filters for the same field is provided, they are applied with `OR`. E.g., filters `f_item[]=color:green&f_item[]=color:blue` will retrieve products, that have either `green` OR `blue` color.
`sort_type`optional	Sort, where `type` part of the parameter name is a name of a requested type. The value itself is using key:value syntax. E.g., use `sort_item=price_amount:asc` to sort hits of type `item` by their price in ascending order. You can use several sorts in one request, e.g., `sort_item=price_amount:asc` together with `sort_article=introduced_at:desc`.
`prefer[]`optional	Allows preferation of products. It uses `key:value` syntax e.g., `prefer[]=category:Gadgets` to prefer hits according to chosen criteria. Results matching the specified attribute and its value will be sorted higher. Note that unlike `f_type`, the `prefer` is applied to all requested types. See Query-time boosting for more details.
`hit_fields`optional	A comma separated list of attributes and product parameters. Only these fields (in addition to some default ones) will be retrieved and present in results. If not provided, all fields will be present in results. The use of this feature is recommended. Try to specify only those field that are necessary for the frontent of the autocomplete window. This can help the retrieval of the results to be faster.
`context`optional	Refer to context in search for explanation and Multi-warehouse solution for a use-case scenario.
`ctx[]`optional	drives model selection, using key:value syntax e.g., `ctx[]=warehouse:berlin`. you can provide multiple `key:value` pairs, that are combined into one context definition. order of `key:value` pairs in request is not important. however, please note that `key:value` pairs must match one of the contexts which are being reported into luigi's box search analytics. see the multi-warehouse solution and context in analytics for more details.

Request Headers

Consider sending request header of Accept-Encoding as well with values for supported encoding methods of your HTTP client, e.g. gzip or br, gzip, deflate for multiple supported methods. Encodings make the response from autocomplete endpoint considerably smaller and thus faster to transfer.

Example request

Note that this endpoint is cached internally and it may take some time (in the order of minutes) for changes to underlying data to propagate.

To invoke the endpoint, use this code (the simplest example):

require 'faraday'
require 'faraday_middleware'
require 'json'

connection = Faraday.new(url: 'https://live.luigisbox.com') do |conn|
  conn.use FaradayMiddleware::Gzip
end

response = connection.get("/autocomplete/v2?q=harry+potter&tracker_id=1234-5678&type=item:5")

if response.success?
  puts JSON.pretty_generate(JSON.parse(response.body))
else
  puts "Error, HTTP status #{response.status}"
  puts response.body
end

#!/bin/bash

curl -i -XGET --compressed\
  "https://live.luigisbox.com/autocomplete/v2?q=harry+potter&tracker_id=1234-5678&type=item:5"\

<?php

// Using Guzzle (http://guzzle.readthedocs.io/en/latest/overview.html#installation)
require 'GuzzleHttp/autoload.php';


$client = new GuzzleHttp\Client();
$res = $client->request('GET', "https://live.luigisbox.com/autocomplete/v2?q=harry+potter&tracker_id=1234-5678&type=item:5", [
  'headers' => [
    'Accept-Encoding' => 'gzip'
  ]
]);

echo $res->getStatusCode();
echo $res->getBody();

// This endpoint requires no authentication

// This endpoint requires no body

The above command returns a JSON structured like this. The exact content of attributes field depends on the content of your product catalog.

json

{
    "exact_match_hits_count": 6,
    "partial_match_hits_count": 0,
    "partial_match_terms": [],
    "hits": [
        {
            "url": "http://www.e-shop.com/products/123456",
            "attributes": {
                "image_link": "http://www.e-shop.com/assets/imgs/products/123456.jpg",
                "description": "Description field from your product catalog",
                "categories": [
                    "Gadgets",
                    "Kids"
                ],
                "title": "<em>Product</em> X",
                "title.untouched": "Product X",
                "availability_rank_text": "true",
                "price": "5.52 EUR",
                "condition": "new"
            },
            "type": "item",
            "updated_at": "2017-11-23T00:00:00+00:00"
        },
        {
            "url": "http://www.e-shop.com/products/456789",
            "attributes": {
                "image_link": "http://www.e-shop.com/assets/imgs/products/456789.jpg",
                "description": "Description field from your product catalog",
                "categories": [
                    "Gadgets",
                    "Kids"
                ],
                "title": "Product Y",
                "title.untouched": "<em>Product</em> Y",
                "availability_rank_text": "preorder",
                "price": "12.14 EUR",
                "condition": "new"
            },
            "type": "item",
            "updated_at": "2017-11-23T00:00:00+00:00"
        }
    ],
    "campaigns": [
        {
            "id": 9,
            "target_url": "https://www.e-shop.com/harry-potter",
            "banners": {
                "autocomplete_list": {
                    "desktop_url": "https://www.e-shop.com/harry-potter-1.jpg",
                    "mobile_url": "https://www.e-shop.com/harry-potter-2.jpg"
                }
            }
        },
        {
            "id": 12,
            "target_url": "https://www.e-shop.com/rowling",
            "banners": {
                "autocomplete_top": {
                    "desktop_url": "https://www.e-shop.com/rowling-1.jpg",
                    "mobile_url": "https://www.e-shop.com/rowling-2.jpg"
                }
            }
        }
    ],
    "suggested_url": "http://www.e-shop.com/special_landing_site/HP?lb_redirected_from=harry+potter"
}

Integration with other Luigi's Box services

Fixits

Autocomplete endpoint integrates the "fixit" rules that you can set up in the application.

The endpoint will also return a URL of a Fixit redirect if such a rule for this query exists. Look for suggested_url in response. The entered search query must be an exact match with a query set in the Fixit rule for the suggested_url to appear in the response.

On seeing the suggested_url in the response, you may want to redirect the user directly to this URL instead of submitting the autocomplete query to search.

Banners

Autocomplete API response will include data related to banner campaigns set up in the application. Refer to the Banner campaigns documentation for more details.

Query rewrite

Query rewrite is a way to control your search and autocomplete results. You can set up query rewrites in Luigi's Box application and they will have an effect on autocomplete and search results.

If you are using search.js then query rewrite will work out of the box and no integration is necessary on your side.

If you are using API to build search, then you must adapt your code to incorporate some functionality of query rewrite.

Each query rewrite has exactly one search query it responds to (diacritics and case do not matter). You can choose if you want to rewrite query, or keep the original one. You can also define filters, which will be applied to your search requests for given query.

When creating query rewrite, you can choose if you want to admit to the customer, that you have rewritten the original query. You can also define a message, which will be shown in case of applying query rewrite.

json

{
  "query_rewrite": {
        "id": 9,
        "original_query": "mini guitar",
        "admit_rewrite": true,
        "message": "We rewrote your entered query to another with better search results for you."
    }
}

Sample requests

The requests below use the sample Luigi's Box data. You will have to adapt the examples to your specific situation and adapt:

The tracker_id parameter
The type names

Get autocomplete results for several types in a single request

This is the most basic request where you only provide the query and request the types.

GET https://live.luigisbox.com/autocomplete/v2?tracker_id=179075-204259&type=product:7,query:6,category:6&q=ukulele

Try it live →

Limit results based on a specific attribute

The request below will only return results from the "Ukulele straps" category. This is a slightly contrived example but you may use to filter for gender, warehouse or other use cases.

GET https://live.luigisbox.com/autocomplete/v2?tracker_id=179075-204259&type=product:7,query:6,category:6&q=ukulele&f_product[]=category:Ukulele+Straps

Try it live →

Limit fields

To achieve better performance, list the fields that you need in the response in hit_fields.

GET https://live.luigisbox.com/autocomplete/v2?tracker_id=179075-204259&type=product:7,query:6,category:6&q=ukulele&hit_fields=title,category,images

Try it live →

Best practices

Avoid proxying requests

If you choose to implement the JSON API, we recommend that you consume it on the frontend side, i.e., directly from the HTML page. This API was designed for this use case and no sensitive information is required to call it (e.g., your private key). Do not proxy calls to Luigi's Box Autocomplete API via your backend servers as this will introduce additional latency.

Prefetch DNS

We recommend that you add DNS prefetch instruction to your HTML code to avoid the DNS lookup penalty on the first autocomplete request. Add the following code anywhere to your <head> to instruct browser to do the DNS lookup in advance.

<link rel="dns-prefetch" href="//live.luigisbox.com">

Fetch only the fields you will use

To avoid a performance penalty, only request the fields that you will use. Use hit_fields parameter to list the fields.