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>.brcdn.com/fetch_thematic/ <acct_id>/ <acct_auth>/ <environment>/ <device_type>/ <response_version>/ <page_name>.html? user_agent=<user_agent> &url=<url>
- Add the following header to your request so that you receive a compressed response: Accept-Encoding: gzip, deflate.
Here's what the call looks like with sample data:
Example thematic search request
GET http://example-0123-e.brcdn.com/fetch_thematic/ <Bloomreach Provided Account ID>/ jftyf00gh3pi0000j/ prod/ desktop/ v1/ white-dresses.html? user_agent=Mozilla%2F5.0+%28compatible%3B+Googlebot%29 &url=http://www.example.com/popular/white-dresses-th.html
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
- http://www.example.com/popular/white-dresses-th.html 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:
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:
<!-- BEGIN HTML-HEADER --> <title>Title of the Page</title> <meta name="robots" content="noindex" /> <link rel="canonical" href="http://www.example.com/popular/white-dresses-th.html" /> <link rel="stylesheet" type="text/css" href="http://www.example.com/css/sample.css" /> <!-- END HTML-HEADER --> <!-- BEGIN HTML-BODY --> <div> ... <left column content> <product display similar to your category page display> ... </div> <!-- 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.
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.
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.
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.