Autosuggest Categories - Bloomreach Experience - The Headless Digital Experience Platform Built for Commerce

Autosuggest Categories

Suggestions with Categories

If an autosuggest query includes categories, then the response includes an attributeSuggestions array. This array helps your site visitors to filter their search results according to categories.

The fields in the JSON filters are name, value, and key. The values for these fields are all strings. The name field value is the suggestion displayed in browsers. The key and value fields form the filtered search API request when a site visitor clicks a suggestion.

attributeSuggestions array example

"suggestionGroups": [
    "catalogName": "products",
    "view": "store1",
    "querySuggestions": [
          "query": "atlas",
          "displayText": "atlas"
    "attributeSuggestions": [ {            
              "value": "mountain_bars",
              "name": "mountain_bars",
              "attributeType": "category"
              "value": "cranksets",
              "name": "cranksets",
              "attributeType": "category"

Example customer experience

Natalie is shopping at All Things, a very large online retailer of both popular and niche general merchandise. Her children own a vintage red wagon that needs a replacement wheel. She can find that wheel more quickly and easily if suggestions are filtered by categories than without. 

Natalie intended to enter the query, wheel replacement for antique red wagons. But All Things has a good idea of what she might want long before she types all of that. Here are their suggestions after she types just  wheel:

Wheels in Toys

Wheels in Bicycles

Wheels in Auto Parts

Wheels in Luggage

Wheels in Games  

roulette wheel

old timey wagon wheel earrings

spinner wheeled suitcase


crazy wheels


racing wheels

hot wheels

off road wheels

exercise wheel

The first query suggestions are filtered by category, and the other suggestions are unfiltered queries, one of which is simply, wheels. While that suggested query can be useful, its results might include every wheel and wheeled product that All Things sells. If Natalie had no idea what kind of wheel she needs, then that query's results might help her figure out how to narrow her search. 

But Natalie never even notices the suggested wheels query so she doesn't waste time pondering how to filter its results. Right at the top, she sees the category query, Wheels in Toys . She clicks that query, which sends a search API call, and the response brings her to set of relevant search results. In seconds, she's looking at a product page for vintage red wagon replacement wheels. Success!

Troubleshooting: Category suggestions aren't in my API response

Normally, your suggestion API responses include both suggested queries and suggested categories. Rarely, you might see only query suggestions returned, such as when the prefix isn't in the cache. As soon as a prefix is encountered, a cache entry is created, and both query and category suggestions are returned in responses. In the meantime, you need to make sure that your integration supports displaying only query suggestions.

Your Bloomreach representative can help you if you need more information.

Did you find this page helpful?
How could this documentation serve you better?
On this page
    Did you find this page helpful?
    How could this documentation serve you better?