Pathways and Recommendations API v2 - Bloomreach Experience - Open Source CMS

Pathways and Recommendations API v2

These APIs provide data for the Pathways and Recommendation widgets on mobile and desktop pages. These APIs are sent over HTTP 1.1 protocol and the response is JSON-formatted. Before you begin, learn about how our APIs work, the Authentication mechanism, and the best way to use our APIs on the API Deployment page. If you are already familiar with our APIs, jump right into the API section. 

Changes from V1 API (mapping from old V1 parameters) 

For existing customers who use the widget API are on v1 and the documentation on this page is for widget API v2. You will see the following changes in the naming of the parameters if you are using v1:

v1 Parameter

v2 Parameter

Description

q

query 

or cat_id

For Search Pathways a query entered in the search box or statically allocated for a landing page. 

For Category pathways the cat_id parameter is used to indicate the category being operated on.

fq filter This 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.

fl

fields

The field must include attributes that you want returned in your API response, such as product IDs and prices. The attributes are defined as in the product feed. 

Authentication

The authentication mechanism for v2 is different from v1. You must now pass the auth-key as a request header and not as a part of the query param.

For example: -H 'auth-key: abc1d234e5fgh6ij'

Mapping API family endpoints to Widget Types

You can use the table given below to understand which API maps out to which widget type. Each API fetches results differently and solves for a specific use case. While there are minor differences in the request body parameters, you must understand which endpoint to use for your widget type to correctly implement widgets. 

If you are unsure of which widget type to use, read about the Widget Types on this page and come back for API implementation. 

API Endpoints

Algorithms supported

Use case

/v2/widgets/item/{widget_id}
  • Frequently bought together
  • Frequently viewed together
  • Similar products
  • Top Picks for you
Recommendations surfaced by Bloomreach algorithms based on user actions on your site- individually or overall.
/v2/widgets/category/{widget_id}
  • Pathways widgets on category or landing pages
Business-driven custom recommendations widgets like new arrivals, product collections, etc. This could be on a category or landing page. 
/v2/widgets/keyword/{widget_id}
  • Pathways widgets on search or landing pages 
Business-driven custom recommendations widgets like new arrivals, product collections, etc. This could be on a search or landing page.  

Recommendations Widgets API

For all the recommendation widgets you deploy on your site, use the following APIs to receive the widgets data. Depending on the type of widget (defined by the created in the widget configurator), ensure that you send widget specific parameters along with the common parameters. For example, for item-based widgets such as "Frequently bought together," you must mandatorily send us the item_id in the request body along with the mandatory parameters as the item_id is the basic identifier based on which the Bloomreach algorithm will show the recommendations. 

Example Request

This is a generic example of the Recommendations and Pathways API. Based on the widget type, you must pass the widget-specific parameters documented in the latter half on this page.

GET http://pathways.dxpapi.com/api/v2/widgets/{widget family}/{widget_id} 
&_br_uid_2=uid=7797686432023:v=11.5:ts=1428617911187:hc=55 
&account_id=<Bloomreach Provided Account ID> 
&url=http://www.example.com/index.html?query=dresses 
&domain_key=example_com &user_id=947345478564 
&ref_url=http://www.example.com/home 
&request_id=8438674518839 
&fields=pid,title,brand,price,sale_price,thumb_image,url,description 
&rows=10 
&start=0

curl Request

curl -X GET \ 'http://pathways.dxpapi.com/api/v2/widgets/item/aBcDeF?item_ids=1000000000,6007840010&facet=true&domain_key=example&start=0&ref_url=http%3A%2F%2Fwww.snap.bloomreach.com&rows=16&url=http%3A%2F%2Fwww.snap.bloomreach.com&_br_uid_2=uid%253A1031056211%253Av%253D01.5%253Ats%253D1301650080%253Ahc%253D409&account_id=<Bloomreach Provided Account ID>&fields=pid&request_id=1331600000' \  
-H 'auth-key: abc1d234e5fgh6ij'
Staging
To use the APIs on a staging environment, use the URL http://pathways-staging.dxpapi.com/api/v2/widgets/{widget family}/{widget_id}

Fetching Item-based Recommendation Widgets

The item-based widgets such as Frequently bought together, Frequently viewed together, Similar products and Top picks for you 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

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

 

Pathways Widgets API

These APIs power custom widgets like new_arrivals, product collections, etc. This could be a search, category or landing page. You can fetch the widget data using the parameter cat_id for category-based widgets and query for search-based widgets.

Fetching Category-based Widget 

This API allows you to fetch category based widget API response. Ensure that you have also sent the widget_id in the path URL. 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. 

GET

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

Request Body Parameters

The table below describes mandatory and optional parameters for category-based 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 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

cat_id

Your site's category ID.

Value type

String

Example

cat_id=cat000922

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)

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

Required

Optional 

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

Fetching Search-based Widget 

The API given below allows you to fetch search(query)-based widget response. 

GET

 http://pathways.dxpapi.com/api/v2/widgets/keyword/{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 search-based 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 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

query

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

query=red dress

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

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)

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

Required

Optional 

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

Fetching Personalization based Recommendation widgets

This API allows you to fetch the personalization widget such as past purchases. 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/personalized/{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

query

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

query=red dress

Required

Mandatory

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

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

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

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?