Pathways and Recommendations API v2 - Bloomreach Experience - Headless Digital Experience Platform

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. 

Widget Types

Example Request

This is a generic example of the Recommendations and Pathways API. Based on the widget type, you must pass additional widget-specific parameters.

GET http://pathways.dxpapi.com/api/v2/widgets/{widget type}/{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
API requests should be limited to 16K Bytes. API requests above this length will throw Error Code 414.

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 type}/{widget_id}

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.

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. 

Advanced Filtering Support for Pathways and Recommendations

Similar to efq filter for Search and Category APIs, you can also perfrom complex boolean queries for Recommendations and Pathways APIs using Advanced Filters. 

Read more about this feature in the Advanced Filtering Support for Pathways and Recommendations page. 

 SKU-based Filtering for Pathways and Recommendations

The Pathways and Recommendations APIs also support filtering on SKU attributes. Read more about this feature in the SKU Select API page.

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

Widget Type

Algorithms supported

Use case

/v2/widgets/item/{widget_id} Item
  • Frequently bought together
  • Frequently viewed together
  • Similar products
  • Bestseller
  • Experience-Driven recommendations.
Recommendations surfaced by Bloomreach algorithms based on user actions on your site- individually or overall.
/v2/widgets/category/{widget_id} Category
  • 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} Keyword
  • 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.  
/v2/widgets/personalized/{widget_id} Personalization
  • Past Purchases
Personalised widget based on customer's purchase history.  

/v2​/widgets​/global​/{widget_id}
Global 
  • Trending Products Recommendations
Recommendations surfaced by Bloomreach based on the most popular or trending products in a particular segment. 

Parameters Reference

Common Values

These parameters are mandatory for all widget types, and should be passed with the same values across all widget types.

  • _br_uid_2
  • account_id
  • url
  • ref_url
  • domain_key
  • view_id
  • request_id

Widget-specific Parameters

This table lists which parameters are specific to which widget types, and whether each parameter is mandatory or optional. 

  Item Widgets Category Widgets Keyword Widgets Personalization Widgets Global Widgets
endpoint Mandatory Mandatory Mandatory Mandatory Mandatory
widget id Mandatory Mandatory Mandatory Mandatory Mandatory
fields Optional Optional Optional Optional Optional
rows Optional Optional Optional Optional Optional
filters Optional Optional Optional Optional Optional
user_id Optional Optional Optional Mandatory Mandatory
item_ids Mandatory N/A N/A N/A N/A
cat_id N/A Mandatory N/A N/A N/A
facet N/A Optional Optional N/A N/A
query N/A N/A Mandatory Mandatory N/A

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?