Version v2 of the Content API is scheduled for sunset on September 30th, 2021. Onboarding to v2 ended on April 30, 2021. To avoid disruptions with your integration, please migrate to v2.1 as soon as possible.

For more information, see Migrating to v2.1 and this blog post.

Segmentation

Segmentation, available in Merchant Center custom reports, can be implemented in the Reporting API by adding the appropriate field to a query. For example, querying for segments.program results in a report with a row for each program (Shopping Ads, Free product listings, etc.) that includes the metrics (impressions, clicks, etc.) for that program as specified in the SELECT clause.

As with custom reports in the Merchant Center, you can specify multiple segments in the same query with the Reporting API.

The following sample query retrieves the clicks for all products in your account during a 30-day period, segmented by program and offer_id:

SELECT
  segments.program,
  segments.offer_id,
  metrics.clicks
FROM MerchantPerformanceView
WHERE segments.date BETWEEN '2020-11-01' AND '2020-11-30'

The results from sending this query to reports.search is a row specifying the clicks for each combination of offer_id and program, like in this sample JSON string:

{
  "results": [
    {
      "segments": {
        "program": "SHOPPING_ADS",
        "offerId": "12345"
      },
      "metrics": {
        "clicks": "38"
      }
    },
    {
      "segments": {
        "program": "SHOPPING_ADS",
        "offerId": "12346"
      },
      "metrics": {
        "clicks": "125"
      }
    },
    {
      "segments": {
        "program": "FREE_PRODUCT_LISTING",
        "offerId": "12346"
      },
      "metrics": {
        "clicks": "23"
      }
    },
    {
      "segments": {
        "program": "SHOPPING_ADS",
        "offerId": "12347"
      },
      "metrics": {
        "clicks": "8"
      }
    },
    {
      "segments": {
        "program": "FREE_PRODUCT_LISTING",
        "offerId": "12347"
      },
      "metrics": {
        "clicks": "3"
      }
    }
  ]
}

Category and product type

The Merchant Center Query Language supports segmenting metrics by two groups of attributes that you can define to organize your inventory:

Category levels (segments.category_l1, segments.category_l2, etc.)
Categories from Google's product taxonomy. Google might auto-assign the category to your product if none was provided, or further refine the provided category.
Product type levels (segments.product_type_l1, segments.product_type_l2, etc.)
Product types that you assign based on your categorization. Unlike the category levels, there is no predefined set of supported values.

Both the category and product type attributes are organized in a hierarchy with multiple levels. The product specification separates each level with the > character, but you select each level of the hierarchy separately in reports.

For example, consider a product with the following product type levels:

Home & Garden > Kitchen & Dining > Kitchen Appliances > Refrigerators

Reports will return each level in its own field, as follows:

Segment Value
segments.product_type_l1 Home & Garden
segments.product_type_l2 Kitchen & Dining
segments.product_type_l3 Kitchen Appliances
segments.product_type_l4 Refrigerators

Currency and price metrics

The segments.currency_code field of a ReportRow indicates the currency in which price metrics such as metrics.order_item_sales_micros are returned. Since this is important in order to properly interpret these metrics, the returned ReportRow will automatically include segments.currency_code whenever you select one of the price metrics below.

  • metrics.aov_micros
  • metrics.ordered_item_sales_micros
  • metrics.returns_micros
  • metrics.shipped_item_sales_micros

Buy on Google metrics

The Merchant Center Query Language supports two categories of metrics for Buy on Google orders: item-level metrics and order-level metrics.

item-level metrics

Metrics calculated based on the items within orders, and associated with the product dimensions of the items in each order.

  • metrics.item_days_to_ship
  • metrics.item_fill_rate
  • metrics.ordered_items
  • metrics.ordered_item_sales_micros
  • metrics.rejected_items
  • metrics.returned_items
  • metrics.return_rate
  • metrics.returns_micros
  • metrics.shipped_items
  • metrics.shipped_item_sales_micros
  • metrics.unshipped_items
order-level metrics

Metrics calculated on a per-order basis.

  • metrics.aos
  • metrics.aov_micros
  • metrics.days_to_ship
  • metrics.orders
  • metrics.shipped_orders
  • metrics.unshipped_orders

Order-level metrics are not associated with the product dimensions of the items in each order.

You can select item-level metrics in combination with any available segment. However, selecting order-level metrics in combination with any of the following product dimension segments will fail:

  • segments.brand
  • segments.category_l1, segments.category_l2, segments.category_l3, segments.category_l4, segments.category_l5
  • segments.custom_label1, segments.custom_label2, segments.custom_label3, segments.custom_label4, segments.custom_label5
  • segments.offer_id
  • segments.product_type_l1, segments.product_type_l2, segments.product_type_l3, segments.product_type_l4, segments.product_type_l5
  • segments.title

Find out more

For a complete list of segments, check out the documentation.