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.

CallProduction EndpointStaging Endpoint
All Search and Merchandising API calls (except Autosuggest calls), and JSON Thematic API callshttps://core.dxpapi.com/api/v1/core/?https://staging-core.dxpapi.com/api/v1/core/?
Autosuggest API callshttps://suggest.dxpapi.com/api/v2/suggest/?https://staging-suggest.dxpapi.com/api/v2/suggest/?
All SEO API callsPlease reach out to your TPM/TC to provide the SEO endpointhttps://bsapi-test.brsrvr.com
Recommendations and Pathways API callshttps://pathways.dxpapi.com/api/v2/widgets/{widget family}/{widget_id}https://pathways-staging.dxpapi.com/api/v2/widgets/{widget family}/{widget_id}

📘

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:

"q" definitionResult
q=*[OK]
q=.[OK]
q=?NOT ALLOWED
q=~NOT ALLOWED
q=*term1 QUERY REWRITE to q=term1
q=term1*term2QUERY REWRITE to q=term1 term2
q=term1~term2QUERY REWRITE to q=term1 term2
q=term1?term2QUERY REWRITE to q=term1 term2
q=""ERROR code 400
No q paramERROR code 400

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 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.

{
    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.

Run in PostmanRun in Postman

The only thing needed to use the Postman collection is to set up the environment variables:

Environment VariableValue
hostIndexing Host
account_idYour Bloomreach provided account ID
domain_keyWhere this information will be stored on the backend represented with catalog name and language key
collectionContent Catalog
keyAn API key will be provided for each environment in your account. This access key must be placed in the Authorization header.
search_hostSearch Host
auto_suggest_hostAuto-suggest Host
urlThe absolute URL of the page where the request is initiated. Do not use a relative URL
ref_urlThe URL of the page or HTTP referrer where the request is started
br_uid_2The br_uid_2 cookie is a first-party cookie created by the Bloomreach tracking pixel library
request_idAn ID to track site visitor clicks. We recommend you generate unique random values of 13 digits to enable click-tracking