Get started

The Reporting sub-API lets you retrieve performance data and insights about products within your Merchant Center account. You can use this sub-API to do the following:

  • Identify product issues.
  • Discover your top-performing products and brands.
  • Gain a better understanding of your overall product landscape.

This guide walks through common use cases to help you use reporting effectively.

You interact with the Reporting sub-API primarily through the reports.search method. This method requires you to submit a query written in the Merchant Center Query Language (MCQL). MCQL lets you:

  • Specify the data fields to retrieve.
  • Filter results based on various segments, such as date ranges or country codes.
  • Control the ordering and limits of your results.

Understand the Merchant Center Query Language

You retrieve reports by sending queries written in the Merchant Center Query Language (MCQL). The language lets you select data from different resources (called "views", like product_performance_view or product_view), filter by segments (like date or marketing_method), select metrics (like clicks or impressions), order the results, and limit the number of results.

For detailed information on the query language structure and available views, fields, and metrics, see the Merchant Center Query Language grammar.

Prerequisites

Before you use the Reporting sub-API, verify that you have a Merchant Center account that contains product data.

For specific data (performance reports) you need to have the Performance and insights role. For more information, see I need help with people and access levels. and Requirements.

Example: Identify product issues

You can identify issues affecting your products to take corrective actions. This helps you maintain compliance and improve the visibility of your products. For example, the following query retrieves all issues for products in your account, helping you verify whether your products meet policy and data quality requirements.

Calling

POST https://merchantapi.googleapis.com/reports/v1beta/accounts/{ACCOUNT_ID}/reports:search

with the following request body:

SELECT
  id,
  offer_id,
  feed_label,
  title,
  aggregated_reporting_context_status,
  item_issues
FROM product_view
WHERE aggregated_reporting_context_status = 'NOT_ELIGIBLE_OR_DISAPPROVED'

will produce a response like:

{
  "results": [
    {
      "productView": {
        "id": "online~en~US~id0"
        "offerId": "id0",
        "feedLabel": "US",
        "aggregatedReportingContextStatus": "NOT_ELIGIBLE_OR_DISAPPROVED",
        "itemIssues": [
          {
            "type": {
              "code": "invalid_string_value",
              "canonicalAttribute": "n:product_code"
            },
            "severity": {
              "severityPerReportingContext": [
                {
                  "reportingContext": "SHOPPING_ADS",
                  "disapprovedCountries": [
                    "US"
                  ]
                },
                {
                  "reportingContext": "FREE_LISTINGS",
                  "disapprovedCountries": [
                    "US"
                  ]
                }
              ],
              "aggregatedSeverity": "DISAPPROVED"
            },
            "resolution": "MERCHANT_ACTION"
          },
          {
            "type": {
              "code": "apparel_missing_brand",
              "canonicalAttribute": "n:brand"
            },
            "severity": {
              "severityPerReportingContext": [
                {
                  "reportingContext": "SHOPPING_ADS",
                  "disapprovedCountries": [
                    "US"
                  ]
                }
              ],
              "aggregatedSeverity": "DEMOTED"
            },
            "resolution": "MERCHANT_ACTION"
          }
        ]
      }
    }
  ]
}