Recommendations and Pathways APIs provide data for the Recommendations and Pathways widgets on mobile and desktop pages. These APIs are sent over HTTP 1.1 protocol and the response is JSON-formatted. Before you begin, you may want to visit the API Deployment page to learn about how our APIs work, the Authentication mechanism, and the best way to use our APIs.
Run in Postman
Easily import the Discovery API collection and try the endpoints in Postman. It offers many examples of how the endpoints can be used for different use cases.
Follow this quick step-by-step guide to set up the environment and use the APIs: Postman Collections Welcome Kit
OpenAPI spec
The detailed OpenAPI specification for the Recommendations and Pathways APIs v2 can be found on GitHub:
Endpoints
Production: https://pathways.dxpapi.com/api/v2/widgets/{widget type}/{widget_id}
Staging: https://pathways-staging.dxpapi.com/api/v2/widgets/{widget type}/{widget_id}
The widget types are listed in the next section below. The widget_id can be found in the Widget Configurator in the Dashboard.
Widget types
There are 6 types of Recommendations and Pathways widgets:
- Category-based Widget
- Global Recommendation Widget
- Item-based Recommendation Widget
- Keyword-based Widget
- Personalization-based Widget
- Visual Search Widget
Each widget type uses a different API endpoint, and each widget API fetches results differently and solves for a specific use case. The table below lists suggested use cases for each widget type, and you can read more about each widget type in the Recommendations User Guide.
| Widget type | API endpoint | Algorithms supported | Use Case |
|---|---|---|---|
| Category | /v2/widgets/category/{widget_id} | Business-driven custom recommendations widgets like new arrivals, product collections, etc. This could be on a category or landing page. | |
| Global | /v2/widgets/global/{widget_id} | Recommendations surfaced by Bloomreach based on the most popular or trending products in a particular segment. | |
| Item | /v2/widgets/item/{widget_id} | Recommendations surfaced by Bloomreach algorithms based on user actions on your site- individually or overall. | |
| Keyword | /v2/widgets/keyword/{widget_id} | Business-driven custom recommendations widgets like new arrivals, product collections, etc. This could be on a search or landing page. | |
| Personalization | /v2/widgets/personalized/{widget_id} | Personalized widget based on customer's purchase history. | |
| Visual | /v2/widgets/visual/upload/{widget_id} /v2/widgets/visual/search/{widget_id} | Displays visually similar shoppable recommendations once the customer uploads an image. |
Example request
curl -X GET \ 'https://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'
- API requests should be limited to 16K Bytes. API requests above this length will throw Error Code 414.
- Please note that the correct domain_key is mandatory in the API request. Starting March 2023, sending API requests without domain_key will return a 4xx error response. This applies to all Recommendations and Pathways APIs except Email Recommendations APIs.
Changes from v1 API
Some parameters in the v1 API are different in the v2 API:
| v1 parameter | v2 parameter | Description |
|---|---|---|
| q | query (Search) cat_id (Category) | For Search Pathways, a query is entered in the search box or statically allocated for a landing page. For Category Pathways, the cat_id indicates 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. |
Authentication in the v2 API
The v1 API allows passing the auth-key as a query param, but the v2 API requires passing the auth-key as a request header. For example, -H 'auth-key: abc1d234e5fgh6ij'
Filtering support
The v2 APIs support advanced filtering, which you can read about on the Advanced Filtering Support for Recommendations and Pathways page