Build a JSON thematic results page - Bloomreach Experience - The Headless Digital Experience Platform Built for Commerce

Build a JSON thematic results page

Getting thematic search results

This page shows you an example request and response that can help you form your own thematic API calls for your site. If you need more information about thematic parameters, then take a look at the quick reference table, which describes the parameters and provides example values.


Search use cases has a lot of information about what you can do with search API requests and responses, including thematic searches with JSON responses.


During integration kickoff, Bloomreach gives you an example API request that's customized with your account information. You can use that example request by adding your own values to the remaining parameters.

Here's an example thematic search API call:

account_id=<Bloomreach Provided Account ID>

All of the parameters in the example are required parameters for all thematic calls with JSON responses. Your own thematic calls might include optional parameters, but they must always include these parameters, too. As a thematic search query, the following parameters must be defined with specific values: 

  • request_type must be set to  thematic
  • q must be set to the page theme name, such as  womens%20black%20blazers

Escape characters and encoding

You can escape non-alphanumeric characters in your parameter values, using URL percent-encoding conventions. Values for query parameters that have multiple words can use URL percent-encoded spaces (%20) between the words. For example:



/ %2F
( %28
; %3B
) %29

q and fq parameter values with %20 encoding


Here's another example, this time with several different escape characters for the  user_agent  parameter:

user_agent parameter value with multiple escape characters


