Product Search API - Bloomreach Experience - Open Source CMS

Product Search API

What does the Product Search API 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.

What's the difference between product searches and content searches?
A product search retrieves products on your site that fit your specified criteria. Products are items on your site that a customer might purchase. Your product feed contains these items and must be current so that your search queries can retrieve accurate results.
Content Search- In Pilot Phase
A content search retrieves non-product content, such as knowledge base articles and product reviews. This kind of content is called unstructured content, and it doesn't adhere to a defined data model like your products do. Unlike product searches, content search queries don't rely on a feed.

Example request

Here's an example request that searches for dresses. 

Request: keyword search for dresses

GET http://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
&search_type=keyword
&q=dresses
&fl=pid,title,brand,price,sale_price,thumb_image,url,description
&rows=10
&start=0

Request parameters

These are the parameters used in the example request. Every product search request needs these parameters.

Are you integrating your native mobile app with Bloomreach?
Some of the parameters in your API requests for native mobile apps need different values from those for your site:

● _br_uid_2: Leave your _br_uid_2 parameters empty.
ref_url: Leave your ref_url parameters empty.
url: Use a dummy value for your url parameters, such as exampledomain.app.
Values are shown below in plain text for readability. However, you need to fully encode the url= and ref_url= to prevent breakages on special characters in the URL. Refer here to correct encoding where needed for filters.
Parameter Details
_br_uid_2

A first-party cookie created by the Bloomreach tracking pixel library (BrTrk). This cookie creates a unique, anonymous identifier for every browser or device.

The _br_uid_2 cookie is already encoded
Don't encode the cookie parameter value: _br_uid_2. Use this value exactly as it comes. It's already encoded.

 ✅ &_br_uid_2=uid%3D7797686432023%3Av%3D11.5%3Ats%3D1428617911187%3Ahc%3D55

Value type

string

Required

Mandatory

Example value

&_br_uid_2=uid%3D7797686432023%3Av%3D11.5%3Ats%3D1428617911187%3Ahc%3D55

account_id

Your site's numerical Bloomreach account ID. Your Bloomreach representative gives your site's account ID to you before or during your integration kickoff meeting.

Notify your Bloomreach representative 
If you don't have a Bloomreach account ID, then let your Bloomreach representative know immediately. You can't send any API calls without your account ID.

Value type

integer

Required

Mandatory

Example value

&account_id=<Bloomreach provided account ID>

auth_key

The Bloomreach-provided authentication key for the Bloomreach account that's sending the request.

Leave auth_key parameter values empty for client-side calls

If you use client-side calls for any of your Bloomreach requests, then do not enter an auth_key value in those client-side calls. Pass the auth_key with an empty value in client-side calls.

The auth_key value is a private authorization key. If you include your valid auth_key value in client-side calls, then you inadvertently expose that private information to everybody.

Value type

string

Required

Mandatory

Example value

&auth_key=jazzhands

Your own auth_key value looks very different from this example. We're using an odd example value to reinforce the importance of treating this key like you treat other keys like your email login credentials: don't share it.

domain_key

Your site domain's ID, which is provided by Bloomreach. This ID is for the domain that you want to receive your Bloomreach API requests.

This parameter identifies the specific site version when the one account ID hosts multiple site versions with unique characteristics, such as language versions. Bloomreach uses your domain_key parameter value to ensure that only the data that pertains to that site version is used for query and analytics features, such as autosuggestions.

Value type

string

Required

Mandatory

Example value

&domain_key=example_com

fl

 

   

The attributes that you want returned in your API response, such as product IDs and prices. All fl parameters must include pid as one of their values. You can include other attributes from your product feed.

Tip
Include all the attributes from your product feed that you want to include in search results, not just the attributes that you want to be returned as objects in your API response. Your search results pages are built from your API responses. Therefore, search results pages can only include attributes that are returned in API responses.

Value type

string

Required

Mandatory

Example value

&fl=pid,title,brand,price,sale_price,thumb_image,url,description

Example value for Content

&fl=cid,title,thumb_image,url,description

Comma-separated values
Separate multiple attributes with a comma: &fl=pid,title,thumb_image,price

q

Your site visitor's search query. Search queries are composed of one or more terms.

Tip
You can percent encode spaces between terms, or you can leave the spaces the way they are. The correct code is %20 if you choose to percent encode spaces in multi-term search queries.

Value type

string

Required

Mandatory

Example value

&q=dresses

ref_url

The URL of the page or HTTP referrer where the request is started.

Value type

string

Required

Mandatory

Example value

&ref_url=http://www.example.com/home

request_id

An ID to track site visitor clicks. We recommend that you generate unique, random values of 13 digits to enable click-tracking.

Bloomreach doesn't automatically enforce the requirements for this parameter. For example, you can enter test as your value for each instance of the request_id parameter without triggering an error message. However, using a unique value allows us to help you if you encounter a problem.

Value type

string

Required

Mandatory

Example value

&request_id=1597706990836

request_type

 

The type of API request. Choose the value that fits your use case:

  • search
  • suggest
  • jfy
  • mlt
  • thematic

Value type

string (enum)

Required

Mandatory

Use search for search API calls
The only correct &request_type value for a category search API call is search

rows

 

The number of matching items to return per results page in the API response. The maximum value is 200.

Tip
To enhance performance, limit this value to the number of items that you think is reasonable for a single page of search results.

Value type

integer

Required

Mandatory

Example value

&rows=10

search_type

 

The type of search. Choose the value that fits your use case:

  • keyword
  • category

Value type

string (enum)

Use keyword for this tutorial's use case
The only correct &search_type value for a keyword product search is keyword.

Required

Mandatory

Example value

&search_type=keyword

start

 

The number of the first item on a page of results. For example, the first item on the first page is 0, making the start value also 0. The maximum value is 10000.

Value type

integer

Required

Mandatory

Example value

&start=0

url

The absolute URL of the page where the request is initiated.

Use the absolute URL
Don't use a relative URL for your url parameter value.

Value type

string

Required

Mandatory

Example value

&url=http://www.example.com/index.html?q=dresses

Use Case Dependent Parameters
You can also send use case dependent parameters in the Product Search API. To view the list of parameters, click here
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?