Search for facet values

Searches for values of a specified facet attribute on the composition’s main source’s index.

POST /1/compositions/{compositionID}/facets/{facetName}/query

curl

cURL

curl --request POST \
  --url https://algolia_application_id.algolia.net/1/compositions/my_composition_object_id/facets/lorem/query \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'x-algolia-api-key: ALGOLIA_API_KEY' \
  --header 'x-algolia-application-id: ALGOLIA_APPLICATION_ID' \
  --data '
{
  "params": {
    "query": "",
    "maxFacetHits": 10,
    "searchQuery": {
      "analytics": true,
      "analyticsTags": [],
      "aroundLatLng": "40.71,-74.01",
      "aroundLatLngViaIP": false,
      "aroundRadius": 1,
      "aroundPrecision": 10,
      "clickAnalytics": false,
      "enableABTest": true,
      "enablePersonalization": false,
      "enableReRanking": true,
      "enableRules": true,
      "facetFilters": [
        [
          "category:Book",
          "category:-Movie"
        ],
        "author:John Doe"
      ],
      "facets": [
        "category",
        "disjunctive(brand)",
        "price"
      ],
      "filters": "(category:Book OR category:Ebook) AND _tags:published",
      "getRankingInfo": false,
      "hitsPerPage": 20,
      "injectedItems": {
        "my-group-key": {
          "items": [
            {
              "objectID": "my-object-1",
              "metadata": {
                "my-field": "my-value"
              }
            },
            {
              "objectID": "my-object-2",
              "metadata": {
                "my-field": "my-value-2"
              }
            }
          ]
        },
        "my-other-group-key": {
          "items": [
            {
              "objectID": "my-other-object-1"
            },
            {
              "objectID": "my-other-object-2"
            }
          ]
        }
      },
      "insideBoundingBox": "lorem",
      "insidePolygon": [
        [
          47.3165,
          4.9665,
          47.3424,
          5.0201,
          47.32,
          4.9
        ],
        [
          40.9234,
          2.1185,
          38.643,
          1.9916,
          39.2587,
          2.0104
        ]
      ],
      "minimumAroundRadius": 1,
      "naturalLanguages": [],
      "numericFilters": [
        [
          "inStock = 1",
          "deliveryDate < 1441755506"
        ],
        "price < 1000"
      ],
      "optionalFilters": [
        "category:Book",
        "author:John Doe"
      ],
      "page": 0,
      "query": "",
      "queryLanguages": [
        "es"
      ],
      "relevancyStrictness": 90,
      "ruleContexts": [
        "mobile"
      ],
      "sortBy": "Price (asc)",
      "userToken": "test-user-123"
    }
  }
}
'

// Initialize the client
var client = new CompositionClient(
  new CompositionConfig("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY")
);

// Call the API
var response = await client.SearchForFacetValuesAsync(
  "foo",
  "brand",
  new SearchForFacetValuesRequest
  {
    Params = new SearchForFacetValuesParams { MaxFacetHits = 10 },
  }
);

// print the response
Console.WriteLine(response);

// Initialize the client
final client = CompositionClient(
    appId: 'ALGOLIA_APPLICATION_ID', apiKey: 'ALGOLIA_API_KEY');

// Call the API
final response = await client.searchForFacetValues(
  compositionID: "foo",
  facetName: "brand",
  searchForFacetValuesRequest: SearchForFacetValuesRequest(
    params: SearchForFacetValuesParams(
      maxFacetHits: 10,
    ),
  ),
);

// print the response
print(response);

// Initialize the client
client, err := composition.NewClient("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY")
if err != nil {
  // The client can fail to initialize if you pass an invalid parameter.
  panic(err)
}

// Call the API
response, err := client.SearchForFacetValues(client.NewApiSearchForFacetValuesRequest(
  "foo", "brand").WithSearchForFacetValuesRequest(
  composition.NewEmptySearchForFacetValuesRequest().SetParams(
    composition.NewEmptySearchForFacetValuesParams().SetMaxFacetHits(10))))
if err != nil {
  // handle the eventual error
  panic(err)
}


// print the response
print(response)

// Initialize the client
CompositionClient client = new CompositionClient("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY");

// Call the API
SearchForFacetValuesResponse response = client.searchForFacetValues(
  "foo",
  "brand",
  new SearchForFacetValuesRequest().setParams(new SearchForFacetValuesParams().setMaxFacetHits(10))
);

