Autosuggest V1 API - Bloomreach Experience - Open Source CMS

Autosuggest V1 API

This is the reference page for the Autosuggest V1 API, and should only be used if you integrated Autosuggest before October 7, 2020.

Example request

Here’s an example API call for an autosuggest query, starting with the single letter, a:

Request

GET http://suggest.dxpapi.com/api/v1/suggest/?
account_id=<Bloomreach Provided Account ID>
&auth_key=jazzhands
&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=a
&request_type=suggest


Example response

Here's an example JSON response for the autosuggest query:

Response

{
"responseHeader": {
    "status": 0,
    "QTime": 0
},
"response": {
    "q": "a",
    "suggestions": [
        {
            "q": "atlas",
            "dq": "atlas",
            "filters": [
                {
                    "name": "Mountain Bars",
                    "value": "Mountain Bars",
                    "key": "Department"
                },
                {
                    "name": "Cranksets",
                    "value": "Cranksets",
                    "key": "Department"
                }
            ]
        },
        {
            "q": "raceface atlas",
            "dq": "raceface atlas"
        },
        {
            "q": "reynolds attack",
            "dq": "reynolds attack"
        },
        {
            "q": "fox attack q4 short",
            "dq": "fox attack q4 short"
        },
        {
            "q": "atlas handlebar",
            "dq": "atlas handlebar"
        }
    ],
    "numFound": 21
}
}

Suggestions

The list of suggestions in the response is in the response JSON object. The value of the suggestions  field is an array of suggested queries and associated category suggestions. All queries are in this form:

"q": "suggested query",

"dq": "UI display query"

In the response, q field values are suggested queries and dq field values are display queries. A display query is the suggested query rendered for display in browsers.

Typically, q and dq values are the same. They usually differ when there are special characters in the q value that need to be rendered for your site visitors.

The dq values are relevant for displaying suggested queries in the browser. When your site visitor clicks a suggestion in the browser, that suggestion is the dq value. Upon clicking a suggestion, your site visitor initiates a search API call. That call is formed with the q value, not the dq value. 

Suggestions with Categories

If an autosuggest query includes categories, then the response includes a filters 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.

Filters array example

"suggestions": [
        {
            "q": "atlas",
            "dq": "atlas",
            "filters": [
                {
                    "name": "Mountain Bars",
                    "value": "Mountain Bars",
                    "key": "Department"
                },
                {
                    "name": "Cranksets",
                    "value": "Cranksets",
                    "key": "Department"
                }
            ]
        },


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

wheels

crazy wheels

wheelchair

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.

Suggestions with Products

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://suggest.dxpapi.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?