Using faceted search
To request a facet, add a widget.items.search.facet object to your request.
Before you can get facets, make sure that an administrator configures attributes for facets in Search.
For the data model of this object, see the Search and Recommendation API reference.
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:
{
"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:
{
"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:
{
"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:
{
"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:
{
"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:
{
"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:
{
"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:
{
"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
}