Bloomreach Search and Merchandising APIs - Bloomreach Experience - Headless Digital Experience Platform

Bloomreach Search and Merchandising APIs

Getting Started

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.

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: search.bloomreach.com.

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

If you cannot migrate before September 15, 2021, we recommend planning your migration for Q1 2022. The core.dxpapi.com 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 http://core.dxpapi.com/api/v1/core/? http://staging-core.dxpapi.com/api/v1/core/?
Autosuggest API calls http://suggest.dxpapi.com/api/v2/suggest/? http://staging-suggest.dxpapi.com/api/v2/suggest/?
All brSEO API calls Please reach out to your TPM/TC to provide the brSEO endpoint http://bsapi-test.brsrvr.com
Pathways and Recommendations API calls http://pathways.dxpapi.com/api/v2/widgets/{widget family}/{widget_id} http://pathways-staging.dxpapi.com/api/v2/widgets/{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=? NOT ALLOWED
q=~ NOT ALLOWED
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

    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 this scenario-based walkthrough: 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.

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?