The values for some parameters, such as fq, require double quote marks ( " ) around them. If the value you're specifying includes double quotes, then you need to escape those double quotes with a backslash ( \ ) before the value's double quotes. For example:

Escape double quotes

&fq=size:"8.5\" by 11\" "

The _br_uid_2 cookie is already encoded

Don't encode the cookie parameter value: _br_uid_2. Use this value exactly as it comes. It's already encoded.


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 Cartidge user, then your response is not compressed.

Response processing

HTML header

The whole HTML header section from the response needs to be inserted into the HTML header of the page even if your page already has these same HTML elements. Replace the contents, don’t duplicate them. 

Bloomreach examines the content of the page to determine whether a page should exist or not. If a page is duplicative or does not have enough products, then Bloomreach sends a noindex tag in the response.

Don’t hardcode noindex meta tags; consume what is sent in the response.


The thematic search API response is Unicode UTF-8 encoded. If your site doesn’t interpret the response accordingly, then strange characters appear in the browser when the response is processed.


Never cache 4xx nor 5xx responses

Do not cache client (4xx) nor server (5xx) responses to your thematic API requests.

To ensure the best personalization experience for your site's users, we recommend that you don't cache thematic API responses. If necessary, you can cache success (2xx) responses, but never cache 4xx nor 5xx responses.

If you must cache your 2xx responses, then we recommend that you set the cache to expire in one hour. The maximum period is 24 hours to ensure that the data is current.


We recommend that you set the timeout for your thematic pages to 2 seconds.

If there's a timeout during a thematic page load, then we recommend that you redirect your customer with a HTTP 302 response code to your site's home page. Append this specific tracking parameter redirected the URL: ?_thto=1. This parameter serves a few purposes: 

  • It ensures that your customers always receive a page load.

  • It collects data to assist Bloomreach in troubleshooting timeouts. 

For example, let’s say that the following page encounters a timeout error when loading:

Then the site redirects the customer to the home page with a 302 response code, and uses the following URL:

Your Bloomreach TPM can work with you to determine the ideal timeout setting for your requirements.


Full example response

You can download the example response if you want a fuller view.

  "page_header": {
    "h1": "heading of this page",
    "title": "title of this page",
    "content_placement_1": "<!-- Html content block 1 -->",
    "content_placement_2": "<!-- Html content block 2 -->",
    "content_placement_3": "<!-- Html content block 3 -->",
    "robots_meta_tag": "index, follow",
    "canonical_url": "",
    "meta_description": "the meta description of the page",
    "meta_keywords": "keywords that can be used to target the page",
    "status_code": 200,
    "left_nav": "{\"product_name\":\"sample_product_name\",\"heading\":\"sample_heading\",\"attribute_groups\":
    [{\"attribute_type\":\"sample_attribute_type_1\",\"heading\":\"By SampleAttributeType1\",\"links\":
    1\",\"anchor_text\":\"anchor_text_1\"}]},{\"attribute_type\":\"sample_attribute_type_2\",\"heading\":\"By SampleAttributeType2
  "response": {
    "numFound": 5,
    "start": 0,
    "docs": [
        "sale_price": 69.99,
        "price": 99.99,
        "product_id": "example_product_id_1",
        "title": "example_title_1",
        "url": "http://product_url_of_this_product",
        "brand": "brandofthisproduct",
        "pid": "example_product_id_1",
        "thumb_image": "http://thumb_image_url_of_this_product",
        "product_link_rel": null,
        "sale_price_range": [
        "variants": [
        "price_range": [
        "description": "Description of this product"
        "sale_price": 69.99,
        "price": 89.99,
        "product_id": "example_product_id_2",
        "title": "example_title_2",
        "url": "http://product_url_of_this_product",
        "brand": "brandofthisproduct",
        "pid": "example_product_id_2",
        "thumb_image": "http://thumb_image_url_of_this_product",
        "product_link_rel": null,
        "sale_price_range": [
        "variants": [
        "price_range": [
        "description": "Description of this product"
        "sale_price": 29.99,
        "price": 49.99,
        "product_id": "example_product_id_3",
        "title": "example_title_3",
        "url": "http://product_url_of_this_product",
        "brand": "brandofthisproduct",
        "pid": "example_product_id_3",
        "thumb_image": "http://thumb_image_url_of_this_product",
        "product_link_rel": null,
        "sale_price_range": [
        "variants": [
        "price_range": [
        "description": "Description of this product"
        "sale_price": 68.49,
        "price": 129.99,
        "product_id": "example_product_id_4",
        "title": "example_title_4",
        "url": "http://product_url_of_this_product",
        "brand": "brandofthisproduct",
        "pid": "example_product_id_4",
        "thumb_image": "http://thumb_image_url_of_this_product",
        "product_link_rel": null,
        "sale_price_range": [
        "variants": [
        "price_range": [
        "description": "Description of this product"
        "sale_price": 34.97,
        "price": 34.97,
        "product_id": "example_product_id_5",
        "title": "example_title_5",
        "url": "http://product_url_of_this_product",
        "brand": "brandofthisproduct",
        "pid": "example_product_id_5",
        "thumb_image": "http://thumb_image_url_of_this_product",
        "product_link_rel": null,
        "sale_price_range": [
        "variants": [
        "price_range": [
        "description": "Description of this product"
  "facet_counts": {
    "facet_queries": {
      "{!ex=width}width:[* TO 17]": 0,
      "{!ex=width}width:[17 TO 25]": 0,
      "{!ex=width}width:[25 TO 33]": 4,
      "{!ex=width}width:[33 TO *]": 1,
      "{!ex=depth}depth:[* TO 17]": 5,
      "{!ex=depth}depth:[17 TO 25]": 0,
      "{!ex=depth}depth:[25 TO 33]": 0,
      "{!ex=depth}depth:[33 TO *]": 0,
      "{!ex=sale_price}sale_price:[* TO 400]": 0,
      "{!ex=sale_price}sale_price:[400 TO 800]": 3,
      "{!ex=sale_price}sale_price:[800 TO 1200]": 0,
      "{!ex=sale_price}sale_price:[1200 TO 2000]": 1,
      "{!ex=sale_price}sale_price:[2000 TO *]": 1,
      "{!ex=s_percentageOff}s_percentageOff:[1 TO *]": 4,
      "{!ex=s_percentageOff}s_percentageOff:[30 TO *]": 3,
      "{!ex=s_percentageOff}s_percentageOff:[40 TO *]": 3,
      "{!ex=s_percentageOff}s_percentageOff:[50 TO *]": 2,
      "{!ex=s_percentageOff}s_percentageOff:[60 TO *]": 2,
      "{!ex=s_percentageOff}s_percentageOff:[70 TO *]": 0,
      "{!ex=height}height:[* TO 17]": 5,
      "{!ex=height}height:[17 TO 35]": 0,
      "{!ex=height}height:[35 TO 55]": 0,
      "{!ex=height}height:[55 TO *]": 0
    "facet_fields": {
      "color_groups": [
      "brand": [
          "count": 28,
          "name": "brand1"
          "count": 1,
          "name": "brand2"
          "count": 1,
          "name": "brand3"
          "count": 1,
          "name": "brand4"
      "item_condition": [
          "count": 26,
          "name": "new"
          "count": 26,
          "name": "old"
    "facet_dates": {
    "facet_ranges": {
  "stats": {
    "stats_fields": {
      "sale_price": {
        "max": 11111.11,
        "min": 11.11
  "sort_fields": [
    "reviews asc",
    "reviews desc",
    "discount asc",
    "discount desc",
    "title asc",
    "title desc",
    "best_seller asc",
    "best_seller desc",
    "sale_price asc",
    "sale_price desc",
    "price asc"
  "did_you_mean": [
  "category_map": {

page_header object

Element name

What do you do with the element


Fill in the on-page title with this value within the <h1> tags.

title Fill in the <title> tag located in the <head> section of the page with this value.
content_placement_1 This element is a reserved spot above the <h1> tag on the page for accepting HTML content. You can curate the page with the Bloomreach Pages tool.
content_placement_2 This element is a reserved spot below the <h1> tag on the page for accepting HTML content. You can curate the page with the Bloomreach Pages tool.
content_placement_3 This element is a reserved spot below the product grid on the page for accepting HTML content. You can curate the page with the BloomReach Pages tool.

Populate the following meta element in the <head> section of the page with the URL provided: 

<link rel="canonical" href="ENTER URL HERE" />


Populate the content section with the values provided in the <head> section of the page:

<meta name="description" content="ENTER DESCRIPTION HERE"/>


Populate the content section with the values provided in the <head> section of the page:

<meta name="keywords" content="ENTER KEYWORDS HERE"/>

status code Consume this status code to serve up the response when the page loads.

These are links to other thematic pages. These links go into the left nav below the facets and look like this after you parse the response:

 Shop Crystal Lamps

 By Brand

 Swarovski (link)

 Schonbeck (link)

 By Style

 Modern (link)

response object 

Element name

What do you do with the element


This is the number of products that were found for this page. You can use this number in the logic to display the appropriate number of products per page if you have pagination.


Indicates which product number to start with when serving the page. Page 1 starts at 0.


A container for all the elements of an individual product served within the product grid.

sale_price Sale price of the product;
price Price of the product.
product_id Disregard.
title Title of the product.
url The URL that points to the product detail page. Use this URL for both the title of the product and the image of the product. Use the URL for any links that appear in the quick view.

Use the value in this field to serve the brand of the product within the product grid.


The product ID. Use this field to do any look-ups on your end.

thumb_image The URL that you use for the image in the product grid.

The product_link_rel element can have one of two values: null or nofollow. If "product_link_rel":nofollow, then set rel="nofollow" in the product link:

<a href="" rel="nofollow">your text or image</a>

If "product_link_rel":null, then omit rel from the product link:

<a href="">your text or image</a>


If you have a sale price range, then we provide the lowest and highest prices for you to put in the appropriate location.

variants A list of variations of the product. For example, a list of the colors that a particular product has.

If you have a price range, then we provide the lowest and highest prices for you to put in the appropriate location.


The quick view is in HTML and contains this product description.

facet_counts object 

The facet_counts object includes nested objects for facet_queries and for facet_fields. The facet_queries object is internal to Bloomreach, so don't consume this part of the response.

The facet_fields object contains all of your facet objects, such as color, brand, and more. Break out each of these objects based on how your category template lays out the page. The facet_fields object is customizable.

The following example returns individual brands in the name field and the number of items for each brand in the count fields:

                    count: 28,
                    name: "Rockabilly Grace"

stats object

You can use the stats object if you want to use a slider on your filtering. When you form the request, use the stats.field parameter and assign it one of these values: price or sale_price.

sort_fields array

The sort_fields array is customizable to sort the page in ascending or descending order of the following fields:

  • best_seller

  • discount
  • price
  • reviews
  • sale_price
  • title

For example, here's a request snippet that displays the results on a thematic page with the top rated items first:

&sort=reviews desc

What can I do with a thematic API call?

Thematic API calls with JSON responses give you many options, including these:

Display banners, assets, and campaigns in search results

Provides reference information about the campaign JSON object in API responses.

Faceting and filtering

Provides reference information about the fq, efq, and facet.range parameters.


Provides reference information about the start and row parameters.

Requesting product and SKU attributes

Provides reference information and a use case about the fl parameter and its effect on product and SKU attributes in response doc arrays.


Provides reference information about the sort parameter.

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.

Preview unavailable when migrated to JSON Thematic Page 

If you migrate from the HTML Thematic Page to JSON Thematic Page, the Preview option will not be available. Note that this limitation is valid only for customers that migrate their integration from HTML Thematic Page to JSON Thematic Page. 

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?