Exploring Catalog Data & Customizing API

💡 Prerequisites

Knowledge Prerequisites
We recommend reading the following guides before starting:

Catalog Management: This guide introduces you to the Catalog Management feature.
Understanding Feed & Configuring Attributes: This guide walks you through the process of understanding your feed and customizing attributes using the Catalog Management feature.

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)

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.

As you start typing your query, both keyword and product suggestions start to appear. Right above the suggested keywords, you can find the exact date and time when the last Keyword Autosuggest index update was made. This update is run automatically every day, so if you make any new Autosuggest changes after the displayed time, they will not be reflected until the next scheduled daily update. To avoid this, you should immediately run an Autosuggest index update manually by clicking on "Update daily keyword autosuggest index now". To configure Autosuggest Settings, visit this article.

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

Keyword/Category dropdown

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)

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

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

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

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

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

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

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

facet.field

V3 Facet format: Provide the field names to include in the facet object response.
Legacy Facet format: Provide the field names to include in the facet_fields response.

facet.range

V3 Facet format: Provide the attribute names to include in the facet object response.
Legacy Facet format: Provide the attribute names to include in the facet_ranges response.

📘
Customers whose go-live date is after September 7, 2023 will be on V3 Facet response format by default. If you’re on the legacy format and would like to implement the new Facet response format, kindly contact your Bloomreach Services representative.

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.