Facet value search
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.
📋 Prerequisites
Luigi's Box must synchronize your product database with its search index before using this feature.
See Indexing the data for setup instructions.
Endpoint
GET https://live.luigisbox.com/v1/facet_value
Required Parameters
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 ) |
⚠️ Important limitations
- 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.
❗ Don't forget the context!
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.
Examples
Standard search request
GET https://live.luigisbox.com/search?tracker_id=111111-111111&f[]=type:product&f[]=color:White&q=piano&facets=brand,color,price_amount&size=24
Corresponding facet value search
GET https://live.luigisbox.com/v1/facet_value?racker_id=111111-111111&f[]=type:product&f[]=color:White&q=piano&facets=brand&size=24&facet_q=yamaha
Response format
{
"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
}
]
}
]
}
}
Implementation examples
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
// 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']);
?>
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']);
Error handling
Common errors
Multiple or missing facets (400 Bad Request)
{
"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."
]
}
Best practices
-
Single facet requirement: Always specify exactly one facet in the
facets
parameter. -
Carry over full context: To ensure relevant results, always pass the
q
parameter and all activef[]
filters from the user's main search to the facet value search request. - Error handling: Implement proper error handling for HTTP status codes and API-specific error responses.