Navigation
🚨

Critical Security Migration

The luigisbox.com domain is compromised. Immediate action is required.

1. Update API Base URLs

Replace the base URL for all API requests (Search, Recommendations, Analytics):

https://live.luigisbox.com
➡️ https://live.luigisbox.tech

2. Replace Frontend Script

The .com script is no longer safe. Replace it with the secure version immediately:

[OLD - Delete from site]
<script async src="https://scripts.luigisbox.com/LBX-123.js"></script>
[NEW - Secure Version]
<script async src="https://scripts.luigisbox.tech/LBX-123.js"></script>

3. Update CSP & Firewalls

If you use a Content Security Policy, whitelist the new domain to prevent the browser from blocking the connection.

script-src https://scripts.luigisbox.tech;
connect-src https://live.luigisbox.tech;
⚠️
Emergency Action: If you cannot update the code right now, remove the existing Luigi's Box script until the migration is complete to prevent unauthorized code execution.
Support: support@luigisbox.net MODIFIED: 12/17/2025
API v1 API v2 API v3

Autocomplete API

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

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.

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

Request Parameters

To request autocomplete results, you must provide your tracker ID and the user's input query. You can also specify which types of objects you want to retrieve.

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
user_id string A unique string identifying the user. Required for personalization.
client_id string An anonymous identifier for the browser/device. Used for analytics and session tracking.
personalize boolean Set to true to enable personalized re-ranking of results. Requires user_id to be present.
f_type[] string Applies a filter to a specific result type. Format: f_<type>[]=<field>:<value>.
Example: f_item[]=category:Shoes filters items to only show Shoes.
sort_type string Sorts results of a specific type. Format: sort_<type>=<field>:<dir>.
Example: sort_item=price:asc sorts items by price.
prefer[] string Boosts items matching a criteria without strictly filtering them. Format: prefer[]=<field>:<value>.
hit_fields string Comma-separated list of specific fields to retrieve in the response (e.g., title,url,price).
context string Arbitrary context string (e.g., "mobile_header") to segment analytics.
ctx[] string Context parameters for dynamic model selection or boosting rules.
non_collapsed_variants boolean If true, returns all product variants individually instead of collapsing them into a single parent product.

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

curl "https://live.luigisbox.com/autocomplete/v2?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:

  1. Endpoint: Use https://live.luigisbox.com/autocomplete/v2.
  2. Parameters: Include your tracker_id, the user's search query q, and the desired type of results (e.g., item:6 for 6 items).
  3. Encoding: Ensure all query parameters are properly URL-encoded.
  4. 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 /autocomplete/v2 ---
# Assumes 'faraday' gem is installed (gem install faraday)


require 'faraday'
require 'json'



LUIGISBOX_HOST = 'https://live.luigisbox.com'
ENDPOINT_PATH = '/autocomplete/v2'
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 /autocomplete/v2
// Assumes Guzzle is installed: 
// composer require guzzlehttp/guzzle


require 'vendor/autoload.php';



use GuzzleHttp\Client;



$LUIGISBOX_HOST = 'https://live.luigisbox.com';
$ENDPOINT_PATH = '/autocomplete/v2';
$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');


// V2 Autocomplete Request
const LUIGISBOX_HOST = 'https://live.luigisbox.com';
const ENDPOINT_PATH = '/autocomplete/v2';
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.

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 Unique identifier of the object.
hits[].url string The URL to redirect to when the user selects this suggestion.
hits[].attributes object Key-value pairs of the indexed fields you requested (or defaults if hit_fields was unused).
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

{
    "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",
                "title": "Product X",
                "price": "5.52 EUR"
            },
            "type": "item",
            "identity": "123456"
        },
        {
            "url": "http://www.e-shop.com/categories/electronics",
            "attributes": {
                "title": "Electronics"
            },
            "type": "category",
            "identity": "cat-1"
        }
    ],
    "campaigns": [],
    "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

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