Recommendations and Pathways Parameters Reference

This guide contains a detailed explanation of all the Parameters used with the different Recommendations and Pathways APIs.

Common API Parameters

These parameters are available for all Recommendations and Pathways APIs regardless of the type of API.

Parameter name
(What the parameter is)
(Why the parameter is needed)
(How you can obtain its value)
account_idYour site's numerical Bloomreach account ID.
Example: 6702
This ID is required to uniquely identify your account.Your Bloomreach representative gives your site's account ID to you before or during your integration kickoff meeting.
_br_uid_2A first-party cookie created by the Bloomreach tracking pixel library (BrTrk).
Example: &_br_uid_2=uid%3D 7797686432023%3Av%3D11.5% 3Ats%3D1428617911187%3Ahc%3D55
This cookie creates a unique, anonymous identifier for every browser or device.Mostly the default value provided is used, which is already encoded.
domain_keyThe site version's domain ID is for the domain where you want to receive your Bloomreach API requests.
Example: documentation_site
This parameter identifies the specific site version when one account ID hosts multiple site versions with unique characteristics, such as language versions.Provided by your Bloomreach representative while scoping and integration.
fieldsA comma-separated list of fields to be sent in the request.

Alternatively, you may configure the fields in the Widget Configurator in the Dashboard instead. This parameter is required if not sent via the Dashboard.
Example: &fields=price,color
Only the attributes passed in the fields parameter will be returned in the doc section of the response.Attributes must be enabled and mapped by Bloomreach.
filtersThe filter parameter applies a faceted filter to the returned products, searching for products that fit your parameter values. When filtering by an attribute, ensure that the attribute name is enclosed in quotes.
Example:&filter="Manufacturer Name":"Pacifichome"

Use cases
You can also filter results based on numeric ranges.
For example, &filter=price:[100 TO *].

To provide multiple filters, send multiple filter parameters.
For example, &filter=price:[* TO 100]&filter=color_groups:blue.

Please note that the below operations are not supported
- a negative filter on ranges
- SKU-level attribute range filtering is only available for Pathways widgets, not Recommendations widgets. Product-level attribute range filtering is supported for both Pathways and Recommendations widgets.
To narrow down and get more specific results.Any facet that you want to filter must be in your feed.
Attributes must be enabled and mapped by Bloomreach. Let your Bloomreach representative know which attributes in your content feed you want to apply as filters to search results.
ref_urlURL or the page from where your visitor came to your site.
Required if you want to use Targeting. Helps to track the journey.Fetch the URL of the page as you desire.
request_idAn ID to track site visitor clicks. Bloomreach doesn't automatically enforce any requirements for this parameter.
For example, you can enter "test" as your value for each instance of the request_id parameter without triggering an error message. However, using a unique value allows us to help you if you encounter a problem.
Example: 27qeut4b29kqu
It helps track the APIs.It is recommended that you generate unique, random values of 13 digits to enable click-tracking.
rowsThe number of matched items to return per results page in the API response.
Example: 50
To allow pagination and manageable results.Determined by the user as per need. To enhance performance, limit this value to the number of items that you think is reasonable for a single page of search results.
urlThe absolute URL of the page where the request is initiated. Do not use a relative URL.
To identify the origin of the request.Use the absolute URL of the page.
user_idThe universal customer ID of the user (visitor). You only need to pass this field if your particular integration tracks customers this way.
Example: kjhh837hsj29h
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.Decided and shared by you. Use an anonymous string. Don't use email or other personally identifiable information.
view_idA unique identifier for a specific view of your product catalog.
Example: homeoasis_ca_en
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.
view_id for different views are decided by Bloomreach and the customers when scoping during the integration process.
widget_idIt’s a unique identifier assigned to widgets when they are created on the Widget Configurator.
Example: 1jwp539z
This parameter is used to identify a specific widget while consuming the widget APIs.The ID of the widget, which can be found in the Widget Configurator in the Dashboard.

API Specific Parameters

These parameters are only available for selected Recommendations and Pathways APIs. The ones which they can be used with is also mentioned in the table.

Parameter name
(What the parameter is)
(Why the parameter is needed)
(How you can obtain its value)
Available for which API(s)
cat_idUnique ID of the Category present in the feed and pixel.
Example: 116715
For identifying, querying and operating on categories if using a category-based API.Category ID for each Category is defined in the feed and pixel.

  • Category-based Widget API
context_idcontextid takes a single product ID for producing Context-based merchandising results for the widget.
Note: In case a context_id is not provided, the system will use Item ID(s) to produce Contextual Merchandising results for the widget.
_Example: 4500928

You can find more information on the Contextual Merchandising Feature in its guide.
Contextual Merchandising uses Context ID as a primary input for generating the recall set of the widget results.
It is highly recommended to pass a context_id whenever a contextual attribute rule is added for a better widget recall set and performance.
In the event that not enough results are produced based on context_id, the system depends on Item ID(s) as a fallback to fill the recall set of the widget.
Present in the feed for each item.
Choose the ID of the item you want to use for influencing contextual recommendations.

  • Item-based Recommendation Widget API
facetA boolean for enabling/disabling facets in the response.Facets are disabled by default. This parameter is used to enable them.To enable facets, set facet=true.

  • Keyword-based Widget API
  • Category-based Widget API
filter_facetIt 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 feed.

For Example,
Single filter with multiple values:
&filter_facet=color:"red" OR "purple"
Multiple filters on different attributes:
&filter_facet=color:"red" &filter_facet=brand:"Bloomreach"
With the filter parameter, after a user selects a facet value for filtering, the other facet values in that field are not returned by the API and are no longer visible. The filter_facet parameter allows other facet values to be returned after a facet value has been selected.Attributes must be enabled and mapped by Bloomreach.
You can then apply the facet filter when needed.

  • Keyword-based Widget API
  • Category-based Widget API
item_idsSpecifies access to a particular set of items. For product catalog, this would be the PID(s).
Example: 4427949
Used to uniquely identify an item for item-based operations.Present in the feed for each item.

  • Item-based Recommendation Widget API
queryYour site visitor's search query. Search queries are composed of one or more terms.
Example: "white sneakers".
To use the query for operations that rely on the user's input.Query string that is entered by the visitor.

  • Keyword-based Widget API
  • Personalization-based Widget API
segmentsegment allows you to rank search results based on segment data to serve different experiences to different segments of users.
See the Relevance by Segment feature for more details on segments.
Example: view_id:ie
Ranking happens only among items within that segment.
More information on the segment parameter can be found here.
The Relevance by Segment feature must be enabled on your account by Bloomreach. If you would like to enable this feature, please consult your DXM or Business Services Consultant.
Example - view_id:ie
Email Recommendation APIs:

  • Category-based

  • Keyword-based

  • Personalization-based

sortSorts results based on the field value in ascending, descending, or another combination of orders. You can sort any field.
Example: sort=sale_price desc sorts in descending order of the sale price.
To get ordered results by default, rather than ordering them on your end in your site's logic.Value is a field name, followed by asc/desc for ascending/descending order respectively.Email Recommendation APIs:

  • Category-based

  • Keyword-based

  • Personalization-based

startThe 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.
Example: start=3
Helps with pagination of results.You can decide the value as per need.All Email Recs APIs except Item-based