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

Search API

Use the search endpoint to get a fulltext search functionality with advanced filtering options.

Overview

Use the search endpoint to get a fulltext search functionality with advanced filtering options.

To use this feature, we need to synchronize your product database with our search index. See Indexing the data for more details.

Luigi's Box Search 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.

Note
The search endpoint is publicly available and requires no authentication.

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

Request Parameters

Required parameters

Parameter Type Required Description
tracker_id string ✓ Your unique site identifier within Luigi's Box.
f[] string ✓ Filter using key:value syntax.
Note: A type filter is required in V2 (e.g., f[]=type:item).
q string The user's search query. Optional if you are just filtering.

Optional parameters

Parameter Type Description
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.
f[] string Additional filters (e.g., category:Shoes).

Logic:
  • Filters on the same field are combined with OR.
  • Filters on different fields are combined with AND.
Ranges: Use the pipe character | for numeric/date ranges.
Example: price:10|100.
personalize boolean If set to true, results will be personalized based on the user ID.
Note: If true, you must provide auth_user_id.
size integer Number of hits to return (Default: 10, Max: 200).
sort string Sort order (e.g., price:asc). Overrides AI ranking.
sort_type string Sort order for specific types (e.g., sort_item=price:asc).
quicksearch_types string Secondary content types to search (e.g., category,brand).
facets string List of facets to retrieve (e.g., brand,color:5).
dynamic_facets_size integer Max number of AI-selected facets to return.
page integer Result page number. Default: 1.
from integer Result offset (alternative to page).
use_fixits boolean Enable automatic typo correction. Default: true.
prefer[] string Soft filters for query-time boosting.
hit_fields string Fields to include in the response.
remove_fields string Fields to exclude from the response.
ctx[] string Arbitrary context tags (e.g., warehouse:berlin).
qu boolean Enable Query Understanding (intent detection).
non_collapsed_variants boolean Return all variants as individual hits. Default: false.

Context Parameters

Parameter Type Description
context[geo_location] string User coordinates (lat,lon) for distance filtering.
context[geo_location_field] string Custom field name containing item coordinates.
context[availability_field] string Custom field for availability status (0/1).
context[availability_rank_field] string Custom field for detailed availability ranking (1-15).
context[boost_field] string Custom field for numeric boosting (0-3).
context[freshness_field] string Custom date field (ISO 8601) for freshness ranking.

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/v2/search?tracker_id=YOUR_TRACKER_ID&q=harry+potter&f[]=type:item" \
     -H "Accept-Encoding: gzip, deflate"

How to make a request

To make a request to this endpoint, you need to send a GET request to the URL. The tracker_id parameter is required to identify your Luigi's Box account. You can typically find this in the Luigi's Box app. Ensure you handle the response and any errors as shown in the example code.

For a comprehensive, step-by-step tutorial on integrating this endpoint into your application, please refer to our Quickstart: Search guide.

Example Code

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


require 'faraday'
require 'json'



LUIGISBOX_HOST = 'https://live.luigisbox.com'
ENDPOINT_PATH = '/v2/search'
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'] = 'harry potter'
  req.params['f[]'] = 'type:item'
  req.headers['Accept-Encoding'] = 'gzip, deflate'
end



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

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


require 'vendor/autoload.php';



use GuzzleHttp\Client;



$LUIGISBOX_HOST = 'https://live.luigisbox.com';
$ENDPOINT_PATH = '/v2/search';
$TRACKER_ID = 'your_tracker_id';



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



if($response->getStatusCode() == 200) {
    echo "Search 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');


// Search Request
const LUIGISBOX_HOST = 'https://live.luigisbox.com';
const ENDPOINT_PATH = '/v2/search';
const TRACKER_ID = 'your_tracker_id';



axios.get(LUIGISBOX_HOST + ENDPOINT_PATH, {
  params: {
    tracker_id: TRACKER_ID,
    q: 'harry potter',
    'f[]': 'type:item'
  },
  headers: {
    'Accept-Encoding': 'gzip, deflate'
  }
})
.then(response => {
  console.log("Search 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);
  }
});

HTTP Response

The response is a structured JSON object containing two top-level fields: results and next_page.

Results fields

Field Description
query The requested query string.
corrected_query Optional. Contains the HTML string of the query with typos fixed (e.g., <strike>sheos</strike> shoes).
Note: Returned only if the query was altered.
total_hits Total number of hits found for the requested type.
hits A list of result objects for the requested type.
facets A list of facets and their counts.
Behavior: Facets that are currently being filtered will return all available options (to allow multi-select), while other facets will return only values relevant to the current search results.
filters A list of filters that were applied to the results.
quicksearch_hits A list of results for secondary types requested via quicksearch_types (e.g., matching categories or brands).
suggested_facet Optional. Indicates one facet evaluated as most useful for narrowing down the current result set.
suggested_url Optional. A redirect URL if the system detects a direct match (e.g., a "Fixit" rule or strict intent).
campaigns A list of banner campaigns associated with the query.

Hit fields

Field Description
identity Unique identifier of the result object. (Replaces url from V1).
attributes Object containing all stored fields from the catalog (e.g., title, price, brand).
attributes.title.untouched The raw title string without any highlighting tags. Useful if you want to display the title cleanly without <em> tags.
type Type of the result (e.g., "item").
nested Array of nested objects (e.g., variants) associated with the hit.

Example Response

{
  "results": {
    "query": "putter",
    "corrected_query": "<strike>harry</strike><strike>potter</strike> <b>putter</b>",
    "filters": [
      "type:product"
    ],
    "total_hits": 223,
    "hits": [
      {
        "identity": "/jucad-putter-right-hand/?variantId=2448462",
        "attributes": {
          "title": "Jucad Putter Right Hand",
          "price_eur": "149 €",
          "brand": [
            "Jucad"
          ],
          "categories": [
            "Golfers",
            "Clubs",
            "Putters"
          ],
          "image_link": "https://cdn.myshoptet.com/usr/demoshop.luigisbox.com/user/shop/detail/1817277.jpg",
          "availability_rank_text": "In Stock"
        },
        "type": "item",
        "nested": []
      }
    ],
    "facets": [
      {
        "name": "price_amount",
        "type": "float",
        "values": [
          {
            "value": "0.69|30.0",
            "hits_count": 56,
            "normalized_hits_count": 0.18
          },
          {
            "value": "30.0|60.0",
            "hits_count": 34,
            "normalized_hits_count": 0.11
          }
        ]
      }
    ],
    "offset": "20",
    "campaigns": []
  },
  "next_page": "https://live.luigisbox.com/search?q=putter&tracker_id=179075-204259&page=2"
}

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"
}