HomeEngagementContentDiscoveryOther resources
API reference

Facet Response V3 - Unified Ranking

As part of our 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 for Search API 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.0 parameter 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 identifierDescriptionNew facet response format (V3)Legacy facet format
numberThis 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_rangeThis 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_statsThis 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.

slider

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 } }
textThis 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":""
                }
            ]
        }

Pathways V3 Facet Response Changes


  1. In the V3 facet response format for Pathways (Search and Category widgets), all facets (except category) are unified in the facets object under the fields section.

  2. Earlier, the API response returned text and range facets separately in the fields and ranges sections respectively.

  3. Note that category appears as a separate section in both the legacy and V3 response formats.

    Facet type identifierDescriptionNew facet response format (V3)Legacy facet format
    numberThis displays the count of individual numeric facet values.{
    "facet": {
    "category": [ ],
    "fields": [
    {
    "key": "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": {
    "category": [],
    "fields": [
    {
    "key": "AveragePrice",
    "value": [
    {
    "count": 10, "name": "5.0"
    },
    {
    "count": 10, "name": "10.0"
    },
    {
    "count": 10,
    "name": "15.0"
    }
    ]
    }
    ],
    "ranges": []
    }
    number_rangeThis can be used to identify ranged facets. It displays the facet values as predefined range buckets and specifies the count for each bucket.{
    "facet": {
    "category": [ ],
    "fields": [
    {
    "key": "sale_price",
    "type": "number_range",
    "value": [
    {
    "start": "*",
    "end": "5",
    "count": 1257
    },
    {
    "start": "5",
    "end": "10",
    "count": 257
    },
    {
    "start": "10",
    "end": "20",
    "count": 127
    },
    {
    "start": "20",
    "end": "*",
    "count": 57
    }
    ]
    }
    ]
    }
    }

    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": {
    "category": [],
    "fields": [],
    "ranges": [
    {
    "key": "Price",
    "value": [
    {
    "count": 1257, "start": "*", "end": 5
    },
    {
    "count": 250, "start": 5, "end": 10
    }
    ]
    }
    ]
    }
    textThis displays the count of individual text facet values.{
    "facet": {
    "category": [ ],
    "fields": [
    {
    "key": "AverageRating",
    "type": "text",
    "value": [
    {
    "name": "Low",
    "count": 1257
    },
    {
    "name": "Average",
    "count": 886
    },
    {
    "name": "Good",
    "count": 2732
    },
    {
    "name": "Great",
    "count": 20718
    }
    ]
    }
    ]
    }
    }

    This example displays the count of the AverageRating facet values.    		"facet": {
    "category": [],
    "fields": [
    {
    "key": "Color",
    "value": [
    {
    "count": 10, "name": "Blue"
    },
    {
    "count": 15, "name": "Black"
    },
    {
    "count": 13, "name": "White"
    }
    ]
    }
    ],
    "ranges": []
    }