Parameters for the thematic API with JSON responses - Bloomreach Experience - The Headless Digital Experience Platform Built for Commerce

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.


You can escape non-alphanumeric characters in your parameter values, using  URL percent-encoding conventions.

Using * query
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





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


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 .

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.

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.

rows yes integer

The number of matching products (documents) returned per results page. The default value is 10.

search_type yes string (enum)

The type of the search. Use 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.

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.,,

wt yes string (enum)

Specifies the type of response. Use 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:


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.

More information: fq syntax
Surround attributes in your value with quotes. For example:
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:



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. 

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?