Thematic API (JSON)

Getting thematic search results

Integration steps

The Bloomreach integration team meets with you to configure your thematic pages. Here are the essential steps that you follow with Bloomreach's guidance:

  1. Define the URL pattern for your thematic pages.

  2. Determine how to handle different user agents, such as those for mobile devices and desktops.

  3. Make a server-side API call to the Bloomreach Commerce Organic thematic servers.

  4. Extract the data from the JSON response.

  5. Construct the page for your user by inserting the data into your regular category page template.

Thematic integration checklist

  • Verify that the theme extraction from the incoming URL is correct.
  • Verify that API requests are formed correctly, and that all the required parameters and values are populated.
  • Verify that the raw API calls return valid JSON for a set of example pages.
  • Verify that responses have the right parameters.
  • Verify that responses render correctly.

Additional reading

What can I do with the 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.



Example requests

account_id=<Bloomreach Provided Account ID>
  "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": {


  • API requests should be limited to 16K Bytes. API requests above this length will throw Error Code 414.
  • Please note that the correct domain_key is mandatory in the API request. Starting March 2023, sending API requests without domain_key will return a 4xx error response.

Response objects

Note the following objects in the response:

page_header object

ElementWhat to do with the element
h1Fill in the on-page title with this value within the <h1> tags.
titleFill in the <title> tag located in the <head> section of the page with this value.
content_placement_1This 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_2This 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_3This 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.
canonical_urlPopulate the following meta element in the <head> section of the page with the URL provided:

<link rel="canonical" href="ENTER URL HERE" />
meta_descriptionPopulate the content section with the values provided in the section of the page:

<meta name="description" content="ENTER DESCRIPTION HERE"/>
meta_keywordsPopulate the content section with the values provided in the <head> section of the page:

<meta name="keywords" content="ENTER KEYWORDS HERE"/>
status codeConsume this status code to serve up the response when the page loads.
left_navThese 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

ElementWhat to do with the element
numFoundThis 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.
startIndicates which product number to start with when serving the page. Page 1 starts at 0.
docsA container for all the elements of an individual product served within the product grid.
sale_priceSale price of the product.
pricePrice of the product.
product_idDisregard, refer to pid element instead.
titleTitle of the product.
urlThe 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.
brandUse the value in this field to serve the brand of the product within the product grid.
pidThe product ID. Use this field to do any look-ups on your end.
thumb_imageThe URL that you use for the image in the product grid.
product_link_relThe 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>
sale_price_rangeIf you have a sale price range, then we provide the lowest and highest prices for you to put in the appropriate location.
variantsA list of variations of the product. For example, a list of the colors that a particular product has.
price_rangeIf you have a price range, then we provide the lowest and highest prices for you to put in the appropriate location.
descriptionThe 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.

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

The field and order is sent in the sort parameter.

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


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.

Click Try It! to start a request and see the response here!