As part of our latest facet enhancements initiative, we have improved the facet response format. Earlier, the API response returned text and range facets separately in facet_fields and facet_ranges objects, respectively.
The new response format merges all facets together, irrespective of whether it is a numeric or a text facet. All the facets are now unified in the facets object. We’ve also introduced additional capabilities that allow the Bloomreach algorithm to retrieve and rank numeric facets along with other text facets in the API response under the single response object.
The facet type identifiers and format changes are summarized in the table below.
Customers whose go-live date is after September 7, 2023 will be on V3 Facet response format by default.
Older customers can use this new facet response format by simply passing an additional
facet.version=3.0parameter to the Bloomreach Search and Merchandising APIs.
After testing the parameter on your API Requests, you can choose to migrate to this format easily by requesting your Bloomreach POC to switch the flag internally to version 3.0.
| Facet type identifier | Description | New facet response format (V3) | Legacy facet format |
|---|---|---|---|
| number | This displays the count of individual numeric facet values. | … “facet_counts”: { "facets": [ { "name": "AveragePrice", "type": "number", "value": [ { "name": "5.0", "count": 1257 }, { "name": "10.0", "count": 886 }, { "name": “15.0", "count": 2732 }, { "name": "100.0", "count": 10658 }, { "name": "200.0", "count": 20718 } ] } This example displays the count of the AveragePrice facet values. | … "facet_counts": { "facet_fields": { "bvAverageRating": [ { "name": "1.0", "count": 1257 }, { "name": "2.0", "count": 886 }, { "name": "3.0", "count": 2732 }, { "name": "4.0", "count": 10658 }, { "name": "5.0", "count": 20718 } ] } |
| number_range | This can be used to identify ranged facets. It displays the facet values as predefined range buckets and specifies the count for each bucket. | … “facet_counts”: { "facets": [ { "name": "sale_price", "type": "number_range", "values": [ { "start": "*", "end": 5, "count": 59 }, { "start": 5, "end": 10, "count": 2176 }, { "start": 10, "end": 20, "count": 6464 }, { "start": 20, "end": "*", "count": 131981 } ] } In this example, the values for the facet sale_price are displayed as range buckets - * to 5 - 5 to 10 - 10 to 20 - 20 to * | ... "facet_counts:": { "facet_ranges": { "sale_price": [ { "start": "*", "end": 5, "count": 59 }, { "start": 5, "end": 10, "count": 2176 }, { "start": 10, "end": 20, "count": 6464 }, { "start": 20, "end": "*", "count": 131981 } ] } |
| number_stats | This can be used to identify the numeric facets that display a slider widget. The slider has a maximum and minimum value. Sliders allow shoppers to adjust the filter range. You can control this via the API directly using the stats.field parameter. Note: For integrations after September 7, 2023, this can also be controlled via the dashboard. Live customers can control this only via API. However, if you need dashboard controls, you can contact Bloomreach Services to migrate to the new facet response. | … “facet_counts”: { "facets": [ { "name": "drill_length", "type": "number_stats", "value": { "start": 0.19, "end": 7937.99, "count": 10 } } In this example, the facet “drill_length” will be displayed as a slider with a minimum value of 0.19 and a maximum value of 7937.99. | "facet_counts:" :{ "stats":{ "stats.field":{ "sale_price":{ "max":2449.99, "min":0.69 }, "price":{ "max":2449.99, "min":0.69 }, "MARGIN_VALUE":{ "max":0.91, "min":0 } } |
| text | This displays the count of individual text facet values. | … “facet_counts”: { "facets": [ { "name": "AverageRating", "type": "text", "value": [ { "name": "Low", "count": 1257 }, { "name": "Average", "count": 886 }, { "name": “Decent", "count": 2732 }, { "name": "Good", "count": 10658 }, { "name": "Great", "count": 20718 } ] } This example displays the count of the AverageRating facet values. | … "facet_counts": { "facet_fields": { "colors": [ { "name": "Black", "count": 1 }, { "name": "blue", "count": 1 }, { "name": "Brown", "count": 1 }, { "name": "gold", "count": 1 } ] } |
NOTE: There is no change to the format of category facets. The category field includes properties such as cat_id, cat_name, crumb, etc., which are similar to the Legacy format.
"facet_counts":{
"facets":[
{
"name":"category",
"type":"text",
"value":[
{
"cat_id":"sale",
"cat_name":"Sale",
"crumb":"/sale",
"tree_path":"/sale,Sale",
"count":6294,
"parent":""
}
]
}
"facet_fields":{
"category":[
{
"cat_id":"sale",
"cat_name":"Sale",
"crumb":"/sale",
"tree_path":"/sale,Sale",
"count":6294,
"parent":""
}
]
}