Build an HTML thematic results page - Bloomreach Experience - The Headless Digital Experience Platform Built for Commerce

Build an HTML 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.


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.

Form of a thematic call for HTML results

GET http://<thematic_host>


- Add the following header to your request so that you receive a compressed response: Accept-Encoding: gzip, deflate. 

If you are a Demandware Cartidge user, then you don't need to add this header.

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

Here's what the call looks like with sample data:

Example thematic search request

<Bloomreach Provided Account ID>/

Here are the example values for the call:

  • example-0123-e is the host
  • <Bloomreach Provided Account ID> is the account ID
  • jftyf20gh3pi0273j is the authentication key
  • prod is the environment
  • desktop is the device type
  • v1 is the response version
  • white-dresses is the page name
  • Mozilla%2F5.0+%28compatible%3B+Googlebot%29 is the user agent
  • is the URL

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\" "

Example truncated response

Bloomreach returns styled HTML 

in response to the request. The response consists of a header and a body of valid HTML that you need to parse and put into your body content.

The example request’s corresponding response looks like this:

Response snippet

<title>Title of the Page</title>
<meta name="robots" content="noindex" />
<link rel="canonical" href="" />
<link rel="stylesheet" type="text/css" href="" />
  <left column content>
  <product display similar to your category page display>
<!-- END HTML-BODY -->
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.

API Response with Zero products

If you receive an API response and the number of products that match the theme is 0, you will have to set up behavior so that the page triggers a timeout.

Response processing

Bloomreach examines metrics like bounce rates and conversion rates to determine how well a page performs. If a page has suboptimal performance, then Bloomreach applies noindex meta tags. Therefore, 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. 

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 representative can work with you to determine the ideal timeout setting for your requirements.

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