Content Search API - Bloomreach Experience - Open Source CMS

Content Search API

What does Content Search API do? 

The content search API sends a keyword query to retrieve non-product content on your site. You can apply additional facets to return content that either includes or excludes specified attributes about content type like videos and blog posts.

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.

A content search retrieves non-product content, such as knowledge base articles. You can read more about the content feed here

Example request

Here's an example request that searches for popcorn in a content site. 

GET http://core.dxpapi.com/api/v1/core/?
account_id=<Bloomreach Provided Account ID>
&auth_key=jazzhands
&domain_key=example_com 
&_br_uid_2=uid=7797686432023:v=11.5:ts=1428617911187:hc=55
&catalog_name=Recipes
&request_type=search
&search_type=keyword
&q=popcorn
&fl=item_id,item_title,thumb_image,url,description
&rows=10
&start=0

Request Parameters

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

Before getting started, read about the Escape characters and encoding here.
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.

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

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

Example value

&account_id=<Bloomreach Provided Account ID>

Required

Mandatory

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.

Value type

string

Example value

&domain_key=example_com

Required

Mandatory

fl

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

Tip
Include all the attributes from your content 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

Example value for Content

&fl=item_id,item_title,thumb_image,url,description

Comma-separated values

Separate multiple attributes with a comma: &fl=item_id,item_title,thumb_image,description

 

Required

Mandatory

catalog_name

Named identifier of the catalog. A catalog is a grouping of items into a broader category such as blogs, videos, etc. A catalog is a representation of a group of items and must have a unique name, that is also unique to a domain (if you have multiple sites). Catalogs are created in the DataConnect UI by default, you can rename the catalogs when you set up your catalogs initially. Examples of catalog_name are Motorcycle_DIY_Blogs, Recipes, Sale_Products, Product, Content, Blogs, recipe, videos, etc.   

Value type

String

Required

Mandatory

Example Value

&catalog_name=recipes

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

Example value

&q=popcorn

Required

Mandatory

request_type

The type of API request. The only correct value for a content search API call is search.

Value type

string (enum)

Example

&request_type=search

Required

Mandatory

rows

The number of matching items to return per results page in the API response. The maximum value is 200. The result size is used from the Dashboard if it is not sent in the API.

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

Example value

&rows=10

Required

Optional

search_type

The type of search. The only correct value for a content search API call is keyword.

Value type

string (enum)

Example

&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

Example value

&start=0

Use case-dependent parameters

These parameters are for specific product search use cases. Each parameter has a section that tells you which use cases require the parameter.

Parameter Details
callback

Indicates whether to return data wrapped in the function for cross-origin requests.

If you're running a server-side request, then use the value, br_server. If you're running a native-app request, then use the value, br_app.

Value type

string (enum)

Example value

&callback=br_server

Use case

Return data wrapped in the function for cross-origin requests.

fq

The fq parameter applies a faceted filter to the returned products, searching for content that fit your parameter values. Any facet that you want to filter must be in your content feed. Read more about the using the fq parameter in Faceting and filtering page. 

Attributes must be enabled and mapped by Bloomreach
Let your Bloomreach representative know which attributes in your content feed that you want to apply as filters to search results.

Value type

string

Example value

&fq=color:"red" OR "purple" OR "pink"

 fq Syntax
To learn about the syntax for fq, to go the Syntax for fq and efq parameters on Faceting and filtering page. 

Use case

Apply filtering to search results.

Specify a particular type of non-product content.

segment

The segment parameter allows you to call the Content Search API to include segments defined by you. The Relevance by Segment integration requires you to send the segment name and segment value must match between the pixel and API. For more information on how to set up segment names and values in the pixel, please refer to our pixel integration for Relevance by Segment.

Value type

string

Example value

&segment=customer_geo:NorthAmerica

Segment parameter with name "customer_geo" and value "NorthAmerica"

 

facet.field

Returns a list of fields to facet on. For content search, you must explicitly request all the facets you would like returned.

Value type

string

Example value

&facet.field=brand

Use case

Apply for facets to be returned

facet.range

Return a count of ranged facets, such as price and sale price. Use numeric attributes only.

