Autosuggest API

📘

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 V1 API reference page.

What is Autosuggest?

Autosuggest guides site visitors by providing search term suggestions, which are sometimes called autocomplete or type-ahead, in a dropdown list as visitors type in a search box. These suggestions become increasingly refined with each character entered. When visitors see a suggested query in the dropdown list, they can stop typing and select the query.

Suggestions are interactive. Site visitors can select a query from the autosuggest list as soon as they see one that fits their needs. The list relies on the characters visitors are currently typing as well as past search query data aggregated from all site visitors. Autosuggest results in less typing for visitors and helps them refine vaguely formed queries.

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:

ParameterDescription
queryContextThe metadata of the API call that provides context to the query. This can consist of parameters such as originalQuery.
suggestionGroupsContent 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:

  • query - The suggested query.

  • displayText - Display text for the suggested query.


  • query and displayText typically have the same value, except when there are special characters.

    attributeSuggestions(RHS suggestions): Suggestions corresponding to different attributes(facets). Currently only supported for product catalog.
    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:

    value
    name: Display text for the suggested category.
    key

    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.
    Language
    Click Try It! to start a request and see the response here!