Autocomplete API V3

Overview

The Autocomplete API provides search-as-you-type functionality. It is designed to return results quickly for incomplete search queries, suggesting items, categories, or other indexed content to the user as they type.

This endpoint supports various features including:

Typo correction: Handle misspelled terms gracefully.
Personalization: Re-rank results based on user history.
Filtering: Restrict suggestions to specific categories or attributes.

Info

Performance Tip: This endpoint is public and requires no authentication. We strongly recommend implementing this directly on the frontend (browser) to minimize latency.

For a detailed comparison of implementation methods, see our Integration Best Practices guide.

Endpoint

GET https://live.luigisbox.tech/v3/autocomplete

Request Parameters (V3)

To request autocomplete results, you must provide your tracker ID and the user's input query.

Info

Note on Caching: This endpoint is cached internally. Changes to your product data (e.g., price updates) may take a few minutes to propagate to Autocomplete results.

Required parameters

Parameter	Type	Required	Description
`tracker_id`	string	✓	Your unique site identifier within Luigi's Box. Found in the dashboard settings.
`q`	string	✓	The partial search query input by the user (e.g., "iph").
`type`	string	✓	Defines the types of objects to return and their counts. Format: `type:count`. Multiple types are comma-separated. Example: `item:6,category:3` requests 6 items and 3 categories.

Optional parameters

Parameter	Type	Description
Identity & Personalization (V3)
`auth_user_id`	string	Logged-in User ID. The unique identifier of a logged-in user. Must match the `customer_id` sent to Analytics. Required for personalization if the user is logged in.
`device_user_id`	string	Anonymous Device ID. The browser/cookie identifier (e.g., the `_lb` cookie value). Used to track anonymous sessions or link them to a logged-in profile.
`personalize`	boolean	Set to `true` to enable personalized re-ranking. Requires `auth_user_id` or valid history linked to `device_user_id`.
Filtering & Sorting
`f_type[]`	string	Filters results of a specific `type`. Format: `f_<type>[]=<field>:<value>`. Exact Match: `f_item[]=color:green` OR Logic: Combine multiple filters. `f_item[]=color:green&f_item[]=color:blue` (Green OR Blue). Ranges: Use the pipe `\|` character. `price:10\|50` (10 to 50) `price:10\|` (10 and up)
`sort_type`	string	Sorts results of a specific `type`. Format: `sort_<type>=<field>:<dir>`. Example: `sort_item=price:asc`.
`prefer[]`	string	Boosts items matching a criteria without strictly filtering them. Format: `prefer[]=<field>:<value>`. Note: Unlike `f_type`, this applies to all requested result types.
Context & Output
`context`	string	Placement Context. Arbitrary string (e.g., "mobile_header", "checkout_page") used to segment analytics data by the source of the query.
`ctx[]`	string	Model Selection. Format: `key:value`. Selects a specific machine learning model trained on a subset of data. Keys must match contexts defined in Analytics. Example: `ctx[]=warehouse:berlin`
`hit_fields`	string	Comma-separated list of fields to retrieve (e.g., `title,url,price`). Tip: Requesting only necessary fields improves API response time.
`non_collapsed_variants`	boolean	If `true`, returns all product variants individually instead of collapsing them into a single parent product. Default is `false`.

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 the JSON API considerably smaller and thus faster to transfer.

Example Request

shell


curl "https://live.luigisbox.tech/v3/autocomplete?tracker_id=YOUR_TRACKER_ID&q=text&type=item:6" \
     -H "Accept-Encoding: gzip, deflate"

How to make a request

The following examples demonstrate how to send a request to the Autocomplete API using various languages.

To make a valid request:

Endpoint: Use https://live.luigisbox.tech/v3/autocomplete.
Parameters: Include your tracker_id, the user's search query q, and the desired type of results (e.g., item:6 for 6 items).
Encoding: Ensure all query parameters are properly URL-encoded.
Headers: Set Accept-Encoding: gzip to reduce data transfer size.

For a comprehensive, step-by-step tutorial on integrating this endpoint into your application, please refer to our Quickstart: Getting query suggestions via the Autocomplete API guide.

Example Code

# --- Ruby Example for GET /v3/autocomplete ---
# Assumes 'faraday' gem is installed (gem install faraday)

require 'faraday'
require 'json'

LUIGISBOX_HOST = 'https://live.luigisbox.tech'
ENDPOINT_PATH = '/v3/autocomplete'
TRACKER_ID = 'your_tracker_id'

connection = Faraday.new(url: LUIGISBOX_HOST) do |conn|
  conn.use FaradayMiddleware::Gzip
end

response = connection.get(ENDPOINT_PATH) do |req|
  req.params['tracker_id'] = TRACKER_ID
  req.params['q'] = 'text'
  req.params['type'] = 'item:6'
  req.headers['Accept-Encoding'] = 'gzip, deflate'
