Exploring Catalog Data & Customizing API

This guide illustrates the process of exploring and customizing our Search and Suggest APIs as per your needs.

💡 Prerequisites


Knowledge Prerequisites
We recommend reading the following guides before starting:

Access Prerequisites
Catalog Management should always be accessed via tools.bloomreach.com and not via tools-staging.bloomreach.com. The only exception to this is if the account is not accessible via tools.bloomreach.com and is accessible via tools-staging.bloomreach.com.

Both Production and Staging versions of Catalogs are available on tools.bloomreach.com. Accessing Catalog Management via tools-staging.bloomreach.com may have edge cases where functionality may not work as it isn't a supported use case.

EU/UK-based Merchants: EU/UK-based merchants should access via tools.bloomreach.co.uk and not via tools-staging.bloomreach.co.uk. The only exception to this is if the account is not accessible via tools.bloomreach.co.uk and is accessible via tools-staging.bloomreach.co.uk.

Both Production and Staging versions of Catalogs are available on tools.bloomreach.co.uk. Accessing Catalog Management via tools-staging.bloomreach.co.uk for a non-staging-only account may have edge cases where functionality may not work as it isn't a supported use case.

Explore Catalog Data and Customize API(Search Tab)


19991999

In the catalog Search tab, you can explore the indexed data in your catalog. It also lets you see the search API calls made to our systems and understand how our APIs work.

19991999

The Search tab comes with a Search bar that allows you to display results for a query. It also shows the following components:

  1. Keyword/Category dropdown
  2. Customize action
  3. View Requests

Keyword/Category dropdown

554554

Use this dropdown to specify whether you’d like to see search results for a keyword or category.

Customize action

Use this to customize the API. Refer to the following section to view the list of options to tailor the API as per your needs:

Display Attributes(fl)

19991999

Attributes you’d like to include in the returned search documents. Please note that any custom attribute must first be configured as displayable as well as present in the catalog feed.

Filters

19991999
  • Simple Attribute Filters (fq)

This customization allows you to modify the fq parameter. The fq parameter applies a filter to the returned documents based on a specific attribute name and the attribute value(s). If a single attribute value is specified, it must be enclosed in double quotes, for example: "value". If there are multiple values, each value needs to be enclosed in double quotes and separated either by an and or an or, for example: "black" or "white". If there are multiple filters, they will be compounded together and operate as an AND condition. The attribute must be present in catalog data and configured as facetable.

  • Complex Boolean Attribute Filters (efq)

This customization is similar to fq. However, it allows you to specify more complex boolean expressions across attributes.

Sort

19991999

This customization lets you sort the result documents by attribute name. The value supplied should be either 'asc' for ascending results or 'desc' for descending results. The attribute needs to be present in the data as well as configured as facetable and not multi-valued.

Personalization

19991999

This customization allows you to return personalized result documents by specifying the following:

Bloomreach Cookie (_br_uid_2)
The personalized value of the cookie identifier from Bloomreach. It is used to personalize search results based on the specified ID.

User ID (user_id)
The universal customer ID of the user. You only need to pass this field if your particular integration tracks customers this way. Example: anonymous_user_12345

Multi-View

19991999

View ID (view_id)
View ID is a unique identifier for a specific view of your product catalog. You can use this customization to return result documents for a specific view of your catalog. If you have multiple versions of your site, each with its own product catalog characteristics like product titles and prices, then add view_id to your call. Example: contract_7312

Custom Params

19991999

Use this customization to specify additional search API parameters. Each parameter has a key and value that will be passed directly to the API. If you, or Bloomreach support, have added custom parameters to your catalog that aren’t represented in the core list of default parameters, you can add those custom parameters here.

Attribute Stats

19991999

By enabling stats.field, you can see basic query stats, including minimum and maximum values, will be included at the end of your response documents.

Faceting

19991999

facet.field
Provide the field names to include in the facet fields.

facet.range
Provide the attribute names to include in the facet ranges. See the Product Search & Category API documentation for information about facets & facet ranges.

View Requests list

This feature allows interactive API exploration. You will find all the API requests listed here. In the above example, we entered the keyword “sofa” to view the API response with the result documents. You can click on the 🔗 link symbol to view the response document. The document counts may differ if global rules are applied. Valid documents and availability might also differ.

Using Facets

The Search module provides you with relevant facets for narrowing down the results. When you select any of these facets, the API response is updated in real-time. You can view the updated response in the View Requests list.

Differing response document count between the API responses and Catalog Management

There are a few reasons that our API responses may return a different response document count than what is reported in Catalog Management:

  • Account configurations: Your account’s configuration specifies that the Search API must not return "unavailable products.” This configuration does not affect the catalog document count, but it definitely affects the Search API response document count.
  • Product and variants: The document count encompasses both product and variants, while certain of our APIs return only product response documents.
  • Views: The document count encompasses the unique documents needed to support the variation in your product data due to multi-view overrides. Our Search API only returns response documents based on a single view
  • Invalid product data: Invalid product data is counted in document count but not made available to APIs.

Did this page help you?