This is the reference page for the Autosuggest v1 API, and should only be used if you integrated Autosuggest before October 7, 2020.
Endpoints
Production: https://suggest.dxpapi.com/api/v1/suggest/?
Staging: https://staging-suggest.dxpapi.com/api/v1/suggest/?
Example request and response
GET https://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
{
"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
}
}
GET https://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
{
"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"}
]
}
}
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.
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 &rsp_fmt=v2 when you need to use the new response format.
Check your format version
If you started your Commerce Search and Categories integration after October 2016, then your response format is in version 2 and you don't need the rsp_fmt parameter.
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.
{
"spellcheck": {
"suggestions": [
"lip",
{
"numFound": 80,
"startOffset": 0,
"endOffset": 5,
"suggestion": [
"dq=lipstick",
"dq=lipgloss",
/* truncated */
]
}
]
}
}
{
"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 */
]
}
}
_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.
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.