// print the response
System.out.println(response);

// Initialize the client
const client = compositionClient('ALGOLIA_APPLICATION_ID', 'ALGOLIA_API_KEY');

// Call the API
const response = await client.searchForFacetValues({
  compositionID: 'foo',
  facetName: 'brand',
  searchForFacetValuesRequest: { params: { maxFacetHits: 10 } },
});


// print the response
console.log(response);

// Initialize the client
val client = CompositionClient(appId = "ALGOLIA_APPLICATION_ID", apiKey = "ALGOLIA_API_KEY")

// Call the API
var response =
  client.searchForFacetValues(
    compositionID = "foo",
    facetName = "brand",
    searchForFacetValuesRequest =
      SearchForFacetValuesRequest(params = SearchForFacetValuesParams(maxFacetHits = 10)),
  )


// print the response
println(response)

// Initialize the client
$client = CompositionClient::create('ALGOLIA_APPLICATION_ID', 'ALGOLIA_API_KEY');

// Call the API
$response = $client->searchForFacetValues(
    'foo',
    'brand',
    ['params' => ['maxFacetHits' => 10,
    ],
    ],
);


// print the response
var_dump($response);

# Initialize the client
# In an asynchronous context, you can use CompositionClient instead, which exposes the exact same methods.
client = CompositionClientSync("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY")

# Call the API
response = client.search_for_facet_values(
    composition_id="foo",
    facet_name="brand",
    search_for_facet_values_request={
        "params": {
            "maxFacetHits": 10,
        },
    },
)


# print the response
print(response)

# Initialize the client
client = Algolia::CompositionClient.create("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY")

# Call the API
response = client.search_for_facet_values(
  "foo",
  "brand",
  Algolia::Composition::SearchForFacetValuesRequest.new(
    params: Algolia::Composition::SearchForFacetValuesParams.new(max_facet_hits: 10)
  )
)


# print the response
puts(response)

// Initialize the client
val client = CompositionClient(appId = "ALGOLIA_APPLICATION_ID", apiKey = "ALGOLIA_API_KEY")

// Call the API
val response = Await.result(
  client.searchForFacetValues(
    compositionID = "foo",
    facetName = "brand",
    searchForFacetValuesRequest = Some(
      SearchForFacetValuesRequest(
        params = Some(
          SearchForFacetValuesParams(
            maxFacetHits = Some(10)
          )
        )
      )
    )
  ),
  Duration(100, "sec")
)

// print the response
println(response)

// Initialize the client
let client = try CompositionClient(appID: "ALGOLIA_APPLICATION_ID", apiKey: "ALGOLIA_API_KEY")

// Call the API
let response = try await client.searchForFacetValues(
    compositionID: "foo",
    facetName: "brand",
    searchForFacetValuesRequest: CompositionSearchForFacetValuesRequest(
        params: SearchForFacetValuesParams(maxFacetHits: 10)
    )
)

// print the response
print(response)

200

{
  "results": [
    {
      "exhaustiveFacetsCount": true,
      "facetHits": [
        {
          "count": 123,
          "highlighted": "<em>George</em> <em>Clo</em>oney",
          "value": "Mobile phone"
        }
      ],
      "indexName": "<string>",
      "processingTimeMS": 20
    }
  ]
}

{
  "message": "Invalid Application-Id or API-Key"
}

{
  "message": "Invalid Application-Id or API-Key"
}

{
  "message": "Invalid Application-Id or API-Key"
}

{
  "message": "Invalid Application-Id or API-Key"
}

• By default, facet values are sorted by decreasing count. You can adjust this with the sortFacetValueBy parameter.
• Searching for facet values doesn’t work if you have more than 65 searchable facets and searchable attributes combined.

Required ACL: search

Authorizations

x-algolia-application-id · string · header · required

Your Algolia application ID.

x-algolia-api-key · string · header · required

Your Algolia API key with the necessary permissions to make the request. Permissions are controlled through access control lists (ACL) and access restrictions. The required ACL to make a request is listed in each endpoint's reference.

Path Parameters

compositionID · string · required

Unique Composition ObjectID. Composition unique identifier.

Example:

"my_composition_object_id"

facetName · string · required

Facet attribute in which to search for values.

This attribute must be included in the attributesForFaceting index setting with the searchable() modifier.

Body

application/json

params · searchForFacetValuesParams · object

Show child attributes

Response

200

application/json

OK

results · object[]

Search for facet values results.

Show child attributes