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.

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.

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.

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.