Content AutoSuggest API - Bloomreach Experience - Open Source CMS

Content AutoSuggest API

In Pre-Launch Phase
This page is a part of the Content Search (data-based) feature that is slated for launch in Q3 2020. To know more about this feature and activate/purchase the add-on module, please reach out to your Bloomreach representative.

This API returns autosuggestions when a user searches for content (blogs, articles, videos) on your site. The suggestions appear as a dropdown list while users type a search term in the search box. 

API Endpoint

Use the API endpoint given below:

GET

http://suggest.dxpapi.com/api/v2/suggest/

Example Request

GET

http://suggest.dxpapi.com/api/v2/suggest/account_id=<Bloomreach Provided Account ID>&auth_key=jazzhands&request_id=1234567890000&_br_uid_2=uid=7797686432023:v=11.5:ts=1428617911187:hc=55&url=www.example.com&ref_url=www.example.com&q=sa&catalog_views=product_exampleen_1234:US

Path Params

The table given below contains a list of path parameters that you can send in the Content Autosuggest API. Some of them are mandatory and some are optional.  

Parameter Details
_br_uid_2

A first-party cookie created by the Bloomreach tracking pixel library (BrTrk). This cookie creates a unique, anonymous identifier for every browser or device.

Don't encode the cookie parameter value: _br_uid_2. Use this value exactly as it comes. It's already encoded.

 &_br_uid_2=uid%3D7797686432023%3Av%3D11.5%3Ats%3D1428617911187%3Ahc%3D55

Value type

String

Example value

&_br_uid_2=uid%3D7797686432023%3Av%3D11.5%3Ats%3D1428617911187%3Ahc%3D55

Required

Mandatory

account_id

Your site's numerical Bloomreach account ID. Your Bloomreach representative gives your site's account ID to you before or during your integration kickoff meeting.

Notify your Representative
If you don't have a Bloomreach account ID, then let your Bloomreach representative know immediately. You can't send any API calls without your account ID.

Value type

Integer

Example value

&account_id=<Bloomreach Provided Account ID>

Required

Mandatory

auth_key

The Bloomreach-provided authentication key for the Bloomreach account that's sending the request.

Value type

string

Required

Mandatory

Example value

&auth_key=jazzhands

Your own auth_key value looks very different from this example. We're using an odd example value to reinforce the importance of treating this key like you treat other keys like your email login credentials. Please do not share it.

url

The absolute URL of the page where the request is initiated.

Use the absolute URL
Don't use a relative URL for your url parameter value.

Value type

string

Example value

&url=http://www.example.com/index.html?query=dresses

Required

Mandatory

q

Your site visitor's search query. Search queries are composed of one or more terms.

Tip
You can percent encode spaces between terms, or you can leave the spaces the way they are. The correct code is %20 if you choose to percent encode spaces in multi-term search queries.

Value type

string

Example value

&q=popcorn

catalog_views

A list of catalog views that you want to see in your suggestions. You must specify the catalog name within the catalog view. A catalog is the named identifier.

If you have multiple catalogs (ie: product catalog and content catalog) for which you'd like to display text suggestions, those catalog names need to be specified as the value within the catalog_view. If you have specific views (view_id) within each catalog (ie: store1, store2 or basic, premium), you can specify them under catalog_views as well.

Suggestions fall under 2 categories: text and attributes (ie: item, category, facet). Attributes suggestions are enabled for the first two catalogs mentioned as part of catalog_views and only for the first view passed in each of the first two catalogs.

You can enter any string value to identify the specific catalog view. This string must be consistent in your pixel, API, and catalog(s).

Value type

String, with view_ids within a catalog separated by a colon. To show multiple catalogs in a call, they must be pipe-separated.

Required

Mandatory

Example value

&catalog_view=product:store1,store2|recipe:premium|articles

The output for the previous example would be text and attribute suggestions for product catalog in store1 view and for recipe catalog in premium view. Only text suggestions from the articles catalog will display.

Sample Response

{
  "queryContext": {
    "originalQuery": "sa"
  },
  "suggestionGroups": [
    {
      "catalogName": "products",
      "view": "store1",
      "searchSuggestions": [
        {
            "url": "https://www.example.com/us/shop/catalog/product/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"
            }
        ]
    }
  ]
}


Response Entities

The Content Autosuggest API implementation has the following basic entities in the response: 

Parameter 

Description

Example

queryContext

The metadata of the API call that provides context to the query. This can consist of parameters such as originalQuery.

{
    "originalQuery": "sa"
  },
 

suggestionGroups

 

 

 

 

 

 

 

 

 

 

 

 

 

     

 

    

Content suggestion items for every catalog view pair.

a. catalogName: The catalog name is the name of the item. 

b. View: The view of the element inside the catalog and being queried for.

c. searchSuggestions: Search Suggestion contains search documents. Currently, it can only be supported for catalog_name=product.

d. querySuggestions:Query suggestion items which are filtered from the Bloomreach dictionaries. Contains objects of: 

  • query - Query stored inside dictionaries.
  • displayText - Display text for the query.

e. attributeSuggestions(RHS suggestions): Suggestions corresponding to different attributes(facets). Currently supported for catalog_name=products.



 

product/recipes/news/articles.

Using * query
When you use the query '*' as 'q=*' in the API request, the latency of the response will vary depending on your catalog size and it may not adhere to the Bloomreach's standard SLA. Further, please note that except for include/exclude operation, other merchandising operations such as boost/bury or slots do not work on * query parameters.
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?