Parameters for the MLT API
This API is going to be deprecated by the end of 2020. New customers will be a part of the Pathways and Recommendations platform. To know more about Pathways and Recommendations, see this page. Please contact your Bloomreach representative for more information.
Some of the parameters in your native mobile API requests for apps need different values from those for your site:
_br_uid_2: Leave your _br_uid_2 parameters empty.
ref_url: Leave your ref_url parameters empty.
url: Use a dummy value for your url parameters, such as exampledomain.app.
Quick reference: request parameters
This table provides a list of each parameter and a description. A yes flag in the Required column indicates that the parameter is required for all MLT calls, not some.
|
Parameter Name |
Required |
Type |
Description |
Example |
|---|---|---|---|---|
| account_id | yes | integer | The Bloomreach-provided ID of the account sending the request. | |
| auth_key | yes | string | The Bloomreach-provided authentication key for the account sending the request. You must pass this parameter, but if your integration is client-side, then you can send it empty. | jazzhands |
| _br_uid_2 | yes | string |
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 percent encode this parameter. |
uid=7797686432023:v=11.5:ts=1428617911187:hc=55 |
| pid | yes | string | The unique identifier for a product in the feed. | 1005004 |
| brand | no | string | The brand of the product. | hugo boss |
| callback | no | string (enum) |
Indicates whether to return data wrapped into the function when making cross-origin requests. If you have a server-side integration, then use the value, br_server. If you have a native-app integration, then use the value, br_app. |
br_server |
| domain_key | yes | string | The Bloomreach-provided ID of the domain receiving the request. | example_com |
| fl | yes | string | The fields returned with the MLT results, such as the name of products and prices. This value must be a comma-separated list. You must include the pid attribute in your fl parameter value. You can include other attributes from your product feed. | pid,title,brand |
| fq | no | string | Applies a faceted filter to search results, including only products with the specified attributes . You must surround the value with quotes. | brand:"Fossil" |
| request_id | yes | string | A random ID that enables click-tracking. Use 12 or 13 digits. | 1597706996836 |
| request_type | yes | string (enum) |
The request type. Use mlt, which displays an ordered list of similar products. |
mlt |
| rows | yes | integer | The number of matching products (documents) returned per results page. The maximum value is 200. To enhance performance, limit this value to the number of products that you think is reasonable for a single page of listings. | 30 |
| sort | no | string |
Sorts results based on the field value in ascending, descending, or another combination of orders. |
sale_price desc |
| start | yes | integer | The first page number of results. The maximum value is 500 . | 0 |
| title | yes | string | The title or name of the product. *Note: title is used to identify similar products in edge cases to avoid 0 results. | Red Monochrome Slingbacks |
| url | yes | string | The absolute URL of the page where the request is made. |
http://www.example.com/index.html?q=watch |
| user_id | no | string | The universal customer ID of the user. You only need to pass this field if your particular integration tracks customers this way. | 00000 |
| view_id | no | string | A unique identifier for a view of the product catalog. Use a string that identifies the specific site catalog view for your customer. | k-3 |
Detailed reference: request parameters
Some of the request parameters need a little more explanation than others. You can find this extra information here.
domain_key parameter
The Bloomreach-provided ID of the domain receiving the request. 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 for query and analytics features, such as autosuggestions.
fl parameter
The fl parameter is a comma-separated list of fields returned with MLT results, such as the name of products and prices. The following list is representative of the fields that you can use, but it isn't exhaustive. Your list depends on the values in your product feed.
-
pid is the product ID
-
title is the title or name of the product
-
url is the URL of the product description page
-
price is the price of the product
-
sale_price is the price of the product on sale
-
sku_swatch_image is a thumbnail image for a particular sku variation of a product
fq parameter
The fq 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 fq parameter filters results to include only relevant items. For example, a major sports league has a website store that sells products to fans for every team in the league. The league has 32 teams, and each team has its own hats, t-shirts, jerseys, tchotchkes, cups, and many other items. Showing all of these items to a customer is overwhelming, causing customers difficulty when they try to find exactly what they're looking for. You can use the fq parameter in your API calls to suggest to customers only items from their own teams.
Surround attributes in your value with quotes. For example:
brand:"Fossil"
If you have multiple values, then surround the entire value with parentheses. For example:
brand:("Fossil" OR "Betsey Johnson")
To apply filters for a ranged facet, such as price or sale price, the ranged value needs to be specified in addition to the product attribute.
For example: to limit results to products with a price below 100
price:[* TO 100]
or to limit results to products with a price between 200 and 300
price:[200 TO 300]
request_id parameter
The request_id parameter value is a random 12 or 13-digit ID that you supply to enable click-tracking. Bloomreach doesn't automatically enforce the 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, if you don't use a unique value, then Bloomreach can't help you with potential problems you might experience while using the API.
sort parameter
The sort parameter sorts results based on the field value in ascending, descending, or another combination of orders. You can use one of the following values:
-
sale_price desc sorts in descending order of the sale price
-
sale_price asc sorts in ascending order of the sale price
-
price_desc sorts in descending order of the price
-
price_asc sorts in ascending order of the price
-
launch_date desc sorts in descending order of the date on which products launched
-
launch_date asc sorts in descending order of the date on which products launched
user_id parameter
The user_id parameter is a universal customer ID of a user. The parameter captures user IDs from the customer side, and reuses the information when powering apps or enhancing cross-device linking. In this way, Commerce Search and Categories 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.
view_id parameter
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.
You can enter any string value to identify the specific site catalog view. This string must be consistent in your pixel, API, and product catalog. For example, Abacus Thinking sells different academic products to different grade levels. A first grade teacher looks in their Kindergarten through Grade 3 catalog, which Abacus Thinking assigns the ID, k-3:
|
&view_id=k-3 |
Consistent, valid values
Your view_id values must be the same in your API, pixel, and product catalog. If Abacus Thinking assigns the value, kindergarten-3rd, to the view_id parameter in their product feed, then the API value, k-3, doesn't match any catalog view.
Quick reference: response parameters
|
Parameter Name |
Description |
Example |
|---|---|---|
| match | A container for the core response details. | n/a |
| numFound | The number of records (products) that the MLT response is based on or the number of records that the MLT request retrieves. |
20 |
| start |
The first page number of results . |
0 |
| docs | A container for individual documents (products) and their fields . | n/a |