end

if response.success?
  puts "Autocomplete results: " +
       "#{JSON.pretty_generate(JSON.parse(response.body))}"
else
  puts "Error: HTTP Status " +
       "#{response.status}, Response: #{response.body}"
end

<?php
// PHP Example for GET /v3/autocomplete
// Assumes Guzzle is installed: 
// composer require guzzlehttp/guzzle

require 'vendor/autoload.php';

use GuzzleHttp\Client;

$LUIGISBOX_HOST = 'https://live.luigisbox.tech';
$ENDPOINT_PATH = '/v3/autocomplete';
$TRACKER_ID = 'your_tracker_id';

$client = new GuzzleHttp\Client();
$response = $client->request(
    'GET', 
    "{$LUIGISBOX_HOST}{$ENDPOINT_PATH}", 
    [
        'query' => [
            'tracker_id' => $TRACKER_ID,
            'q' => 'text',
            'type' => 'item:6'
        ],
        'headers' => [
            'Accept-Encoding' => 'gzip, deflate'
        ]
    ]
);

if($response->getStatusCode() == 200) {
    echo "Autocomplete results:" . PHP_EOL;
    echo json_encode(json_decode($response->getBody()), JSON_PRETTY_PRINT);
} else {
    echo "Error: HTTP Status " . 
         $response->getStatusCode() . 
         "\nResponse: " . $response->getBody();
}

const axios = require('axios');

// V3 Autocomplete Request
const LUIGISBOX_HOST = 'https://live.luigisbox.tech';
const ENDPOINT_PATH = '/v3/autocomplete';
const TRACKER_ID = 'your_tracker_id';

axios.get(LUIGISBOX_HOST + ENDPOINT_PATH, {
  params: {
    tracker_id: TRACKER_ID,
    q: 'text',
    type: 'item:6'
  },
  headers: {
    'Accept-Encoding': 'gzip, deflate'
  }
})
.then(response => {
  console.log("Autocomplete results:", 
              JSON.stringify(response.data, null, 2));
})
.catch(error => {
  if (error.response) {
    console.error("Error: HTTP Status " + error.response.status + 
                  ", Response: " + JSON.stringify(error.response.data));
  } else {
    console.error("Exception:", error.message);
  }
});

Response Structure

The response is a JSON object containing the requested hits and metadata.

Warning

Handling Redirects (Fixits): The response may contain a suggested_url. Your frontend logic must check for this field and redirect the user immediately if it is present. See the Advanced Features guide for implementation details.

Response Attributes

Field	Type	Description
`exact_match_hits_count`	integer	Number of hits that matched the query exactly.
`partial_match_hits_count`	integer	Number of hits that matched via typo tolerance or partial matching.
`partial_match_terms`	array	List of terms that were used for partial matching correction.
`hits`	array	The list of result objects. Contains the actual suggested items.
`hits[].type`	string	The type of the result object (e.g., `item`, `category`).
`hits[].identity`	string	The unique identifier of the result object.
`hits[].updated_at`	string	ISO 8601 timestamp of when the item was last updated.
`hits[].attributes`	object	Key-value pairs of the indexed fields. Note: String fields (like `title`) usually contain `<em>` tags highlighting the matched query. Raw values are often available as `field.untouched`.
`campaigns`	array	List of `banner` or `fixit` objects active for this query.
`suggested_url`	string	If the query matches a specific redirect rule, this field contains the target URL.

Example Response

json

{
    "exact_match_hits_count": 6,
    "partial_match_hits_count": 0,
    "partial_match_terms": [],
    "hits": [
        {
            "identity": "http://www.e-shop.com/products/123456",
            "attributes": {
                "image_link": "http://www.e-shop.com/assets/imgs/123.jpg",
                "title": "<em>Product</em> X",
                "title.untouched": "Product X",
                "price": "5.52 EUR",
                "availability_rank_text": "true"
            },
            "type": "item",
            "updated_at": "2017-11-23T00:00:00+00:00"
        }
    ],
    "campaigns": [
        {
            "id": 12,
            "target_url": "https://www.e-shop.com/promo",
            "banners": {
                "autocomplete_top": {
                    "desktop_url": "https://www.e-shop.com/banner-1.jpg",
                    "mobile_url": "https://www.e-shop.com/banner-2.jpg"
                }
            }
        }
    ],
    "suggested_url": null
}

Error Handling

The API uses standard HTTP status codes to indicate success or failure.

HTTP Status	Description
200 OK	The request was successful and results are returned.
400 Bad Request	The request was malformed (e.g., missing `tracker_id`).
504 Gateway Timeout	The request took too long to process. Retrying might succeed.

Example Error

json

{
  "type": "malformed_input",
  "reason": "incorrect parameters provided"
}

Navigation