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:
-
Define the URL pattern for your thematic pages.
-
Determine how to handle different user agents, such as those for mobile devices and desktops.
-
Make a server-side API call to the Bloomreach Commerce Organic thematic servers.
-
Extract the data from the JSON response.
-
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
- Thematic Pages
- Thematic page load process
- SEO strategies for thematic pages
- Deploy your thematic XML sitemap
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.
Pagination
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.
Sorting
Provides reference information about the sort parameter.
Endpoints
Production: https://core.dxpapi.com/api/v1/core/?
Staging: https://staging-core.dxpapi.com/api/v1/core/?
Example requests
GET https://core.dxpapi.com/api/v1/core/?
account_id=<Bloomreach Provided Account ID>
&auth_key=jazz_hands
&domain_key=example_com
&request_id=1093069556030
&url=http://www.example.com/index.html?q=womens%20black%20blazers
&ref_url=http://www.example.com
&_br_uid_2=uid%3D1920073709916%3Av%3D11.5%3Ats%3D1437651366100%3Ahc%3D2
&request_type=thematic
&search_type=keyword
&q=womens%20black%20blazers
&rows=10
&start=0
&fl=pid,title,brand,sku_swatch_images
{
"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": "http://www.example.com/thematic/full-theme-name/...",
"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\":
[{\"attribute_value\":\"sample_attribute_value_1\",\"url\":\"http://www.example.com/d/thematic_page.jsp?pgNm=example-theme-name-
1\",\"anchor_text\":\"anchor_text_1\"}]},{\"attribute_type\":\"sample_attribute_type_2\",\"heading\":\"By SampleAttributeType2
\",\"links\":[{\"attribute_value\":\"sample_attribute_value_2\",\"url\":\"http://www.example.com/d/thematic_page.jsp?pgNm=example-theme-
name-2\",\"anchor_text\":\"anchor_text_2\"},
{\"attribute_value\":\"sample_attribute_value_3\",\"url\":\"http://www.example.com/d/thematic_page.jsp?pgNm=example-theme-name-
3\",\"anchor_text\":\"anchor_text_3\"},
{\"attribute_value\":\"sample_attribute_value_4\",\"url\":\"http://www.example.com/d/thematic_page.jsp?pgNm=example-theme-name-
4\",\"anchor_text\":\"anchor_text_4\"},
{\"attribute_value\":\"sample_attribute_value_5\",\"url\":\"http://www.example.com/d/thematic_page.jsp?pgNm=example-theme-name-
5\",\"anchor_text\":\"anchor_text_5\"},
{\"attribute_value\":\"sample_attribute_value_6\",\"url\":\"http://www.example.com/d/thematic_page.jsp?pgNm=example-theme-name-
6\",\"anchor_text\":\"anchor_text_6\"}]}]}"
},
"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": [
23.93,
55.93
],
"variants": [
],
"price_range": [
99.99,
99.99
],
"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": [
44.93,
62.93
],
"variants": [
],
"price_range": [
89.99,
89.99
],
"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": [
9.93,
32.93
],
"variants": [
],
"price_range": [
49.99,
49.99
],
"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": [
42.74,
42.74
],
"variants": [
],
"price_range": [
129.99,
129.99
],
"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": [
19.93,
53.93
],
"variants": [
],
"price_range": [
34.97,
34.97
],
"description": "Description of this product"
}
]
},
"facet_counts":{
"facet_queries":{},
"facets":[
{
"name":"color_groups",
"type":"text",
"value":[
{
"name":"green",
"count":3
},
{
"name":"blue",
"count":1
}
]
},
{
"name":"final_price",
"type":"number_range",
"value":[
{
"start":0,
"end":150,
"count":0
}
]
}
]
}
"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": {
"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": "http://www.example.com/thematic/full-theme-name/...",
"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\":
[{\"attribute_value\":\"sample_attribute_value_1\",\"url\":\"http://www.example.com/d/thematic_page.jsp?pgNm=example-theme-name-
1\",\"anchor_text\":\"anchor_text_1\"}]},{\"attribute_type\":\"sample_attribute_type_2\",\"heading\":\"By SampleAttributeType2
\",\"links\":[{\"attribute_value\":\"sample_attribute_value_2\",\"url\":\"http://www.example.com/d/thematic_page.jsp?pgNm=example-theme-
name-2\",\"anchor_text\":\"anchor_text_2\"},
{\"attribute_value\":\"sample_attribute_value_3\",\"url\":\"http://www.example.com/d/thematic_page.jsp?pgNm=example-theme-name-
3\",\"anchor_text\":\"anchor_text_3\"},
{\"attribute_value\":\"sample_attribute_value_4\",\"url\":\"http://www.example.com/d/thematic_page.jsp?pgNm=example-theme-name-
4\",\"anchor_text\":\"anchor_text_4\"},
{\"attribute_value\":\"sample_attribute_value_5\",\"url\":\"http://www.example.com/d/thematic_page.jsp?pgNm=example-theme-name-
5\",\"anchor_text\":\"anchor_text_5\"},
{\"attribute_value\":\"sample_attribute_value_6\",\"url\":\"http://www.example.com/d/thematic_page.jsp?pgNm=example-theme-name-
6\",\"anchor_text\":\"anchor_text_6\"}]}]}"
},
"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": [
23.93,
55.93
],
"variants": [
],
"price_range": [
99.99,
99.99
],
"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": [
44.93,
62.93
],
"variants": [
],
"price_range": [
89.99,
89.99
],
"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": [
9.93,
32.93
],
"variants": [
],
"price_range": [
49.99,
49.99
],
"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": [
42.74,
42.74
],
"variants": [
],
"price_range": [
129.99,
129.99
],
"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": [
19.93,
53.93
],
"variants": [
],
"price_range": [
34.97,
34.97
],
"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": {
}
}
Customers whose go-live date is after September 7, 2023 will be on V3 Facet response format by default. If you’re on the legacy format and would like to implement the new Facet response format, kindly contact your Bloomreach Services representative.
Response objects
- 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.
Note the following objects in the response:
page_header object
| Element | What to do with the element |
|---|---|
| h1 | 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. |
| canonical_url | Populate the following meta element in the <head> section of the page with the URL provided: <link rel="canonical" href="ENTER URL HERE" /> |
| meta_description | Populate the content section with the values provided in the section of the page: <meta name="description" content="ENTER DESCRIPTION HERE"/> |
| meta_keywords | 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. |
| left_nav | 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 | What to do with the element |
|---|---|
| numFound | 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. |
| start | Indicates which product number to start with when serving the page. Page 1 starts at 0. |
| docs | 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, refer to pid element instead. |
| 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. |
| brand | Use the value in this field to serve the brand of the product within the product grid. |
| pid | 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. |
| product_link_rel | 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="http://www.example.com/product-327641.html" rel="nofollow">your text or image</a> If "product_link_rel":null, then omit rel from the product link: <a href="http://www.example.com/product-327641.html"\>your text or image</a> |
| sale_price_range | 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. |
| price_range | If you have a price range, then we provide the lowest and highest prices for you to put in the appropriate location. |
| description | 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.
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.
Encoding
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.
Caching
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.
Timeouts
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:
http://www.example.com/shop/gorgeous-red-cocktail-dresses
Then the site redirects the customer to the home page with a 302 response code, and uses the following URL:
http://www.example.com/?_thto=1
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.
Merchandising parameters
For a full list of the supported merchandising parameters on this API, refer to the Real-time API merchandising page.