Autosuggest products - Bloomreach Experience - Open Source CMS

Autosuggest products

In pilot phase
This page is about a feature that is in pilot phase. Bloomreach does not guarantee that pilot phase features will become generally available as currently described. Your Bloomreach Representative can help you if you want to discuss pilot phase features.

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 eight products.

rsp_fmt parameter

Your autosuggest API responses are returned in either format version 1 or version 2. Product suggestions require version 2.

If you're using version 1, then you can set the rsp_fmt parameter value to v2 when you need to use the new response format:

&rsp_fmt=v2

For example, to create calls that return product suggestions, you need to use the new response format. You can't retrieve product suggestions in your API responses without using version 2.

Check your format version

If you started your Commerce Search and Categories integration after October 2016, then your response format is in version 2. You don't need the rsp_fmt parameter. 

If your integration started earlier than October 2016, then your response format is in version 1. You need to use the rsp_fmt parameter for product suggestions.

To confirm your format version, take a look at one of your autosuggest API responses. Version 1 has a spellcheck object, which includes a list of undifferentiated dq attribute-value pairs. Version 2 holds the data in a response object, which includes pairs of q and dq attribute-value pairs. Version 2 is easier to parse.


Example response snippet in format v1

{
  "spellcheck": {
    "suggestions": [
      "lip",
      {
        "numFound": 80,
        "startOffset": 0,
        "endOffset": 5,
        "suggestion": [
          "dq=lipstick",
          "dq=lipgloss",
  
/* truncated */
  
        ]
      }
    ]
  }
}


Example response snippet in format v2

{
   "response": {
    "q": "lip",
    "suggestions": [
      {
        "q": "lipgloss",
        "dq": "lipgloss"
      },
      {
        "q": "lipstick",
        "dq": "lipstick"
      },
    ],
  
/* truncated */
  
    "numFound": 80,
    "products": [
      {
        "url": "https://www.example.com/luscious-face-sheer-pout-touch-of-lip-color-c0999813065?_br_psugg_q=lipgloss",
        "sale_price": 21.99,
        "pid": "LFX345989",
        "thumb_image": "https://images.example.com/pics/catalog/product/cosmetics/lfsplc-LFX345989-color49-thumb.jpg",
        "title": "Lucious Face Sheer Pout Touch of Lip Color"
      },
      {
        "url": "https://www.example.com/shh-power-stance-full-coverage-lipstick-c0999659001?_br_psugg_q=lipstick",
        "sale_price": 17.29,
        "pid": "SXX450221",
        "thumb_image": "https://images.example.com/pics/catalog/product/cosmetics/spsfcl-SXX450221-mocha-thumb.jpg",
        "title": "Shh! Take a Power Stance Lipstick (full coverage)"
      }
  
/* truncated */
  
    ]
  }
}

Your Bloomreach Representative can tell you which format version you're using, and can help you determine when to switch from the old response format to v2.


_br_psugg_q attribute

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.
 

Example API request and response

Here's an example autosuggest call that retrieves products as well as suggested queries:

Example API request for keyword and product suggestions

GET http://brm-suggest-0.brsrvr.com/api/v1/suggest/?
account_id=<Bloomreach Provided Account ID>
&auth_key=
&domain_key=example_com
&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

The response includes a JSON array for products. 

Example API response for keyword and product suggestions

{
    "responseHeader":
        {
            "status": 0,
            "QTime": 4
        },
    "response": {"q": "pen",
    "suggestions":
    [
        {"q": "pens","dq": "pens",
            "filters": [{"name": "Pens","value": "Pens","key": "Department"}]},
        {"q": "pencils","dq": "pencils",
        {"q": "mechanical pencils","dq": "mechanical pencils"},
        {"q": "black pens","dq": "black pens"},
        {"q": "pencil sharpener","dq": "pencil sharpener"}
    ],
    "products":
    [
        {"pid":"354001283", "url":"http://www.example.com/pid=354001283?_br_psugg_q=pens", "title":"Blue fine point rollerball pen", "price":"28$","image_url":"www.example.com/354001283"},
        {"pid":"354001316", "url":"http://www.example.com/pid=354001316?_br_psugg_q=pens", "title":"Black fine point rollerball pen", "price":"28$","image_url":"www.example.com/354001316"}
        {"pid":"354001401", "url":"http://www.example.com/pid=354001401?_br_psugg_q=pens", "title":"Red fine point rollerball pen", "price":"28$","image_url":"www.example.com/354001401"}
        {"pid":"354030028", "url":"http://www.example.com/pid=354030028?_br_psugg_q=pens", "title":"Blue gel pen", "price":"31$","image_url":"www.example.com/354030028"}
        {"pid":"354030041", "url":"http://www.example.com/pid=354030041?_br_psugg_q=pens", "title":"Black gel pen", "price":"31$","image_url":"www.example.com/354030041"}
    ]
    }
}

 

Troubleshooting: Product suggestions aren't in my API response

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. 

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?