Parameters for the autosuggest API - Bloomreach Experience - Open Source CMS

Parameters for the autosuggest API

 Are you integrating your native mobile app (or other non-JS environment) with Bloomreach?

Some of the parameters in your API requests for native mobile apps or non-JS environment need different values from those for your site:

  • _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

Quick reference

This table provides a list of each parameter and a description. A yes flag in the Required column indicates that the parameter is required for all autosuggest calls, not some.  

Parameter Name





account_id Yes Integer The Bloomreach-provided ID of the account sending the request.  
auth_key Yes String The Bloomreach-provided authentication key for the account sending the request. Because Autosuggest calls are client-side, you can send it empty. empty
_br_uid_2 Yes String

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 percent encode this parameter.


callback No String (enum)

Indicates whether to return data wrapped into the function when making cross-origin requests.

If you have a server-side integration, then use the value, br_server. If you have a native-app integration, then use the value, br_app.

catalog_views Yes String 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.


q Yes String The customer's partial query. a
ref_url Yes String The URL of the HTTP referrer for the webpage where the request is made. You must pass this parameter, but you can send it empty.

request_id Yes String A random ID that enables click-tracking. Use 12 or 13 digits. 1597706996836
request_type Yes String (enum)

The request type. Use suggest, which is a list of suggestions for an input string or query. For example, query=sh might return shoes, women shoes, men shoes and black shoes.

url Yes String The absolute URL of the page where the request is made.

user_agent No String The user agent of the browser that's making the search request.  
user_id No String The universal customer ID of the user. You only need to pass this field if your particular integration tracks customers this way. 00000

Detailed reference

Some of the request parameters need a little more explanation than others. You can find this extra information here. 

request_id parameter

The request_id parameter value is a random 12 or 13-digit ID that you supply to enable click-tracking. Bloomreach doesn't automatically enforce the requirements for this parameter. For example, you can enter  test  as your value for each instance of the request_id parameter without triggering an error message. However, if you don't use a unique value, then Bloomreach can't help you with potential problems you might experience while using the API.

user_id parameter

The user_id parameter is the universal customer ID of a user. The parameter captures user IDs from the customer side, and reuses the information when powering apps or enhancing cross-device linking. In this way, Commerce Search and Categories recognizes users in a way that's aligned with your system. Use an anonymous string with 12 or 13 numeric characters. Don't use email or other personally identifiable information. If you do not track users this way, then omit this field.

catalog_views parameter

The catalog_views parameter is the 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 catalog_views. 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).

catalog_views value
Example: &catalog_views=product:store1,store2|recipe:premium|articles

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

The output for the example value would be text and attribute suggestions for the product catalog in the store1 view, and for the recipe catalog in the premium view. Only text suggestions will be displayed for the articles catalog.
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?