Thematic API (JSON)

The Bloomreach-provided authentication key for the Bloomreach account that's sending the request. Leave auth_key parameter values empty for client-side calls If you use client-side calls for any of your Bloomreach requests, then do not enter an auth_key value in those client-side calls. Pass the auth_key with an empty value in client-side calls. The auth_key value is a private authorization key. If you include your valid auth_key value in client-side calls, then you inadvertently expose that private information to everybody.

A first-party cookie created by the Bloomreach tracking pixel library (BrTrk). This cookie creates a unique, anonymous identifier for every browser or device. Use the default value provided, which is already encoded.

Your site domain's ID, which is provided by Bloomreach. This ID is for the domain that you want to receive your Bloomreach API requests. 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.

The example value shown here, documentation_site, is included for your convenience to send a request with Try It.

The attributes that you want returned in your API response, such as product IDs and prices. All fl parameters must include pid as one of their values. Any attribute from your product feed may be used as a value for fl. Multiple values should be comma separated, such as fl=pid,price.

The page theme name. You can percent encode spaces between terms as %20, or you can leave the spaces unencoded. If you use q=, the latency of the response will vary depending on your catalog size and it may not adhere to Bloomreach's standard SLA. Additionally, most merchandising operations do not work on query parameters, except for include/exclude operations.

The example value shown here, jack%20chains, is included for your convenience to send a request with Try It.

The URL of the page or HTTP referrer where the request is started.

An ID to track site visitor clicks. We recommend that you generate unique, random values of 13 digits 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, using a unique value allows us to help you if you encounter a problem.

The type of API request. Value should be thematic for Thematic requests.

The type of search. Value should be keyword for Thematic requests.

The absolute URL of the page where the request is initiated. Do not use a relative URL.

The example value shown here, https://www.documentation-site.com, is included for your convenience to send a request with Try It.

Specifies the type of response. Use json for the JSON Thematic API.

Indicates whether to return data wrapped in the function for cross-origin requests. For server-side requests, use the value br_server. For native-app requests, use the value br_app.

If you're sending a thematic search API request, but not receiving a response, add &debug=true to your request and resend it. When a theme is pending QA, &debug=true triggers the thematic server to send the JSON response.

The response is gzip compressed. You need to uncompress the response to use the contents. If you are a [Demandware Cartridge] (https://www.salesforce.com/products/commerce-cloud/overview/?cc=dwdcmain) user, then your response is not compressed.

Return a count of ranged facets, such as price and sale price. Use numeric attributes only. 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.

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 feed. Read more about using the fq parameter in the "Simple Filtering" section in the Faceting and filtering page.

You can configure Attributes from the Catalog Management Tab. Configure which attributes in your content feed you want to apply as filters to search results.

Sorts results based on the field value in ascending, descending, or another combination of orders. You can sort any fl field. Value is a field name, followed by asc/desc for ascending/descending order respectively. For example, sort=sale_price desc sorts in descending order of the sale price

The user agent of the browser that's making the search request. Make sure that this value in your API request is the same as the value in the original request from your user.

We optimize pages in part by crawling and gathering data, and the original user_agent lets us distinguish between our internal Bloomreach users who QA pages and everyone else who visits your site.

The universal customer ID of the user. You only need to pass this field if your particular integration tracks customers this way. 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.

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.

Make sure that this value in your API request is the same as the value in the original request from your user. We optimize pages in part by crawling and gathering data, and the original user_ip lets us distinguish between our internal Bloomreach users who QA pages and everyone else who visits your site.