Ranking Diagnostics on the API

The debug data that is available on the Ranking Diagnostics dashboard can be fetched directly on the API response.
It lets you gain a deeper understanding of the search results by providing insights into the factors affecting the recall, ranking, and merchandising of products. This empowers you with a valuable, developer-friendly tool to understand the algorithm and debug via the API.

Request Parameter

To receive the debug data for a query, pass the following parameter in the Search and Category API request:
&br_diagnostics=<value>

The following table contains the allowed values for this parameter and what they mean:

Response Data

This is the structure of the response when the br_diagnostics parameter is passed:

{
  "responseHeader": {},
  "response": {},
  "facet_counts": {},
  "debug": {
    "recall": {},
    "merchandising": {},
    "ranking": {}
  }
}

Here, the debug response object contains the debugging data for the query or category that the search was made for.

🚧

Avoid Timeout Errors

Avoid using the br_diagnostics parameter on * query requests to avoid Timeout Errors (Code 504).

The following sections explain the individual components of the debug object.
Note that you will see only those debug components that you requested based on the parameter value.

Recall

The recall response object helps debug the different rules applied to that query/category that impact the recall set. Here is a detailed guide on how Bloomreach considers products for recall and the factors affecting it that are received in the response. Given below is a sample API response retrieving the debug data under the recall response object.

Here is an example of the recall object:

{
  "recall": {
    "merchandising_rules": {
      "products_added_to_recall": [],
      "attribute_include": [],
      "attribute_exclude": [],
      "products_blocklisted": []
    },
    "queryRelaxation": {},
    "queryRedirect": {},
    "querySpellCorrect": {
      "querySpellCorrected": false,
      "new.query": ""
    },
    "synonyms": {
      "dashboard": [],
      "canonicals": [],
      "derived": []
    }
  }
}

To only get this individual object in the debug response, pass the parameter as: &br_diagnostics=recall.

Here are some articles to help you better understand these fields and use them for debugging:

• Adding Products to Recall
• Query Spell Correction and Relaxation
• Synonyms

Ranking

The ranking response object helps debug the ranking of products in the recall of that query/category. Here is a detailed guide on how Bloomreach ranks the selected products and the factors affecting them. Given below is a sample API response retrieving the debug data under the ranking response object.

Here is an example of the ranking object:

{
  "ranking": {
    "product1": {
      "pid": "288983",
      "totalScore": 93.63758,
      "performance": 98.15912,
      "relevance": 94.471634
    },
    "product2": {
      "pid": "8434",
      "totalScore": 90.70463,
      "performance": 94.661156,
      "relevance": 94.657486,
      "merchandisingRulesApplied": {
        "softBoostBury": {
          "attributeSoftBoost": [
            "BR_TS_rank: \"\\-1000\""
          ]
        }
      }
    }
  }
}

To only get this individual object in the debug response, pass the parameter as: &br_diagnostics=ranking.

Here are some articles to help you better understand these fields and use them for debugging:

• Ranking Signals
• Boost and Bury

Merchandising

The merchandising response object helps debug all the merchandising rules applied to that query/category. This part digs deeper into all the merchandising operations that are applied to queries or categories on the dashboard that affect the products. The response is an aggregation of all the applied operations and their details.

Here is an example of the merchandising object:

{
  "merchandising": {
    "products_boosted": [],
    "products_buried": [],
    "attributes_boosted": [],
    "attributes_buried": [],
    "products_locked": [],
    "facets_boosted": {},
    "facets_buried": {},
    "default_facetvalue_limit": 200,
    "default_facetvalue_order": "asc",
    "default_facetvalue_sort": "alpha",
    "max_facetvalue": {},
    "facets_always_shown": [],
    "facets_always_hidden": [],
    "facet_aliases": {},
    "facetvalues_boosted": {},
    "facetvalues_buried": {},
    "facetvalues_aliases": {},
    "max_facets": 25,
    "facetvalue_merge": {},
    "facetvalues_always_hidden": {},
    "facetvalue_range": {}
  }
}

To only get this individual object in the debug response, pass the parameter as: &br_diagnostics=merchandising.

Here are some articles to help you better understand these fields and use them for debugging:

• Boost and Bury
• Sequential Locking Products
• Facet Management

FAQs

1. Can this debug info from the API be used for post-processing on every search/category request?
   No, these requests are rate-limited at 1 QPS. You are advised to use this only for debugging purposes.

1. Do we support debugging on all Discovery APIs?
   Debugging is supported on the Product Search and Category API.
2. Does the API response contain all the information from the ranking Diagnostics Tool on the dashboard?
   Not yet, this is the first iteration of the API support for Ranking Diagnostics and we have targeted to roll out the most relevant data first. We will be making further enhancements to this feature.
3. Is SLA applicable when the debug param is requested on the API?
   No. Since debug data could potentially be very large, SLAs do not apply on API requests with the debug parameter.