Item-based Recommendations Widget API - Bloomreach Experience - Headless Digital Experience Platform

Item-based Recommendations Widget API

The item-based widgets such as Frequently bought together, Frequently viewed together, Similar products, Top picks for you, Bestseller and Experience-Driven Recommendations use the unique identifier of the item on your site to show relevant recommendations. You must send a GET request on the API endpoint mentioned below to get the required response. 

GET

http://pathways.dxpapi.com/api/v2/widgets/item/{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 dashboard configurator. This ID is generated when the widget is created and must be used in all the API requests for Pathways and Recommendations. 

Request Body Parameters

The table below describes all the parameters required for this API. Ensure that you have sent the ones marked as Mandatory.

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

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

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

Required

Optional

item_ids

item_ids

The item_ids parameter specifies access to a particular set of item(s) . In the case of a product catalog this would be PID(s) or product ID(s) . 

Value type

string

Example value

item_ids=DRE219718979135

item_ids=DRE219718979135,XYZ2197189777

Required

Mandatory

Using item_ids with Similar Products 
Using multiple item_ids (comma separated values) is currently not supported for Similar Products recommendation widgets due to the limitation in the legacy MLT widget (now Similar Products).  
ref_url

The URL of the page or HTTP referrer 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

Only mandatory if you want to use Targeting

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?