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
(What the parameter is)
Why
(Why the parameter is needed)
How
(How you can obtain its value)

_br_uid_2

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

account_id

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

url

The absolute URL of the page where the request is initiated. Do not use a relative URL.
Example: https://www.documentation-site.com

To identify the origin of the request.

Use the absolute URL of the page.

ref_url

URL or the page from where your visitor came to your site.
Example: https://example.com/email-red-dress

Required if you want to use Targeting. Helps to track the journey.

Fetch the URL of the page as you desire.

domain_key

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

view_id

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

request_id

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

widget_id

It’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.

fields

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

rows

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

filters

The filter parameter applies a faceted filter to the returned products, searching for products that fit your parameter values. You can also filter results based on numeric ranges.
For example, &filter=-(price:["" TO "100"]) or &filter=(price:["100" TO ""]).
To provide multiple filters, send multiple filter parameters.
For example, &filter=-(price:["*" TO "100"])&filter=- (color_groups: ("blue")).

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.

user_id

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

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
(What the parameter is)
Why
(Why the parameter is needed)
How
(How you can obtain its value)
Available for which API(s)

context_id

context_id 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

filter_facet

It 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

facet

A 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

cat_id

Unique 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

item_ids

Specifies 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

query

Your 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