--- title: "Using faceted search" slug: "using-faceted-search" abstract: "Learn how to use the Search and Recommendation API for Sitecore Search to get search results with facets." --- # Using faceted search To request a facet, add a `widget.items.search.facet` object to your request. > [!note] > Before you can get facets, make sure that an administrator configures attributes for [facets](https://doc.sitecore.com/search/en/users/search-user-guide/refine-search-results.html) in Search. For the data model of this object, see the [Search and Recommendation API reference](https://doc.sitecore.com/search/en/developers/search-and-recommentation-api/index.html). The following sections show sample requests to get facets. ## Get all available facets To get all available facets, set the `all` key to `true`. The following is a sample request: ```JSON { "widget": { "items": [ { "rfk_id": "rfkid_7", "entity": "content", "search": { "facet": { "all": true } } } ] }, "context": { "locale": { "country": "us", "language": "en" }, "user": { "uuid": "159871551-io-0i-4e-1p-s6ill6vhenvysbu27bbk-1664389956369" } } } ``` The following is the response to this request: ```JSON { "widgets": [ { "rfk_id": "rfkid_7", "entity": "content", "facet": [ { "name": "product", "label": "Product", "value": [ { "id": "facetid_eyJ0eXBlIjoiZXEiLCJuYW1lIjoicHJvZHVjdCIsInZhbHVlIjoiRXhwZXJpZW5jZSBQbGF0Zm9ybSAoWFApIn0=", "text": "Experience Platform (XP)", "count": 130 }, { "id": "facetid_eyJ0eXBlIjoiZXEiLCJuYW1lIjoicHJvZHVjdCIsInZhbHVlIjoiRXhwZXJpZW5jZSBNYW5hZ2VyIChYTSkifQ==", "text": "Experience Manager (XM)", "count": 80 }, { "id": "facetid_eyJ0eXBlIjoiZXEiLCJuYW1lIjoicHJvZHVjdCIsInZhbHVlIjoiQ29udGVudCBIdWIifQ==", "text": "Content Hub", "count": 73 } ... ] }, { "name": "type", "label": "Type", "value": [ { "id": "facetid_eyJ0eXBlIjoiZXEiLCJuYW1lIjoidHlwZSIsInZhbHVlIjoib3RoZXIifQ==", "text": "other", "count": 990 }, { "id": "facetid_eyJ0eXBlIjoiZXEiLCJuYW1lIjoidHlwZSIsInZhbHVlIjoibmV3cyJ9", "text": "news", "count": 623 }, { "id": "facetid_eyJ0eXBlIjoiZXEiLCJuYW1lIjoidHlwZSIsInZhbHVlIjoiQmxvZ3MifQ==", "text": "Blogs", "count": 519 } ... ] } ] } ], "dt": 62, "ts": 1669437158552 } ``` In the response `facet` object, you can see that the two available facets, `product` and `type` appear. Each facet array has objects for the facet values within that facet type. ## Get values for one facet To get some values for a facet, pass the `name` of the facet and then pass the number of values you want as the `max` number of values you want. For example, you want to show five values for the product facet. The following is a sample request: ```JSON { "widget": { "items": [ { "rfk_id": "rfkid_7", "entity": "content", "search": { "facet": { "types": [ { "name": "product", "max": 5 } ] } } } ] }, "context": { "locale": { "country": "us", "language": "en" }, "user": { "uuid": "159871551-io-0i-4e-1p-s6ill6vhenvysbu27bbk-1664389956369" } } } ``` The following is the response to this request: ```JSON { "widgets": { "rfkid_7": { "facet": { "product": { "label": "Product", "value": [ { "id": "facetid_eyJ0eXBlIjoiZXEiLCJuYW1lIjoicHJvZHVjdCIsInZhbHVlIjoiRXhwZXJpZW5jZSBQbGF0Zm9ybSAoWFApIn0=", "text": "Experience Platform (XP)", "count": 137 }, { "id": "facetid_eyJ0eXBlIjoiZXEiLCJuYW1lIjoicHJvZHVjdCIsInZhbHVlIjoiRXhwZXJpZW5jZSBNYW5hZ2VyIChYTSkifQ==", "text": "Experience Manager (XM)", "count": 83 }, { "id": "facetid_eyJ0eXBlIjoiZXEiLCJuYW1lIjoicHJvZHVjdCIsInZhbHVlIjoiQ29udGVudCBIdWIifQ==", "text": "Content Hub", "count": 73 }, { "id": "facetid_eyJ0eXBlIjoiZXEiLCJuYW1lIjoicHJvZHVjdCIsInZhbHVlIjoiQ3VzdG9tZXIgRGF0YSBQbGF0Zm9ybSJ9", "text": "Customer Data Platform", "count": 68 }, { "id": "facetid_eyJ0eXBlIjoiZXEiLCJuYW1lIjoicHJvZHVjdCIsInZhbHVlIjoiT3JkZXJDbG91ZCJ9", "text": "OrderCloud", "count": 35 } ] } } } }, "dt": 38, "ts": 1666323029989 } ``` In the response `facet` object, you can see one facet, `Product` with five values. ## Get the top facets from a dynamic attributes collection To get the top values from a dynamic attributes collection, pass the dynamic attribute collection name as the `name`. You can also pass a `max` value to specify how many values you want to see. For example, you want to see the top five values from the `attribute_tags` dynamic attribute collection. The following is a sample request: ```JSON { "widget": { "items": [ { "rfk_id": "rfkid_7", "entity": "product", "search": { "facet": { "types": [ { "name": "attribute_tags", "max": 5 } ] } } } ] }, "context": { "locale": { "country": "us", "language": "en" } } } ``` The following is the response to this request: ```JSON { "widgets": [ { "rfk_id": "rfkid_7", "entity": "product", "facet": [ { "name": "attribute_tags.ID13", "label": "Material", "value": [ { "id": "facetid_eyJ0eXBlIjoiZXEiLCJuYW1lIjoiYXR0cmlidXRlX3RhZ3MuSUQxNyIsInZhbHVlIjoiVGV4dGlsZSJ9", "text": "Textile", "count": 3135 }, { "id": "facetid_eyJ0eXBlIjoiZXEiLCJuYW1lIjoiYXR0cmlidXRlX3RhZ3MuSUQxNyIsInZhbHVlIjoiUGxhc3RpYyJ9", "text": "Plastic", "count": 2852 }, { "id": "facetid_eyJ0eXBlIjoiZXEiLCJuYW1lIjoiYXR0cmlidXRlX3RhZ3MuSUQxNyIsInZhbHVlIjoiQWx1bWludW0ifQ==", "text": "Aluminum", "count": 2691 }, { "id": "facetid_eyJ0eXBlIjoiZXEiLCJuYW1lIjoiYXR0cmlidXRlX3RhZ3MuSUQxNyIsInZhbHVlIjoiUG9seWVzdGVyIn0=", "text": "Polyester", "count": 2220 }, { "id": "facetid_eyJ0eXBlIjoiZXEiLCJuYW1lIjoiYXR0cmlidXRlX3RhZ3MuSUQxNyIsInZhbHVlIjoiTGVhdGhlciJ9", "text": "Leather", "count": 2109 } ] }, { "name": "attribute_tags.ID354", "label": "Type - Engine", "value": [ { "id": "facetid_eyJ0eXBlIjoiZXEiLCJuYW1lIjoiYXR0cmlidXRlX3RhZ3MuSUQzNTYiLCJ2YWx1ZSI6IlR3aW4gQ2FtIFN0eWxlIn0=", "text": "Twin Cam Style", "count": 23137 }, { "id": "facetid_eyJ0eXBlIjoiZXEiLCJuYW1lIjoiYXR0cmlidXRlX3RhZ3MuSUQzNTYiLCJ2YWx1ZSI6IkV2b2x1dGlvbiBTdHlsZSJ9", "text": "Evolution Style", "count": 14384 }, { "id": "facetid_eyJ0eXBlIjoiZXEiLCJuYW1lIjoiYXR0cmlidXRlX3RhZ3MuSUQzNTYiLCJ2YWx1ZSI6Ik1pbHdhdWtlZS1FaWdodCAxMDcifQ==", "text": "Milwaukee-Eight 107", "count": 13086 }, { "id": "facetid_eyJ0eXBlIjoiZXEiLCJuYW1lIjoiYXR0cmlidXRlX3RhZ3MuSUQzNTYiLCJ2YWx1ZSI6Ik1pbHdhdWtlZS1FaWdodCAxMTQifQ==", "text": "Milwaukee-Eight 114", "count": 12629 }, { "id": "facetid_eyJ0eXBlIjoiZXEiLCJuYW1lIjoiYXR0cmlidXRlX3RhZ3MuSUQzNTYiLCJ2YWx1ZSI6Ik1pbHdhdWtlZS1FaWdodCAxMTcgICJ9", "text": "Milwaukee-Eight 117 ", "count": 10246 } ] }, { "name": "attribute_tags.ID2", "label": "Color", "value": [ { "id": "facetid_eyJ0eXBlIjoiZXEiLCJuYW1lIjoiYXR0cmlidXRlX3RhZ3MuSUQzIiwidmFsdWUiOiJCbGFjayJ9", "text": "Black", "count": 45536 }, { "id": "facetid_eyJ0eXBlIjoiZXEiLCJuYW1lIjoiYXR0cmlidXRlX3RhZ3MuSUQzIiwidmFsdWUiOiJHcmF5In0=", "text": "Gray", "count": 7904 }, { "id": "facetid_eyJ0eXBlIjoiZXEiLCJuYW1lIjoiYXR0cmlidXRlX3RhZ3MuSUQzIiwidmFsdWUiOiJCbHVlIn0=", "text": "Blue", "count": 6628 }, { "id": "facetid_eyJ0eXBlIjoiZXEiLCJuYW1lIjoiYXR0cmlidXRlX3RhZ3MuSUQzIiwidmFsdWUiOiJDaHJvbWUifQ==", "text": "Chrome", "count": 5021 }, { "id": "facetid_eyJ0eXBlIjoiZXEiLCJuYW1lIjoiYXR0cmlidXRlX3RhZ3MuSUQzIiwidmFsdWUiOiJXaGl0ZSJ9", "text": "White", "count": 4843 } ] } ... ] } ], "dt": 31, "ts": 1669044364271 } ``` In the response `facet` object, you can see two facet types, `attribute_tags.ID136` (U.S. size) and `attribute_tags.ID138` (gender), with many values in each. ## Get values from specific attributes of a dynamic attributes collection To get specific attributes from a dynamic attributes collection, pass the names of the specific attribute you want. For example, you want to get the `attribute_tags.ID18` and `attribute_tags.ID12` attributes from the `attribute_tags` dynamic attribute collection. The following is a sample request: ```JSON { "widget": { "items": [ { "rfk_id": "rfkid_7", "entity": "product", "search": { "facet": { "types": [ { "name": "attribute_tags.ID18" }, { "name": "attribute_tags.ID12" } ] } } } ] }, "context": { "locale": { "country": "us", "language": "en" } } } ``` The following is the response to this request: ```JSON { "widgets": [ { "rfk_id": "rfkid_7", "entity": "product", "facet": [ { "name": "attribute_tags.ID18", "label": "U.S. Size", "value": [ { "id": "facetid_eyJ0eXBlIjoiZXEiLCJuYW1lIjoiYXR0cmlidXRlX3RhZ3MuSUQxMyIsInZhbHVlIjoiTWVkaXVtIn0=", "text": "Medium", "count": 5166 }, { "id": "facetid_eyJ0eXBlIjoiZXEiLCJuYW1lIjoiYXR0cmlidXRlX3RhZ3MuSUQxMyIsInZhbHVlIjoiTGFyZ2UifQ==", "text": "Large", "count": 5003 }, ... ] }, { "name": "attribute_tags.ID12", "label": "Size", "value": [ { "id": "facetid_eyJ0eXBlIjoiZXEiLCJuYW1lIjoiYXR0cmlidXRlX3RhZ3MuSUQxNSIsInZhbHVlIjoiTGFyZ2UifQ==", "text": "Large", "count": 2513 }, { "id": "facetid_eyJ0eXBlIjoiZXEiLCJuYW1lIjoiYXR0cmlidXRlX3RhZ3MuSUQxNSIsInZhbHVlIjoiTWVkaXVtIn0=", "text": "Medium", "count": 2476 }, ... ] } ] } ], "dt": 531, "ts": 1669044284670 } ```