Facet Value Search

Overview

Facet Value Search lets you search inside a single facet’s values instead of searching the full catalog. It is useful when a facet contains many options and the standard facet list is not enough.

The endpoint processes facet_q against the facet given in facets and returns only matching facet values with their hit counts.

Make sure your catalog is indexed before using this endpoint. See Indexing for setup details.

Note

The facet value search endpoint is public and requires no authentication.

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

Request parameters

Required parameters

Parameter	Description
tracker_id	Your Luigi’s Box site identifier.
facet_q	User input used to search within facet values.
facets	Name of the facet to search within, for example brand.

Caution

You can specify only one facet for this endpoint. The facet_q parameter is ignored by regular search requests. The facet_name:values_count syntax is supported, but it also limits returned results.

Optional parameters

This endpoint supports most optional parameters from the standard Search API, which lets you keep the same search context while searching within facet values.

To get correct results, always include the user’s original q and any active f[] filters. Without the current search context, facet counts may be misleading or irrelevant.

Request headers

Header	Value	Required	Description
Accept-Encoding	gzip, deflate	Recommended	Enables compressed responses.

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

Send a GET request to the endpoint, pass tracker_id, the facet you want to search in, the user’s facet_q, and the current search context.

For step-by-step integration guidance, see Quickstart: Search.

Code Examples

Ruby

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

connection = Faraday.new(url: 'https://live.luigisbox.com') do |conn|
  conn.use FaradayMiddleware::Gzip
end

response = connection.get('/v1/facet_value', {
  tracker_id: 'YOUR_TRACKER_ID',
  'f[]' => ['type:product', 'color:White'],
  q: 'piano',
  facets: 'brand',
  size: 24,
  facet_q: 'yamaha'
})

puts JSON.pretty_generate(JSON.parse(response.body))

PHP

<?php
require 'vendor/autoload.php';

use GuzzleHttp\Client;

$client = new Client();
$response = $client->request('GET', 'https://live.luigisbox.com/v1/facet_value', [
    'query' => [
        'tracker_id' => 'YOUR_TRACKER_ID',
        'f[]' => ['type:product', 'color:White'],
        'q' => 'piano',
        'facets' => 'brand',
        'size' => 24,
        'facet_q' => 'yamaha',
    ],
    'headers' => [
        'Accept-Encoding' => 'gzip',
    ],
]);

echo $response->getBody();

JavaScript

const axios = require('axios');

axios
  .get('https://live.luigisbox.com/v1/facet_value', {
    params: {
      tracker_id: 'YOUR_TRACKER_ID',
      'f[]': ['type:product', 'color:White'],
      q: 'piano',
      facets: 'brand',
      size: 24,
      facet_q: 'yamaha',
    },
    headers: {
      'Accept-Encoding': 'gzip',
    },
  })
  .then((response) => {
    console.log(JSON.stringify(response.data, null, 2));
  })
  .catch((error) => {
    console.error(error.response?.status || error.message);
  });

HTTP Response

Response format

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

Results fields

Field	Description
query	Original search query from q.
corrected_query	Corrected query if Luigi’s Box changed it, otherwise null.
facet_value_query	Query used to search within facet values.
filters	Filters applied to the search context.
filters_negative	Negative filters applied to the search context.
facets	Requested facet and the matching values.

Facet object fields

Field	Description
name	Name of the facet, for example brand.
type	Facet type, for example text, float, or date.
values	Matching facet values.

Facet value fields

Field	Description
value	The facet value itself, for example Yamaha.
hits_count	Number of matching items for that 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 succeeded and results are returned.
400 Bad Request	The request was malformed — missing parameters or invalid facet count.
404 Not Found	The tracker_id does not match any known catalog.
500 Server Error	Internal error. If persistent, contact support.
504 Gateway Timeout	The request took too long to process. Retrying may succeed.

Error responses

400 Bad Request

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

404 Not Found

Catalog for tracker_id: "your-tracker-id" not found.