Milestone 4. API deployment - Bloomreach Experience - The Headless Digital Experience Platform Built for Commerce

Milestone 4. API deployment

Are you integrating only Insights features?

You can skip this entire milestone if you're integrating only Insights features.

Here's what we did before starting this milestone
  • Together we defined a detailed scope of the integration project.
  • You integrated the platform components on your site:
    • You deployed the JavaScript tracking pixel on all of your pages.
    • You generated and delivered your product feed. You continue to generate and deliver your feed daily.
  • Optional steps:
    • If required for your use cases, you generated and delivered your delta feed. You continue to generate deliver this supplemental delta feed hourly.

What happens in this milestone?

What you do What Bloomreach and you do together

You define your parameter values and deploy the APIs for the features you want to integrate on your site:

  • Bloomreach Search and Merchandising features:
    • Product search
    • Content search
    • Category search
    • Bestseller search
    • Pathways and Recommendations 
    • Autosuggest
    • MLT widget
    • JFY widget
  • Bloomreach SEO features:
    • Thematic Pages
    • Related categories, related items and related products widgets

We review your API deployments.

Bloomreach APIs

Bloomreach uses RESTful APIs to provide data for features on your mobile and desktop pages. You define these APIs for your site during the integration process. You can work on the APIs concurrently or in sequence, according to your own preference.

The APIs you use depend on which features you want to integrate on your site. Your Bloomreach representative reviews these features with you during integration kickoff. If you decide after kickoff to change which features you want to integrate, then let your Bloomreach representative know.

These APIs are performed over HTTP 1.1 protocol and the response is JSON-formatted.

API Reference

To view all the API endpoints and supported parameters, go to the API Reference section. 

Backend server

API responses must not be cached by your backend server. All of the services depend on receiving the latest context from the browser. In particular, personalized services depend on per-user cookie information that must not be shared across users.

Don't cache responses. Cached responses can delay or prevent newly deployed fixes or features from working on your site.

 The API sets a cookie to maintain user or session information. It is the responsibility of your backend server to pass this cookie to the browser and present this cookie to the API service in subsequent backend calls.

Environments and endpoints

Bloomreach Search and Merchandising exposes two environments to enable you to integrate and deploy: staging and production. A typical integration involves integrating against the staging servers. Before continuing to the Listen and tune milestone, you need to point your API servers to production servers. 

There are several servers for you to use. The endpoint or base URI differs according to which environment and which call you’re using.

Bloomreach is collaborating with Google Cloud for our Serving Infrastructure, so the Search, Category, and Content Search APIs will be using a new Google endpoint:

If you are a new customer: You can integrate to the new Google endpoint starting January 1, 2022.
If you are an existing customer: We plan to complete this migration before September 30, 2021. Please reach out to your account manager for further details.

If you cannot migrate before September 30, 2021, we recommend planning your migration for Q1 2022. The endpoint will continue to be supported until the end of Q1 2022.
Call Production Endpoint Staging Endpoint
All Search and Merchandising API calls (except Autosuggest calls), and JSON Thematic API calls
Autosuggest API calls
All brSEO API calls Please reach out to your TPM/TC to provide the brSEO endpoint
Pathways and Recommendations API calls{widget family}/{widget_id}{widget family}/{widget_id}

Bloomreach servers for HTTP requests reside at the production data center. Your Bloomreach representative provides your specific production endpoint in your integration package, which you receive at integration kickoff. The hostname is geographically close to your own data centers, reducing the latency of API requests and responses. For integration and performance testing, use the staging data center.

Sending special characters in "q" parameter in the API

The following is a summary of how special characters are treated when sent in the "q" parameter of the API:  

"q" definition Result
q=* [OK]
q=. [OK]
q=*term1  QUERY REWRITE to q=term1
q=term1*term2 QUERY REWRITE to q=term1 term2
q=term1~term2 QUERY REWRITE to q=term1 term2
q=term1?term2 QUERY REWRITE to q=term1 term2
q="" ERROR code 400
No q param ERROR code 400
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.

Below is a sample when the response is NOT ALLOWED:


    numFound : 0


    docs : []

    facet_ranges: { }

  facet_fields: {}


If you are an old customer, you can refer to the API Endpoints Changes Table. However, it is recommended that you use the new API endpoints for better performance.   

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?