Navigation

Search API (POST)

Use the POST search endpoint for complex queries and filtering.

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.

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

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

Request Parameters

URL Parameters (Query String)

Parameter Type Required Description
tracker_id string ✓ Your unique Luigi's Box tracker identifier.
f[] string ✓ The required Type filter (e.g., type:item).
Note: Additional filters go in the Body.
q string The user's search query.
auth_user_id string Logged-in User ID.
device_user_id string Anonymous Device ID (cookie).
size integer Number of hits (Default: 10).
page integer Page number (Default: 1).
sort string Sort order (e.g., price:asc). Overrides AI ranking.

Important Refer to the GET /search documentation for a full list of URL parameters.

Request Body (JSON)

The request body accepts a JSON object defining the filter logic and context.

Parameter Type Required Description
filters object ✓ A structured object defining complex boolean logic.

Structure:
  • Root Key: Must match the content type (e.g., "item").
  • Logic Keys: Nested and, or, not arrays.
  • Filter Objects: Each array item must be an object containing a filter key.
Example: 
{
  "item": {
    "or": [
      { "filter": "color:red" },
      { "filter": "color:blue" }
    ]
  }
}

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/v2/search?tracker_id=179075-204259&q=nike&f[]=type:product" \
     -H "Content-Type: application/json" \
     -d '{
       "filters": {
         "item": {
           "and": [
             { "filter": "categories:Shoes" },
             {
               "not": [
                 { "filter": "size:42" }
               ]
             }
           ]
         }
       }
     }'

Request Construction

Execute a POST request to the endpoint with the Content-Type header set to application/json.

  • URL: Include tracker_id, q, and the mandatory type filter (f[]=type:item) in the query string.
  • Body: Provide the filters object within the JSON payload.

Example Code

# --- Ruby Example for POST /search ---
# Assumes 'faraday' gem is installed


require 'faraday'
require 'json'



LUIGISBOX_HOST = 'https://live.luigisbox.com'
ENDPOINT_PATH = '/v2/search'



conn = Faraday.new(url: LUIGISBOX_HOST)



response = conn.post(ENDPOINT_PATH) do |req|
  # 1. URL Parameters (Authentication & Query)
  req.params['tracker_id'] = '179075-204259'
  req.params['q'] = 'nike'
  req.params['f[]'] = 'type:product'



# 2. Body Payload (Complex Filters)
  req.headers['Content-Type'] = 'application/json'
  req.body = {
    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/v2/search', [
    // 1. URL Parameters
    'query' => [
        'tracker_id' => '179075-204259',
        'q' => 'nike',
        'f[]' => 'type:product'
    ],
    // 2. Body Payload
    'json' => [
        '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/v2/search', 
  // 1. Body Payload
  {
    filters: {
      item: {
        and: [
          { filter: 'categories:Shoes' },
          { not: [{ filter: 'size:42' }] }
        ]
      }
    }
  },
  // 2. URL Parameters (Config)
  {
    params: {
      tracker_id: '179075-204259',
      q: 'nike',
      f: ['type:product']
    }
  }
)
.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
identity Unique identifier of the result.
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.

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