Bloomreach Search and Merchandising 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.

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.

📘

Old endpoints

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.

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:

When you use q=* in the API request, the latency of the response will vary depending on your catalog size and it may not adhere to 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.

{
    numFound : 0
    start:0
    docs : []
    facet_counts: { 
     "facets": []
    }
}

{
    numFound : 0
    start:0
    docs : []
    facet_ranges: { }
  facet_fields: {}
}

Where do I start?

Each of the feature APIs help your site visitors search for products and content on your site. A good place to start is with the product search API, particularly the scenario-based walkthrough below: Walkthrough — Build a product search results page. The product search API is the most comprehensive of the Search and Merchandising APIs: once you understand how to create product search calls, it's generally easy to create calls with other search APIs. Search use cases has a collection of use cases that modify the essential use case in Walkthrough — Build a product search results page.

Run in Postman

Easily import the Discovery API collection and try the endpoints in Postman. It offers many examples of how the endpoints can be used for different use cases.

Follow this quick step-by-step guide to set up the environment and use the APIs: Postman Collections Welcome Kit