Parameters for the thematic API with HTML responses
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 thematic API calls, not some.
Tip
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 options 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. |
jazz_hands |
acct_id |
yes | integer | The Bloomreach-provided ID for your account. | |
device_type |
yes | string | Specifies the type of the device that your customer is using to send the request. | desktop |
environment |
no | string |
Specifies the internal environment where Bloomreach returns a response. This value is always prod for thematic pages. |
prod |
page_name | yes | string | The dynamically-generated name of the thematic page. | white-dresses |
response_version |
yes | string | Specifies the template version. The default value is v1 . | v1 |
url | yes | string | The URL for the webpage that is sending the request. | http://www.example.com/white-dresses-th.html |
user_agent | yes | string |
The browser user agent, which lets Bloomreach track web crawling. |
Mozilla/5.0+%28compatible%3B+Googlebot%29 |
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.
device_type parameter
The device_type parameter specifies your customer’s device type. If you have different page templates for different devices, then Bloomreach returns a page formatted according to the appropriate page template. Here are some common values:
- desktop (default)
- mobile
- tablet
Extrapolate this parameter value from the HTTP headers supplied by your customer’s browsing request.
page_name parameter
The page_name parameter value is the dynamically-generated name of the thematic page that your customer is loading. Bloomreach extracts the name from the request page. Hyphens replace spaces in this value and there are no extra white spaces around the value.
You can append your thematic URL to your page_name parameter. Here's the recommended method:
Create a rule to rewrite any URL that has the pattern, http://www.example.com/page_name- your-thematic-url, to a single template on the server that receives page_name parameters. This template sends the request to the Bloomreach Thematic server, which returns the response.
response_version parameter
The response_version parameter specifies the template version. If you create a new design for your category page, then you can move your thematic pages to that new design. The default value is v1. New designs require you to increment or otherwise update this value.