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/search

Request Parameters

The POST endpoint uses a hybrid approach: standard identification parameters (tracker_id, q) are sent in the URL, while the complex boolean logic is sent in the JSON body.

URL Parameters (Query String)

Parameter Type Required Description
tracker_id string ✓ Your unique Luigi's Box tracker identifier.
q string The user's search query.
size integer Number of hits to return. Default: 10.
page integer Result page number. Default: 1.

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

Request Body (JSON)

The body is strictly reserved for the complex filters object.

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

Structure:
  • Root Key: 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/search?tracker_id=179075-204259&q=nike" \
     -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 and q (along with standard parameters like size or page) in the query string.
  • Body: Provide the filters object within the JSON payload to define complex boolean logic.

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|
  # 1. URL Parameters (Authentication & Query)
  req.params['tracker_id'] = '179075-204259'
  req.params['q'] = 'nike'



# 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/search', [
    // 1. URL Parameters
    'query' => [
        'tracker_id' => '179075-204259',
        'q' => 'nike'
    ],
    // 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/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'
    }
  }
)
.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"
}