Overview
The POST endpoint is designed for advanced use cases requiring complex boolean logic (nested AND/OR/NOT conditions) or large filter payloads that exceed the limits of URL parameters.
https://live.luigisbox.com/search
Request Body
The request body must be a JSON object.
Required parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
tracker_id |
string | ✓ | Your unique Luigi's Box tracker identifier. |
filters |
object | ✓ |
A structured object defining complex boolean logic.
Structure:
|
Optional Body Parameters
| Parameter | Type | Description |
|---|---|---|
q |
string | The user's search query. Optional if you only want to filter results. |
size |
integer |
Number of hits to return.
Default: 10 (Max: 200).
|
sort |
string |
Sort order using field:direction syntax (e.g., price:asc).
Warning: Overrides AI relevance ranking. |
sort_type |
string |
Sort order for specific result types (e.g., sort_item=price:asc).
|
quicksearch_types |
string |
Comma-separated list of secondary content types to include (e.g., category,brand).
|
facets |
string |
Comma-separated list of facets to retrieve (e.g., brand,color:5).
|
dynamic_facets_size |
integer |
Maximum number of AI-selected facets to return. Default: 0.
|
page |
integer | Result page number. Default: 1. |
from |
integer | Result offset (alternative to page). |
use_fixits |
boolean | Enable/disable automatic typo correction. Default: true. |
prefer |
array |
Soft filter array for query-time boosting (e.g., ["category:Gadgets"]).
|
hit_fields |
string | Comma-separated list of fields to include. |
remove_fields |
string | Comma-separated list of fields to exclude. |
user_id |
string | User identifier for personalization. |
client_id |
string | Analytics Client ID (required if user_id is a logged-in ID). |
ctx |
array |
Context definitions for model selection (e.g., ["warehouse:berlin"]).
|
qu |
boolean | Enable Query Understanding. Requires user_id. |
non_collapsed_variants |
boolean | Return all variants as individual hits. Default: false. |
Context Parameters (Body)
| Parameter | Type | Description |
|---|---|---|
context |
object |
Object containing context keys.
Keys: geo_location, availability_field, etc.
See Search Features for 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 the JSON API considerably smaller and thus faster to transfer.
| Header | Value | Required | Description |
|---|---|---|---|
Content-Type |
application/json |
✓ | Indicates the body format. |
Example Request
# POST request for complex filtering
curl -X POST "https://live.luigisbox.com/search" \
-H "Content-Type: application/json" \
-d '{
"tracker_id": "YOUR_TRACKER_ID",
"q": "nike",
"filters": {
"item": {
"and": [
{ "filter": "categories:Shoes" },
{
"not": [
{ "filter": "size:42" }
]
}
]
}
}
}'
How to make a request
To make a request to this endpoint, you need to send a POST 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 POST /search ---
# Assumes 'faraday' gem is installed
require 'faraday'
require 'json'
LUIGISBOX_HOST = 'https://live.luigisbox.com'
ENDPOINT_PATH = '/search'
conn = Faraday.new(url: LUIGISBOX_HOST)
response = conn.post(ENDPOINT_PATH) do |req|
req.headers['Content-Type'] = 'application/json'
req.body = {
tracker_id: 'YOUR_TRACKER_ID',
q: 'nike',
filters: {
item: {
and: [
{ filter: 'categories:Shoes' },
{ not: [{ filter: 'size:42' }] }
]
}
}
}.to_json
end
puts response.body
<?php
// PHP Example for POST /search
// Assumes Guzzle is installed
require 'vendor/autoload.php';
use GuzzleHttp\Client;
$client = new Client();
$response = $client->post('https://live.luigisbox.com/search', [
'json' => [
'tracker_id' => 'YOUR_TRACKER_ID',
'q' => 'nike',
'filters' => [
'item' => [
'and' => [
['filter' => 'categories:Shoes'],
['not' => [['filter' => 'size:42']]]
]
]
]
]
]);
echo $response->getBody();
?>
// Node.js Example for POST /search
// Assumes axios is installed
const axios = require('axios');
axios.post('https://live.luigisbox.com/search', {
tracker_id: 'YOUR_TRACKER_ID',
q: 'nike',
filters: {
item: {
and: [
{ filter: 'categories:Shoes' },
{ not: [{ filter: 'size:42' }] }
]
}
}
})
.then(response => {
console.log(response.data);
})
.catch(error => {
console.error(error);
});
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 |
|---|---|
url |
Unique identifier of the result object. |
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": [
{
"url": "/jucad-putter-right-hand/?variantId=2448462",
"attributes": {
"title": "Jucad <em>Putter</em> Right Hand",
"title.untouched": "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.
| HTTP Status | Description |
|---|---|
| 200 OK | The request was successful. |
| 400 Bad Request | The request was malformed (e.g., invalid JSON). |
Example Error
{
"type": "malformed_input",
"reason": "json syntax error"
}