Product & Category Search API v1

📘

For detailed information on how Bloomreach Search works, how you can optimize your search quality, and how to troubleshoot search issues, go through the Search Quality Guides.

Where do I start?

The Product and Category Search API helps your site visitors search for products 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 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

OpenAPI spec

The detailed OpenAPI specification for the Product & Category Search API v1 can be found on GitHub:

Endpoints

The API 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 Tune and test search experience milestone, you need to point your API servers to production servers.

Production: https://core.dxpapi.com/api/v1/core/?
Staging: https://staging-core.dxpapi.com/api/v1/core/?

👍

Code samples

Check the demo code sample that demonstrates how to implement Search and Category pages.

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.

Example requests

Product search request for "dresses"

GET https://core.dxpapi.com/api/v1/core/?
account_id=<Bloomreach provided account ID>
&auth_key=jazzhands
&domain_key=example_com
&request_id=8438674018839
&_br_uid_2=uid=7797686432023:v=11.5:ts=1428617911187:hc=55
&ref_url=http://www.example.com/home
&url=http://www.example.com/index.html?q=dresses
&request_type=search #Value must be search for Product Search API
&search_type=keyword #Value must be keyword for Product Search API
&q=dresses
&fl=pid,title,brand,price,sale_price,thumb_image,url,description
&rows=10
&start=0

📘

Visit this guide to learn about the latest facet response format.

Category search request for "cat000922"

GET https://core.dxpapi.com/api/v1/core/?
account_id=<Bloomreach Provided Account ID>
&auth_key=jazzhands
&domain_key=example_com
&request_id=8830241055597
&_br_uid_2=uid=7797686432023:v=11.5:ts=1428617911187:hc=55
&ref_url=http://www.example.com/home
&url=http://www.example.com/index.html?q=cat000922
&request_type=search #Value must be search for Category API
&rows=20
&start=0
&fl=pid,title,brand,price,sale_price,colors,sizes,thumb_image,price_range,sale_price_range
&q=cat000922
&search_type=category #Value must be category for Category API

📘

Category API does not support characters like ä , é , ô in category IDs.

🚧

Query size limit

Query parameter can have a maximum length of 300 characters and a maximum word count of 30. Exceeding this limit results in an error.

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: {}
}

📘

Customers whose go-live date is after September 7, 2023 will be on V3 Facet response format by default. If you’re on the legacy format and would like to implement the new Facet response format, kindly contact your Bloomreach Services representative.

Native mobile app and non-JS integration

API requests for native mobile apps or non-JS environments need different values for some parameters:

❗️

API requests should be limited to 16K Bytes. API requests above this length will throw Error Code 414 .

• _br_uid_2: The value should be the same as described on the Cookie page. Generate a br_uid_2 for your app user and store it in the app permanently if a br_uid_2 does not exist. This br_uid_2 should be used on the corresponding API calls for the app. If the user is on iPhone and resets their IDFA, or if the user is on an Android device and resets their advertising settings: the br_uid_2 should be erased and regenerated the next time the app is set.
• ref_url: Leave your ref_url parameters empty.
• url: Use a dummy value for your url parameters, such as exampledomain.app.

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.

Timeout

We recommend that you configure the application client timeout value to at least 2 seconds. If needed, you can set the client timeout value to more than 2 seconds depending on your use case.

If there's a timeout during a search or category page load, then we recommend that you redirect your customer with an HTTP 302 response code to your site's home page. Append this specific tracking parameter to the redirected URL: ?_thto=1. This parameter serves a few purposes:

• This ensures that your customers always receive a page load.
• It also collects data to assist Bloomreach in troubleshooting timeouts.

For example, let’s say that the following page encounters a timeout error when loading:
http://www.example.com/search?q=shoes

Then the site redirects the customer to the home page with a 302 response code and uses the following URL:
http://www.example.com/?_thto=1

❗️

Please note that the correct domain_key is mandatory in the API request. Starting March 2023, sending API requests without domain_key will return a 4xx error response.