For detailed information on the Autosuggest feature and how it works, refer to its guide here .
If you integrated Autosuggest before October 7, 2020, you should refer to the Autosuggest API v1 reference page.
Run in Postman
Easily import the Discovery API collection and try the endpoints in Postman. It offers many examples of how the endpoints can be used for different use cases.
Follow this quick step-by-step guide to set up the environment and use the APIs: Postman Collections Welcome Kit
OpenAPI spec
The detailed OpenAPI specification for the Autosuggest API v2 can be found on GitHub:
Endpoints
Production: https://suggest.dxpapi.com/api/v2/suggest/?
Staging: https://staging-suggest.dxpapi.com/api/v2/suggest/?
Example request and response
GET https://suggest.dxpapi.com/api/v2/suggest/?
account_id=<Bloomreach Provided Account ID>
&auth_key=jazzhands
&request_id=7546919099987
&catalog_views=my_product_catalog:store1|recipe:daily
&_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=sa
&request_type=suggest #Value must be suggest for Autosuggest API
{
"queryContext": {
"originalQuery": "sa"
},
"suggestionGroups": [
{
"catalogName": "my_product_catalog",
"view": "store1",
"searchSuggestions": [
{
"url": "https://www.example.com/us/shop/catalog/my_product_catalog/salsa_sauce/2000306000?_br_psugg_q=sauce",
"sale_price": 12.9,
"pid": "2000000000",
"thumb_image": "https://www.example.com/images/1_front_000/00300011-01.jpg",
"title": "Mexican Salsa Sauce"
}
],
"querySuggestions": [
{
"query": "salsa sauce",
"displayText": "Salsa sauce"
}
],
"attributeSuggestions": [
{
"value": "/sauce,sauce/salsa_sauce,salsa_sauce",
"name": "/sauce,sauce/salsa_sauce,salsa_sauce",
"attributeType": "category"
}
]
},
{
"catalogName": "recipe",
"view": "daily",
"querySuggestions": [
{
"query": "Spicy salsa sauce",
"displayText": "spicy salsa sauce"
},
{
"query": "salsa sauce",
"displayText": "Salsa sauce"
}
]
}
]
}
{
"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"
}
]
}
]
}
API requests should be limited to 16K Bytes. API requests above this length will throw Error Code 414.
Note the following 2 parameters in the response:
| Parameter | Description |
|---|---|
| queryContext | The metadata of the API call that provides context to the query. This can consist of parameters such as originalQuery. |
| suggestionGroups | Content suggestion items for every catalog view pair. catalogName: The name of the item. View: The view of the element inside the catalog and being queried for. searchSuggestions: Contains search documents, supported for product or content catalogs. querySuggestions: Query suggestion items which are filtered from the Bloomreach dictionaries. Contains objects of:
|
| attributeSuggestions (if categories are included) | 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. Contains objects of:
|
Native mobile app and non-JS Integration
API requests for native mobile apps or non-JS environments need different values for some parameters:
- _br_uid_2: The value should be the same as described on the Cookie page. Generate a br_uid_2 for your app user and store it in the app permanently if a br_uid_2 does not exist. This br_uid_2 should be used on the corresponding API calls for the app. If the user is on iPhone and resets their IDFA, or if the user is on an Android device and resets their advertising settings: the br_uid_2 should be erased and regenerated the next time the app is set.
- ref_url: Leave your ref_url parameters empty.
- url: Use a dummy value for your url parameters, such as exampledomain.app.