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.
What do the Product Search and Category APIs do?
The Product Search API sends a keyword query to retrieve results about products and other content on your site. You can apply additional filters and facets to return products and content that either include or exclude specified attributes like colors and brands.
The Category API sends a category query to retrieve results about products within the categories that you specify.
Endpoints
Production: https://core.dxpapi.com/api/v1/core/?
Staging: https://staging-core.dxpapi.com/api/v1/core/?
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 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.
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.
Buy Online Pick-up In Store (BOPIS)
With this feature, you can allow your user to search products from across your sites (online) and have it picked up physically from any of your stores nearest to the user (offline).
BOPIS uses the following parameters:
- ll - BOPIS-specific parameter to specify the end-customer's latitude-longitude.
- fl - Returns the distance from the point specified in the ll parameter.
- fq - Allows filtering by distance from the point specified in the ll parameter.
GET https://core.dxpapi.com/api/v1/core/?
account_id=<Bloomreach provided account ID>
&auth_key=jazzhands
&domain_key=example_com
&request_id=8438674518839
&_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
&ll=38.880657,-77.396935 #latitude-longitude of the end customer
&search_type=keyword
&q=dresses
&fl=store_lat_lon, pid #Returns the distance from ll
&fq=store_lat_lon:"100" #Enables filtering by distance from ll
&rows=10
&start=0
Read more about this feature on the BOPIS feature page.
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.