Value type

string

Example value

&facet.range=sale_price

Use case

Apply ranged filtering to search results.

fq

The fq parameter applies a faceted filter to the returned products, searching for content that fit your parameter values. Any facet that you want to filter must be in your content feed.

Attributes must be enabled and mapped by Bloomreach
Let your Bloomreach representative know which attributes in your content feed that you want to apply as filters to search results.

The  fq  parameter filters results to include only relevant items. For example, a major sports league has a website store that sells products to fans for every team in the league. The league has 32 teams, and each team has its own hats, t-shirts, jerseys,  tchotchkes, cups, and many other items. Showing all of these items to a customer is overwhelming, causing customers difficulty when they try to find exactly what they're looking for. You can use the fq parameter in your API calls to suggest to customers only items from their own teams.

Surround individual attributes in fq values with double quotes. If you are using multiple attribute in your fq value, then separate the attributes with OR or AND.

Value type

string

Example value

&fq=color:"red" OR "purple" OR "pink"

 More information: fq syntax
Surround attributes in your value with quotes. For example:
brand:"Fossil"
If the attribute in the efq parameter contains a space, surround the attribute with quotes. For example:
"Product Type":"1"
If you have multiple values, then surround the entire value with parentheses. For example:
brand:("Fossil" OR "Betsey Johnson")
Please note that if the value has quote within it, then the quote should be escaped with '\', e.g. Sheet Dimension = 8.5" x 11".
In this case the fq should be:
Sheet Dimension:"8.5\" x 11\""
In this case the efq should be:
"Sheet Dimension":"8.5\" x 11\""
To apply filters for a ranged facet, such as price or sale price, the ranged value needs to be specified in addition to the product attribute.
For example: to limit results to products with a price below 100:
price:[* TO 100]
Or to limit results to products with a price between 200 and 300:
price:[200 TO 300]

Use case

Apply filtering to search results.

Specify a particular type of non-product content.

sort

Sorts results based on the field value in ascending, descending, or another combination of orders. You can use one of the following values:

  • launch_date desc sorts in descending order of the date on which products launched

  • launch_date asc sorts in descending order of the date on which products launched

Value type

string (enum)

Use case

Sort search results by certain attributes.

user_id

The universal customer ID of the user. You only need to pass this field if your particular integration tracks customers this way.

The parameter captures user IDs from the customer side, and reuses the information when powering apps or enhancing cross-device linking. In this way, Bloomreach recognizes users in a way that's aligned with your system. Use an anonymous string. Don't use email or other personally identifiable information. If you do not track users this way, then omit this field.

Value type

string

Example value

&user_id=947345478564

Track individual site visitor behavior.

view_id

A unique identifier for a specific view of your content catalog. If you have multiple versions of your site, each with their own content catalog characteristics like content titles and descriptions, then add view_id to your call. Bloomreach uses your view_id parameter value to display the right content information for your customers based on their individual site views.

You can enter any string value to identify the specific site catalog view. This string must be consistent in your pixel, API, and content catalog. For example, Public Health, a public healthcare service site, which offers educational resources and news to the general public has two versions of their site: one for the general public without having to log in and one for the scientific community that come to their site to look at in-depth scientific research articles (not accessible to the general public). The parameter that would be passed for the scientific community (logged in) view would be:

&view_id=scientificcommunity

Bloomreach Content Search can support a single view_id, multiple view_ids (separated by commas) or * view_id in a single API parameter for a single content catalog. If no view_ids are passed for a content item in a catalog, Bloomreach will assign a br_default_view value. If an API call is made with no view_id in the request, the br_default_view content items will return.

If a content item contains more than one view_id in the catalog and those view_ids are passed in the API param, we will return those documents without de-duping or grouping.

💡Consistent, valid values

Your view_id values must be the same in your API, pixel, and content catalog. If Public Health assigns the value, sciencecommunity, to the view_id parameter in their content feed, then the parameter value, scientificcommunity doesn't match any catalog view.

Value type

string

Example value

&view_id=scientificcommunity

Use case

Search a specific view of a site with multiple versions.

 

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