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

Facet Value Search

The facet value search endpoint enables targeted searching within specific facet values.

Overview

The facet value search endpoint enables targeted searching within specific facet values. This is particularly useful when working with facets that contain many options, where the standard facet listing doesn't provide sufficient filtering capabilities.

This endpoint processes the facet_q parameter to search within a specified facet's values and returns only matching facet values with their corresponding hit counts.

Luigi's Box must synchronize your product database with its search index before using this feature. See Indexing the data for setup instructions.

Note
This endpoint is publicly available and does not require authentication.

GET https://live.luigisbox.com/v1/facet_value

Request Parameters

Required Parameters

Parameter Description
tracker_id Your site identifier within Luigi's Box (visible in all URLs when logged into the Luigi's Box app)
facet_q User input - the query string to search within facet values.
facets Name of the facet to search within (e.g., facets=category)
!
Warning
  • You can only specify one facet (e.g., facets:brand).
  • The facet_q parameter only works with this endpoint; it's ignored in regular search requests
  • While facet_name:values_count syntax is supported (e.g., facets=category:10), it limits returned results

Optional Parameters

This endpoint supports most optional parameters from the standard search endpoint, allowing you to maintain the consistent filtering and context when searching within facet values. Please refer to the Search API for a complete list of optional parameters. You can reuse URL parameters from your search requests, simply change the endpoint to v1/facet_value and add the required facet_q and facets parameters.

!
Warning
To get the right results, you **must** include the user's current search context. Without it, the API may return irrelevant facet values and misleading hit counts. Always pass the original `q` and any active `f[]` filters from the main search to this endpoint. For example, if a user's search for "pianos" is filtered by `type:product` and `color:White`, your facet search call needs to include the original `q=piano` and both `f[]` filters.

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/v1/facet_value?tracker_id=111111-111111&f[]=type:product&f[]=color:White&q=piano&facets=brand&size=24&facet_q=yamaha"

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 /v1/facet_value ---
# Assumes 'faraday' gem is installed (gem install faraday)

require 'faraday' require 'faraday_middleware' require 'json'

BASE_URL = 'https://live.luigisbox.com' FACET_VALUE_ENDPOINT = '/v1/facet_value' TRACKER_ID = 'YOUR_TRACKER_ID'

def search_facet_values(facet_query, search_query, filters) connection = Faraday.new(url: BASE_URL) do |conn| conn.use FaradayMiddleware::Gzip end

response = connection.get(FACET_VALUE_ENDPOINT, { tracker_id: TRACKER_ID, 'f[]' => filters, q: search_query, facets: 'brand', size: 24, facet_q: facet_query })

if response.success? puts JSON.pretty_generate(JSON.parse(response.body)) else puts "Error, HTTP status #{response.status}" puts response.body end end

# Usage for "white pianos" context search_facet_values('yamaha', 'piano', ['type:product', 'color:White'])

<?php
// PHP Example for GET /v1/facet_value
// Install Guzzle: composer require guzzlehttp/guzzle
require 'vendor/autoload.php';

use GuzzleHttp\Client; use GuzzleHttp\Exception\RequestException;

// Constants const BASE_URL = 'https://live.luigisbox.com'; const FACET_VALUE_ENDPOINT = '/v1/facet_value'; const TRACKER_ID = 'YOUR_TRACKER_ID';

/** * Search within facet values using Luigi's Box API */ function searchFacetValues($facetQuery, $searchQuery, $filters) { $client = new Client();

try { $response = $client->request('GET', BASE_URL . FACET_VALUE_ENDPOINT, [ 'query' => [ 'tracker_id' => TRACKER_ID, 'f[]' => $filters, 'q' => $searchQuery, 'facets' => 'brand', 'size' => 24, 'facet_q' => $facetQuery ], 'headers' => [ 'Accept-Encoding' => 'gzip' ] ]);

echo "Status: " . $response->getStatusCode() . "\n"; echo $response->getBody();

return json_decode($response->getBody(), true); } catch (RequestException $e) { echo "Error: " . $e->getMessage() . "\n"; if ($e->hasResponse()) { echo "Status: " . $e->getResponse()->getStatusCode() . "\n"; echo $e->getResponse()->getBody(); } throw $e; } }

// Usage for "white pianos" context searchFacetValues('yamaha', 'piano', ['type:product', 'color:White']); ?>

// --- Javascript Example for GET /v1/facet_value ---
const axios = require('axios');

const BASE_URL = 'https://live.luigisbox.com'; const FACET_VALUE_ENDPOINT = '/v1/facet_value'; const TRACKER_ID = 'YOUR_TRACKER_ID';

const searchFacetValues = async (facetQuery, searchQuery, filters) => { const params = { tracker_id: TRACKER_ID, 'f[]': filters, q: searchQuery, facets: 'brand', size: 24, facet_q: facetQuery };

try { const response = await axios.get(BASE_URL + FACET_VALUE_ENDPOINT, { params: params, headers: { 'Accept-Encoding': 'gzip' } });

console.log('Status:', response.status); console.log(JSON.stringify(response.data, null, 2)); return response.data; } catch (error) { console.error('Error:', error.response?.status || error.message); if (error.response) { console.error(error.response.data); } throw error; } };

// Usage for "white pianos" context searchFacetValues('yamaha', 'piano', ['type:product', 'color:White']);

HTTP Response

Response format

The response is a JSON object containing the results of the facet value search.

Results fields

Field Description
query The original search query (q parameter).
corrected_query If the search query was automatically corrected, this field contains the corrected version. Otherwise null.
facet_value_query The query used to search within facet values (facet_q parameter).
filters List of filters applied to the search context.
filters_negative List of negative filters (exclusions) applied.
facets List containing the requested facet and its matching values.

Facet object fields

Field Description
name Name of the facet (e.g., "brand").
type Type of the facet (e.g., "text", "float", "date").
values List of matching facet values.

Facet Value object fields

Field Description
value The actual value of the facet (e.g., "Yamaha").
hits_count Number of items matching this facet value within the current search context.

Example Response

{
  "results": {
    "query": "piano",
    "corrected_query": null,
    "facet_value_query": "yamaha",
    "filters": [
      "type:product",
      "color:White"
    ],
    "filters_negative": [],
    "facets": [
      {
        "name": "brand",
        "type": "text",
        "values": [
          {
            "value": "Yamaha",
            "hits_count": 25
          }
        ]
      }
    ]
  }
}

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 or missing required parameters (like tracker_id).
504 Gateway Timeout The request took too long to process. Retrying might succeed.

Example Error

{
    "facet_q": [
        "facet_q The request contained zero or more than one facet. Please specify one and only one facet with this type of request."
    ]
}