Parameters for the autosuggest API
Are you integrating your native mobile app with Bloomreach?
Some of the parameters in your API requests for native mobile apps need different values from those for your site:
- _br_uid_2: Leave your _br_uid_2 parameters empty.
- ref_url: Leave your ref_url parameters empty.
- url: Use a dummy value for your url parameters, such as exampledomain.app.
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.
|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|
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.
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.
|domain_key||Yes||String||The Bloomreach-provided ID of the domain receiving the request.||example_com|
|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|
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.
|rsp_fmt||No||String||Specifies that the response is returned in format version 2, which is easier to parse and needed for retrieving product suggestions. You can omit this parameter if you're already using version 2.||v2|
|No||String||A unique identifier for a view of the product catalog. Use a string that identifies the specific site catalog view for your customer.||k-3|
|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|
Some of the request parameters need a little more explanation than others. You can find this extra information here.
The Bloomreach-provided ID of the domain receiving the request. This parameter identifies the specific site version when the one account ID hosts multiple site versions with unique characteristics, such as language versions. Bloomreach uses your domain_key parameter value to ensure that only the data that pertains to that site version is used for query and analytics features, such as autosuggestions.
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.
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.
The view_id parameter is a unique identifier for a specific view of your product catalog. If you have multiple versions of your site, each with their own product catalog characteristics like product titles and prices, then add view_id to your call. Bloomreach uses your view_id parameter value to display the right product information for your customers based on their individual site views.
You can enter any string value to identify the specific site catalog view. This string must be consistent in your pixel, API, and product catalog. For example, Abacus Thinking sells different academic products to different grade levels. A first grade teacher looks in their Kindergarten through Grade 3 catalog, which Abacus Thinking assigns the ID, k-3:
Consistent, valid values
Your view_id values must be the same in your API, pixel, and product catalog. If Abacus Thinking assigns the value, kindergarten-3rd, to the view_id parameter in their product feed, then the API value, k-3, doesn't match any catalog view.
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.
Disclaimer for items marked, "In Pilot Phase"
Please note that this product or feature is in pre-release “pilot phase” and is made available to select participants from time to time for the purpose of providing feedback on the quality and usability of the “pilot phase” product or feature (the “Pilot Products”). Pilot Products are still undergoing final testing and evaluation and ARE PROVIDED ON AN “AS IS” AND “AS AVAILABLE” BASIS WITHOUT ANY WARRANTIES, WHETHER EXPRESS OR IMPLIED, AS TO THE QUALITY, SUITABILITY, USABILITY MERCHANTABILITY, NON-INFRINGEMENT, ACCURACY, COMPLETENESS, PERFORMANCE AND FITNESS FOR A PARTICULAR PURPOSE OF THE PRODUCT OR FEATURE AND WILL NOT BE LIABLE FOR ANY LOSS, WHETHER SUCH LOSS IS DIRECT, INDIRECT, SPECIAL OR CONSEQUENTIAL, SUFFERED BY ANY PARTY AS A RESULT OF THEIR USE OF THE PRODUCT OR FEATURE. Bloomreach is not obligated to offer any maintenance, technical or other support on the Pilot Products, continue to offer any Pilot Products, or announce or make available a commercial version of the Pilot Products to anyone in the future. Should a commercial version be made available, it may have features or functionality that are different from those found in the Pilot Products.
Should you encounter any bugs, glitches, lack of functionality or other problems with respect to the Pilot Products, please let us know immediately so we can rectify these accordingly. Your help in this regard is greatly appreciated.