Product and Category suggestions

Product Suggestions

You can suggest products along with queries in your autosuggest API calls. When a visitor to your site begins typing a query, the autosuggest call retrieves a text-based list of queries as well as products.

By default, the response includes a maximum of 8 products. Keyword suggestions are in the querySuggestions field and product suggestions are in the searchSuggestions field.

Example request and response

GET https://suggest.dxpapi.com/api/v2/suggest/?
account_id=<Bloomreach Provided Account ID>
&auth_key=
&catalog_views=product:store1
&request_id=7546919099987
&_br_uid_2=uid%3D5917073780329%3A_uid%3D9737480431795%3Av%3D11.8%3Ats%3D1459840113832%3Ahc%3D37
&url=www.example.com
&ref_url=http://www.example.com/
&q=pen
&request_type=suggest

{
  "queryContext": {
    "originalQuery": "pen"
  },
  "suggestionGroups": [
    {
      "catalogName": "product",
      "view": "store1",
      "searchSuggestions": [
        {
            "url": "http://www.example.com/pid=354001283?_br_psugg_q=pens",
            "sale_price": 28,
            "pid": "354001283",
            "thumb_image": "www.example.com/354001283.jpg",
            "title": "Blue fine point rollerball pen"
        },
        {
            "url": "http://www.example.com/pid=354001316?_br_psugg_q=pens",
            "sale_price": 28,
            "pid": "354001316",
            "thumb_image": "www.example.com/354001316.jpg",
            "title": "Black fine point rollerball pen"
        }
      ],
      "querySuggestions": [
        {
            "query": "pens",
            "displayText": "pens"
        },
        {
            "query": "pencils",
            "displayText": "pencils"
        }
      ],
    }
  ]
}

`_br_psugg_q` Parameter

When a site visitor selects a product suggestion, the product page opens. The URL for this product page must include the attribute, br_psugg_q=autosuggest query from the API response, where _autosuggest query is the first query suggestion. By default, product suggestions are powered by the first query suggestion. This attribute allows us to tag and track product suggestion sessions.

Typically, Bloomreach returns the product URL in the suggest API response and automatically adds the _br_psugg_q attribute. However, you need to confirm that the final URL for the product page includes this parameter, and append it to the URL if it's absent.

What if my API response does not contain product suggestions?

Normally, your suggestion API responses include both suggested queries and suggested products. 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 product 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.

Category Suggestions

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, and contains objects of:

value and attributeType: Form the filtered search API request when a site visitor clicks a suggestion.
name: Display text for the suggested category.

Example response

"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"
          },
    ]
  }
]

What if my API response does not contain category suggestions?

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.