Global Recommendation Widget API - Bloomreach Experience - Headless Digital Experience Platform

Global Recommendation Widget API

This API allows you to fetch the global widget for trending products. You must send a GET request on the API endpoint mentioned below along with the widget_id in the URL path.

GET

 http://pathways.dxpapi.com/api/v2/widgets/global/{widget_id}

The widget_id that must be sent in the path params is a unique identifier of the widget type you create via the configurator. This ID is generated when the widget is created and must be used in all the API requests for Recommendations and Pathways. 

Request Body Parameters

The parameters described below must be sent in the request body for fetching personalization-based recommendation widgets:

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

Required

Mandatory

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

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

Example value

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

Required

Mandatory

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

ref_url

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

Use the absolute URL

Don't use a relative URL for your ref_url parameter value.

Value type

string

Example value

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

Required

Optional

request_id

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

The request_id is an important parameter for debugging so it is important that you send this. 

Value type

string

Example value

&request_id=1597706996836

Required

Mandatory

view_id

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

Value type

String

Example

view_id=ACA-MAX

Required

Optional

fields

A comma-separated list of fields to be sent in the request. You can choose to configure the fields in the Dashboard or you can send it as a part of the request. This parameter is Mandatory if not sent via the Dashboard.

Value type

String

Example value

fields: "pid,url,sale_price,title"

Required

Optional (Mandatory if not sent via the Dashboard)

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

filter

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

Attributes must be enabled and mapped by Bloomreach

Let your Bloomreach representative know which attributes in your product feed that you want to apply as filters to search results.

The filter  parameter filters result to include only relevant items.

Value type

String

Example value

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

Required

Optional

Support for Range Filter

The Range filter allows you to filter the results based on numeric ranges. An example of a valid filter query looks like this:

  1. &filter=-(price:["*" TO "100"])
  2. &filter=(price:["100" TO "*"])

Currently, we don't chain multiple rules in a single query param like this filter example =-(price:["*" TO "100"],color_groups: ("blue" OR "red")).


Instead, use a chain with multiple filter query params like the example given below:

&filter=-(price:["*" TO "100"])&filter=-(color_groups: ("blue"))&...
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?