Parameters for the thematic API with JSON 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 operations such as boost/bury or slots do not work on * query parameters.
Parameter name |
Required |
Type |
Description |
Example |
---|---|---|---|---|
_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. |
uid=7797686432023:v=11.5:ts=1428617911187:hc=55 |
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. You must pass this parameter, but you can send it empty. | jazz_hands |
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 . |
br_server |
domain_key | yes | string | The Bloomreach-provided ID of the domain receiving the request. | example_com |
facet.range | no | integer | Specifies the facets that need to be returned as ranges, such as a price or sale price. | sale_price |
fl | yes | string | The fields returned with the search results, such as the name of products and prices. This value must be a comma-separated list. | pid,title,brand |
fq | no | string | Applies a faceted filter to search results, including only products with the specified attributes . You must surround the value with quotes. | brand:"Rebel in Rose" |
q | yes | string | The page theme name. | white%20dresses |
ref_url | yes | string | The URL of the HTTP referrer for the webpage where the request is made. |
http://www.example.com/ |
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 thematic. |
thematic |
rows | yes | integer |
The number of matching products (documents) returned per results page. The default value is 10. |
10 |
search_type | yes | string (enum) |
The type of the search. Use keyword. |
keyword |
sort | no | string |
Sorts results based on the field value in ascending, descending, or another combination of orders. |
sale_price desc |
start | yes | integer | The number of the first item on a page of results. For example, the first item on the first page is 0. | 0 |
url | yes | string | The absolute URL of the page where the request is made. |
http://www.example.com/popular/white-dresses.html |
user_agent | no | string | The user agent of the browser that's loading the thematic page. | |
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. | 947345478564 |
user_ip | no | string | The IP address of the browser that's loading the thematic page. If the browser is behind proxies, then provide a comma-separated list of proxy IP addresses, starting with the browser’s IP address. You can obtain the proxy IP addresses from the X-Forwarded-For HTTP header. |
22.22.22.22,40.1.2.30,50.10.20.30 |
wt | yes | string (enum) |
Specifies the type of response. Use json.
|
json |
More details
domain_key parameter
The domain_key parameter value is 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.
facet.range parameter
Your API responses can include ranged facets, some of which are defined in your request. Use the facet.range parameter:
&facet.range=price
Here's the corresponding response snippet, which shows you the number of items per price range:
"facet_ranges": { "price": [ { "count": 9, "start": "*", "end": 100 }, { "count": 0, "start": 100, "end": 200 }, { "count": 0, "start": 200, "end": 300 }, { "count": 0, "start": 300, "end": 400 }, { "count": 0, "start": 400, "end": "*" } ] }
You need to parse the values that are in the facets_counts section of the response. The facet_queries section has custom range facets for numeric fields that you define in your request. The facet_fields section gives you facets that you can display to your site's users, such as brands and colors.
In the example response snippet, the price facet shows you that there are nine products priced $0 - $100, and zero products priced in the other ranges.
fq parameter
The fq parameter applies a faceted filter to the returned products, searching for products that fit your parameter values. Any facet that you want to filter must be in your product feed.
Attributes must be enabled and mapped by Bloomreach
Let your Bloomreach TPM know which attributes in your product feed that you want to apply as filters to search results.
The fq parameter filters results to include only relevant items. For example, a major sports league has a website store that sells products to fans for every team in the league. The league has 32 teams, and each team has its own hats, t-shirts, jerseys, tchotchkes, cups, and many other items. Showing all of these items to a customer is overwhelming, causing customers difficulty when they try to find exactly what they're looking for. You can use the fq parameter in your API calls to suggest to customers only items from their own teams.
Surround attributes in your value with quotes. For example:
brand:"Fossil"
If the attribute in the efq parameter contains a space, surround the attribute with quotes. For example:
"Product Type":"1"
If you have multiple values, then surround the entire value with parentheses. For example:
brand:("Fossil" OR "Betsey Johnson")
Please note that if the value has a quote within it, then the quote should be escaped with '\', e.g. Sheet Dimension = 8.5" x 11".
In this case, the fq should be:
Sheet Dimension:"8.5\" x 11\""
In this case, the efq should be:
"Sheet Dimension":"8.5\" x 11\"" To apply filters for a ranged facet, such as price or sale price, the ranged value needs to be specified in addition to the product attribute. For example: to limit results to products with a price below 100:price:[* TO 100]
Or to limit results to products with a price between 200 and 300:
price:[200 TO 300]
q parameter
Values for q and fq parameters that have multiple words can use URL percent-encoded spaces (%20) between the words. For example:
&q=lace%20dresses
&fq=color:"light%20blue"
Don't separate words with plus signs (+) or hyphens (-). Use %20 or spaces.
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.
rows parameter
The rows parameter value is the number of matching products returned in each results page. In the API response, these products are in the docs section.
The default value is 10, and the maximum value is 500. To enhance performance, limit this value to the number of products that you think is reasonable for a single page of listings.
sort parameter
The sort parameter sorts results based on the field value in ascending, descending, or another combination of orders. You can use one of the following values:
-
sale_price desc sorts results in descending order of the sale price.
-
sale_price asc sorts results in ascending order of the sale price.
-
price_desc sorts results in descending order of the price.
-
price_asc sorts results in ascending order of the price.
-
launch_date desc sorts results in descending order of the date on which products launched.
-
launch_date asc sorts results in descending order of the date on which products launched.
user_agent and user_ip parameters
The user_agent and user_ip parameters identify the user agent and the IP address of the browser that's loading the thematic page. Make sure that these values in your API request are the same as in the original request from your user. We optimize pages in part by crawling and gathering data. The original user agent and IP lets us distinguish between our internal Bloomreach users who QA pages and everyone else who visits your site.
user_id parameter
The user_id parameter is a 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, Bloomreach recognizes users in a way that's aligned with your system. Use an anonymous string. Don't use email or other personally identifiable information. If you do not track users this way, then omit this field.