Deprecated - Widget API Integration Guide - Bloomreach Experience - The Headless Digital Experience Platform Built for Commerce

Deprecated - Widget API Integration Guide

Deprecated Widget API Integration
The following is an old integration guide for Organic Widgets used by customers who integrated before April 2018. It contains integration details for Related Searches and Related Products. It is to be used for reference purposes ONLY and is no longer the suggested integration for Organic Widgets. Please refer to Widget API for the most up to date details on integrating the Organic Widgets which include how to integrate Related Categories, Related Items and Related Products.

What are related searches and related products widgets? 

Related searches and related products are widgets that you place on your mobile and desktop sites to enhance discoverability and user value. The widget for related searches optimizes your link structure, and the widget for related products optimizes your page content.

Text on product results is usually in a form like JavaScript that isn't always readable by search engine bots. When a customer views your site, the widget API provides data to populate the related searches and related products widgets on the page. Each link in the related searches widget is highly relevant both to the page it's on and the page it's pointing to. These links create a relationship from one page to the next, assisting users and search engines to find new relevant pages. Each product in the related products widget includes a picture, title, and a lead-in snippet with a view more link to expose a popup of the description of the product.

The title and description of related products are readable by search bots, increasing the likelihood of discovery by bots. The links for related searches flatten your site's hierarchy for bots, making it easier for them to crawl your site.

Here are some of the methods we use to populate the content of your related searches and related products widgets:

  • Examine relationships between products and categories on your site.
  • Analyze your product attributes to link similarly patterned items together.

You need just one widget API call for both related searches and related products.

Related searches

The widget for related searches adds relevant links to your category and product pages, flattening the structure of your site. This widget helps web crawlers easily discover other related pages from this single page as well as pass on the strength or authority from this single page to these other pages, helping them to rank and receive more organic search traffic from search engines.

This widget is particularly helpful to users who don't immediately find exactly what they're looking for on a particular page. For example, a customer named Lucia searches your site with the query, white dresses. The list of related searches on the category page or product page might include wedding gowns, summer dresses, and lace dresses. Lucia can click these links to find more pages that are highly relevant to her search for the perfect white dress.  

The number of searches that you can have in your related searches widget is fixed at six. Bloomreach always tries to display the maximum number of links in the related searches widget. However, the widget shows fewer links if we can't find relevant product pages to link to, or if the products in those linked pages go out of stock.

Display requirements for related searches widgets

For each link within related searches, the following requirements apply:

  • Clearly display the entire link or anchor text. Do not truncate any of the link or anchor text with ellipses. For example: blue lace dres...
  • Show all the links that are in the widget and do not truncate the list. For example, don't show three links upon page load followed by a link or button to show more or show fewer links.

Related products

The widget for related products adds products on relevant category and product pages. The related products widget leverages your site’s product content, adding it to relevant pages to enrich the content on those pages with additional and unique content. Adding this content helps these pages rank in additional searches when customers make queries on search engines.

For example, Dresses by Colette sells a pink dress called Sweet in Pink on its product page. This product appears on multiple category and product pages in the related products widget. The content for this product is served in HTML and is readable by search engines. As a result, when Lucia uses a search engine to find a hi-lo pink dress, chances are increased that Dresses by Colette's Sweet in Pink product appears in her search results.

The default number of products you can have in your related products widgets is four. Let your Bloomreach TPM know if you want to display more than four products. Bloomreach always tries to display the maximum number of products in the related products widget. However, the widget shows fewer products if we can't find relevant products that match the content of the page, or if products in the widget go out of stock.

Upon page load of every page, the related products widget must be visible to site visitors and search engine bots. This widget contains individual items that each include information like a product title, product image, preview of the product description, and a quickview link. When a site visitor clicks the quickview link, a popup HTML lightbox displays detailed content, including the product title, product image, and an expanded product description.

Location and appearance of widgets

During the integration process, the Bloomreach integration team meets with you to establish the location and appearance of your related searches and related products widgets on your product, category, and mobile pages.

Category pages

The recommended placement for the related searches widget is in the left navigation area. The recommended placement for the related products widget is below the product grid, but above the footer. Here's an example of the recommended placement for the widgets on category pages.


