---
title: Facet Value Search
description: The facet value search endpoint enables targeted searching within specific facet values.
slug: search/api/facet-value
docKind: endpoint
hub: search
tableOfContents: true
---
import ApiSection from "../../../../components/ApiSection.astro";
import ApiEndpoint from "../../../../components/ApiEndpoint.astro";
import ApiCodeTabs from "../../../../components/ApiCodeTabs.astro";
import { Aside, Tabs, TabItem } from "@astrojs/starlight/components";

<ApiSection>
  <div slot="code">
    <ApiEndpoint method="GET" url="https://live.luigisbox.com/v1/facet_value" />
  </div>
## 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](/indexing/) for setup details.

<Aside type="note">
  The facet value search endpoint is public and requires no authentication.
</Aside>
</ApiSection>

<ApiSection>
## 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`. |

<Aside type="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.
</Aside>

### Optional parameters

This endpoint supports most optional parameters from the standard [Search API](/search/api/v1/search/), 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. |

  <div slot="code">
    <h4 class="code-section-title">Example Request</h4>

```shell
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"
```
  </div>
</ApiSection>

<ApiSection>
## 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](/quickstart/search/).

  <div slot="code">
    <h4 class="code-section-title">Code Examples</h4>
    <ApiCodeTabs syncKey="facet-value-request">
      <div slot="ruby">

```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))
```
      </div>
      <div slot="php">

```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();
```
      </div>
      <div slot="javascript">

```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);
  });
```
      </div>
    </ApiCodeTabs>
  </div>
</ApiSection>

<ApiSection>
## 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. |

  <div slot="code">
    <h4 class="code-section-title">Example Response</h4>

```json
{
  "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
          }
        ]
      }
    ]
  }
}
```
  </div>
</ApiSection>

<ApiSection>
## 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. |

  <div slot="code">
    <h4 class="code-section-title">Error responses</h4>

<Tabs>
  <TabItem label="400 Bad Request">
```json
{
  "facets": [
    "facets The request contained zero or more than one facet. Please specify one and only one facet with this type of request."
  ]
}
```
  </TabItem>
  <TabItem label="404 Not Found">
```text
Catalog for tracker_id: "your-tracker-id" not found.
```
  </TabItem>
</Tabs>
  </div>
</ApiSection>