Use Case Dependent Parameters
Use case-dependent parameters
These parameters are for specific product search use cases. Each parameter has a section that tells you which use cases require the parameter.
When you use the query '*' as 'q=*' in the API request, the latency of the response will vary depending on your catalog size and it may not adhere to the Bloomreach's standard SLA. Further, please note that except for include/exclude operation, other merchandising operations such as boost/bury or slots do not work on * query parameters.
Parameter | Details | ||
callback |
Indicates whether to return data wrapped in the function for cross-origin requests. If you're running a server-side request, then use the value, br_server. If you're running a native-app request, then use the value, br_app. Value typestring (enum) Example value
Use caseReturn data wrapped in the function for cross-origin requests. |
||
fq |
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 feed. Read more about using the fq parameter in the "Simple Filtering" section in the Faceting and filtering page. 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. Value typestring Example value
fq Syntax
To learn about the syntax for fq, to go the "Syntax for fq and efq parameters" section on Faceting and filtering page. Use case Apply filtering to search results. Specify a particular type of non-product content. |
||
efq |
Applies a complex boolean filter to search results to include or exclude items that fit your parameter values. Any product attribute in your product feed is valid, such as brand names and sizes. Typically, the efq parameter is used for custom attributes that you include in your product feed to support additional business logic that you might need to filter. Read more about using the efq parameter in the "Complex boolean filtering" section in the Faceting and filtering page. efq or fq?
Values for the efq parameter are similar to values for the fq parameter. The difference between efq and fq is that efq supports complex boolean searches and fq filters on facets. You can use the fq parameter with the efq parameter to apply more complex filtering. Read more in the "Complex boolean filtering" section in the Faceting and filtering page. Value typeString Example value
Use caseApply complex filtering to search results. |
||
facet.range |
Return a count of ranged facets, such as price and sale price. Use numeric attributes only. Value typestring Example value
Use caseApply ranged filtering to search results. |
||
sort |
Sorts results based on the field value in ascending, descending, or another combination of orders. You can sort any fl field. Some examples are given below:
Value typestring (enum) Example value
Use caseSort search results by certain attributes |
||
view_id |
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:
💡Consistent, valid values Your view_id values must be the same in your API, pixel, and product catalog. If Abacus Thinking assigns the value, ACA-MAX, to the view_id parameter in their product feed, then the parameter value, academia maximiliano, doesn't match any catalog view. Value typestring Example value
Use caseSearch a specific view of a site with multiple versions. |
||
user_id |
The universal customer ID of the user. You only need to pass this field if your particular integration tracks customers this way. 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. 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. Value typestring Example value
Use caseTrack individual site visitor behavior. |
||
widget_id |
This widget_id is provided via the brSM dashboard under "Dynamic Widgets" to fulfill certain usecases where the results need to be independently curated by business users. This is an optional feature that can be enabled by discussing with your CSM. Example
Use caseRetrieve a specific Dynamic Widget based result set using a widget_id |
||
stats.field |
This parameter allows you to display the maximum and minimum values of any numeric field in your data set for a user query. With this parameter, you can get all the documents matching a query and display the minimum and maximum values of specific attributes such as price, sale_price, length, width, reviews, and so on. Note : This parameter is supported for single-valued numeric attributes only. Example &stats.field=sale_price,price,MARGIN_DOLLAR Sample Response { "response": ... "facet_counts:" ... "stats":{ "stats.field":{ "sale_price":{ "max":2449.99, "min":0.69 }, "price":{ "max":2449.99, "min":0.69 }, "MARGIN_VALUE":{ "max":0.91, "min":0 } } Use case The stats.field parameter can be used to display the price range (max-min) in the UI as a price slider. When the user performs a search query, the maximum and minimum price of the queried product is displayed with stats.field. This parameter can also be used for other numeric attributes such as review, length, width, and so on. |
Buy Online Pick-up In Store (BOPIS)
With this feature, you can allow your user to search products from across your sites (online) and have it picked up physically from any of your stores nearest to the user (offline).
To read more about this feature, go to BOPIS page.
For this usecase, you can use the following parameters. BOPIS works on both Search and Category APIs.
Parameter | Details |
ll |
The latitude-longitude of the end-customer in format lat,long separated by a comma. Value Type Alpha-numeric string Required Mandatory Example value lat,lon eg. 11.09,10.018 |
fl |
Returns the distance from point “ll”. In the response body, this value is returned as an additional field with the suffix ‘.distance’. Value Type Sting Required Mandatory Example value fl=geo_spatial_field |
fq |
You can send this value if you want to enable filtering by distance. This distance is calculated with reference to “ll”. Value Type String Required Optional Example value fq=geo_spatial_field : “100” |
Sample Request
Given below is a sample request of a Search API with BOPIS parameters:
GET http://core.dxpapi.com/api/v1/core/? account_id=<Bloomreach provided account ID> &auth_key=jazzhands &domain_key=example_com &request_id=8438674518839 &_br_uid_2=uid=7797686432023:v=11.5:ts=1428617911187:hc=55 &ref_url=http://www.example.com/home &url=http://www.example.com/index.html?q=dresses &request_type=search &ll=38.880657,-77.396935 &search_type=keyword &q=dresses &fl=store_lat_lon, pid &fq=store_lat_lon:"100" &rows=10 &start=0