SEO strategies for related searches and related products widgets

Put widgets on your mobile pages.

 Widgets must be integrated on your mobile pages. Bloomreach supports widgets on mobile devices if your mobile URL structure after the domain name is the same as the structure for your desktop URLs. We use relative URLs in our widget links. If you have a separate mobile site, please ensure widgets are integrated on there as well.

Make server-side calls.

 Widget API calls are always server-side calls.

 Don't create client-side calls.

Use both widgets.

 Both the Related Searches and Related Products widgets are required on the page to realize maximum value from the product.

Don't hide the widgets.

 Make sure that the widgets are visible upon page-load for both site visitors and search engines. 

 Don't hide the widgets inside a tab or other locations that require interaction with the page before they appear. Attempting to hide or obscure these widgets is contrary to the guidelines provided by search engines.

 Site visitors and search engine bots must see the same widget in the same location upon page-load.

 Make sure you show all elements of the widgets, including text and images, to both visitors who access your site and search engine bots who crawl your site.

 Never place the widgets in obscure locations on the site, such as the footer.

 Don't style widgets in a way that masks them from sight, such as using a font color that's similar to the background color.

Don't use JavaScript nor AJAX in widget content.

 Widgets must be implemented in HTML. Search engines don't understand or value JavaScript and AJAX as highly as HTML content.

 Don't implement widget content in JavaScript nor AJAX.

Build a related searches and related products widget

Getting widget results

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

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.

Form of a widget call

GET http://<api_host>/v2/fetch_widget?










Example widget request



&acct_id=<Bloomreach Provided Account ID>









Bloomreach returns HTML in response to the request.

Response processing

The body contains valid HTML that can be directly inserted in the page on the server side. This HTML is deliberately kept simple, offering maximum compatibility with the rest of your page. 

Your call might not return any content for related searches or related products. The response still contains the JavaScript variable, br_related_rid. Make sure that this variable is displayed in the page's HTML for tracking purposes.

Bloomreach supports widgets on mobile devices only if your mobile URL structure is the same as the structure for your desktop URLs. API responses can return relative URLs to support mobile versions. You can apply regular mobile styling to render the response.


You need to parse the response and place each widget in an appropriate location on the page. You can style your related searches and related products widgets by entering styles in your global CSS file.

The related products widget needs a lead-in or snippet of the product description with the rest of description in a quick view popup. Use one of the following techniques:

  • Recommended method: Add the CSS and JavaScript snippets to the widget API response for popup functionality.
  • Alternative method: Put the snippets in your own CSS and JavaScript files, and ensure that these files appear on the pages that contain the related products widget.


You can cache widget API responses. Set the cache to expire within a period of 24 hours maximum to ensure that the data is current.

Error handling for the widget API


Error handling for both timeouts and errors must be in place to have a graceful exit.

If there are timeouts or lookup failures for remote API calls, then you need to omit related categories, related items and related products widgets from category, product and mobile views.


Timeouts are set at 750 milliseconds.


You must set up error handling for scenarios in which an API call returns a non-200 response, such as 404 or 500.

Parameters for the widget API

Quick reference for all parameters

This table provides a list of each parameter and a description. A yes flag in the Required column indicates that the parameter is required for all widget API calls, not some.

More details

acct_auth and acct_id parameters

The values for the acct_auth and acct_id parameters are the same for all of your licensed Bloomreach products. The parameter names are different, but the values are the same. Make sure that you're using the correct parameter names for your licensed Bloomreach products.

api_host parameter

The api_host parameter is the endpoint that Bloomreach provides for your API calls. During integration testing, this value is The test server displays test Widget data that Bloomreach supplies. After testing, Bloomreach gives you your own unique value for the api_host parameter.

ref parameter

The ref parameter is the URL of the HTTP referer for the webpage where the request is made. This parameter facilitates Bloomreach traffic attribution. If the value is not available, then leave this parameter empty.

user_agent parameter

The user_agent parameter is the browser agent, which Bloomreach extracts from the User-Agent HTTP header. This parameter lets Bloomreach know when your pages are crawled by search engines. Take this parameter value directly from the HTTP headers supplied by your customer's browser request.

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?