Parameters for the Widget API
Quick reference for all parameters
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 widget API calls, not some.
You can escape non-alphanumeric characters in your parameter values, using URL percent-encoding conventions.
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.
Parameter Name |
Required |
Type |
Description |
Example |
---|---|---|---|---|
acct_auth |
Yes | String | The Bloomreach-provided authentication key for your account ID. |
jftyf00gh0pi0273j |
acct_id |
Yes | Integer | The Bloomreach-provided ID for your account. | |
prod_id |
No | String |
The unique identifier for the product in your product catalog or database. This parameter affects product pages only. Not needed for category requests. |
white-crochet-lace-trim-dress-477903 |
prod_name | No | String |
The name of the product in your product catalog or database. Not needed for category requests. |
Stunning white gown |
pstatus |
No | String (enum) |
The status of a product on the page. Use one of the following values:
This parameter affects product pages only. |
outofstock |
ptype | Yes | String (enum) |
The page type. Use one of the following values:
|
product |
ref | Yes | String | The URL of the HTTP referrer for the webpage where the request is made. | http://www.example.com/ |
url | Yes | String | The URL for the webpage that is sending the request. | http://www.example.com/white-dresses.html |
user_agent | Yes | String |
The browser user agent, which lets Bloomreach track web crawling. |
Mozilla/5.0+%28compatible%3B+Googlebot%29 |
output_format | No | String |
The format in which you'd like to recieve the reponse. Currently, two formats are supported:
Note: If you do not specify the output_format then by default, Bloomreach will send you the response in the HTML format.
|
br_json |
More details
acct_auth and acct_id parameters
The values for the acct_auth and acct_id parameters are the same for all of your licensed Bloomreach products. The parameter names are different, but the values are the same. Make sure that you're using the correct parameter names for your licensed Bloomreach products.
api_host parameter
The api_host parameter is the endpoint that Bloomreach provides for your API calls. During integration testing, this value is bsapi-test.brsrvr.com. The test server displays test Widget data that Bloomreach supplies. After testing, Bloomreach gives you your own unique value for the api_host parameter.
ref parameter
The ref parameter is the URL of the HTTP referer for the webpage where the request is made. This parameter facilitates Bloomreach traffic attribution. If the value is not available, then leave this parameter empty.
user_agent parameter
The user_agent parameter is the browser agent, which Bloomreach extracts from the User-Agent HTTP header. This parameter lets Bloomreach know when your pages are crawled by search engines. Take this parameter value directly from the HTTP headers supplied by your customer's browser request.