Use Case Dependent Parameters - Bloomreach Experience - Open Source CMS

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.

Note

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. 

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 type

string (enum)

Example value

&callback=br_server

 

Use case

Return 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 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 individual attributes in fq values with double quotes. If you are using multiple attribute in your fq value, then separate the attributes with OR or AND.

Value type

string

Example value

&fq=color:"red" OR "purple" OR "pink"

More information on fq syntax
Surround attributes in your value with quotes. For example:
brand:"Fossil"
If the attribute in the efq parameter contains a space, surround the attribute with quotes. For example:
"Product Type":"1"
If you have multiple values, then surround the entire value with parentheses. For example:
brand:("Fossil" OR "Betsey Johnson")
Please note that if the value has quote within it, then the quote should be escaped with '\', e.g. Sheet Dimension = 8.5" x 11".
In this case the fq should be:
Sheet Dimension:"8.5\" x 11\""
In this case the efq should be:
"Sheet Dimension":"8.5\" x 11\""
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]

Use case

Apply filtering to search results.

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.

 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 efqparameter to apply more complex filtering.

Value type

string

Example value

&efq=color:"red" OR "purple" OR "pink"

More information on efq syntax:
Surround attributes in your value with quotes. For example:
brand:"Fossil"
If the attribute in the efq parameter contains a space, surround the attribute with quotes. For example:
"Product Type":"1"
If you have multiple values, then surround the entire value with parentheses. For example:
brand:("Fossil" OR "Betsey Johnson")
Please note that if the value has quote within it, then the quote should be escaped with '\', e.g. Sheet Dimension = 8.5" x 11".
In this case the fq should be:
Sheet Dimension:"8.5\" x 11\""
In this case the efq should be:
"Sheet Dimension":"8.5\" x 11\""
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]

Use case

Apply complex filtering to search results.

facet.range

Return a count of ranged facets, such as price and sale price. Use numeric attributes only.

Value type

string

Example value

&facet.range=sale_price

Use case

Apply ranged filtering to search results.

sort

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

Value type

string (enum)

Example value

&sort=sale_price desc

Use case

Sort 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:

&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, ACA-MAX, to the view_id parameter in their product feed, then the parameter value, academia maximiliano, doesn't match any catalog view.

Value type

string

Example value

&view_id=ACA-MAX

Use case

Search 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 type

string

Example value

&user_id=947305478564

Use case

Track 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

&widget_id=<hex widget ID from brSM dashboard>

Use case

Retrieve a specific Dynamic Widget based result set using a widget_id

Product Grouping (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 Product Grouping page. 

For this usecase, you can use the following parameters. Product Grouping 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 Product Grouping 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
Did you find this page helpful?
How could this documentation serve you better?
On this page
    Did you find this page helpful?
    How could this documentation serve you better?