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.

Method: reports.search

Retrieves merchant performance mertrics matching the search query and optionally segmented by selected dimensions.

HTTP request

POST https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/reports/search

Path parameters

Parameters
merchantId

string (int64 format)

Required. Id of the merchant making the call. Must be a standalone account or an MCA subaccount.

Request body

The request body contains data with the following structure:

JSON representation 
{
  "query": string,
  "pageSize": integer,
  "pageToken": string
}
Fields
query

string

Required. Query that defines performance metrics to retrieve and dimensions according to which the metrics are to be segmented.
pageSize

integer

Number of ReportRows to retrieve in a single page. Defaults to the maximum of 1000. Values above 1000 are coerced to 1000.
pageToken

string

Token of the page to retrieve. If not specified, the first page of results is returned. In order to request the next page of results, the value obtained from nextPageToken in the previous response should be used.

Response body

If successful, the response body contains data with the following structure:

Response message for the ReportService.Search method.

JSON representation 
{
  "results": [
    {
      object (ReportRow)
    }
  ],
  "nextPageToken": string
}
Fields
results[]

object (ReportRow)

Rows that matched the search query.
nextPageToken

string

Token which can be sent as pageToken to retrieve the next page. If omitted, there are no subsequent pages.

Authorization Scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/content

For more information, see the OAuth 2.0 Overview.

ReportRow

Result row returned from the search query.

JSON representation 
{
  "segments": {
    object (Segments)
  },
  "metrics": {
    object (Metrics)
  }
}
Fields
segments

object (Segments)

Segmentation dimensions requested by the merchant in the query. Dimension values are only set for dimensions requested explicitly in the query.
metrics

object (Metrics)

Metrics requested by the merchant in the query. Metric values are only set for metrics requested explicitly in the query.

Segments

Dimensions according to which metrics are segmented in the response. Values of product dimensions, e.g., offer id, reflect the state of a product at the time of the corresponding event, e.g., impression or order.

Segment fields cannot be selected in queries without also selecting at least one metric field.

Values are only set for dimensions requested explicitly in the request's search query.

JSON representation 
{
  "program": enum (Program),
  "date": {
    object (Date)
  },
  "week": {
    object (Date)
  },
  "currencyCode": string,
  "offerId": string,
  "title": string,
  "brand": string,
  "categoryL1": string,
  "categoryL2": string,
  "categoryL3": string,
  "categoryL4": string,
  "categoryL5": string,
  "productTypeL1": string,
  "productTypeL2": string,
  "productTypeL3": string,
  "productTypeL4": string,
  "productTypeL5": string,
  "customLabel0": string,
  "customLabel1": string,
  "customLabel2": string,
  "customLabel3": string,
  "customLabel4": string
}
Fields
program

enum (Program)

Program to which metrics apply, e.g., Free Product Listing.
date

object (Date)

Date in the merchant timezone to which metrics apply.
week

object (Date)

First day of the week (Monday) of the metrics date in the merchant timezone.
currencyCode

string

Currency in which price metrics are represented, e.g., if you select orderedItemSalesMicros, the returned value will be represented by this currency.
offerId

string

Merchant-provided id of the product.
title

string

Title of the product.
brand

string

Brand of the product.
categoryL1

string

Product category (1st level) in Google's product taxonomy.
categoryL2

string

Product category (2nd level) in Google's product taxonomy.
categoryL3

string

Product category (3rd level) in Google's product taxonomy.
categoryL4

string

Product category (4th level) in Google's product taxonomy.
categoryL5

string

Product category (5th level) in Google's product taxonomy.
productTypeL1

string

Product category (1st level) in merchant's own product taxonomy.
productTypeL2

string

Product category (2nd level) in merchant's own product taxonomy.
productTypeL3

string

Product category (3rd level) in merchant's own product taxonomy.
productTypeL4

string

Product category (4th level) in merchant's own product taxonomy.
productTypeL5

string

Product category (5th level) in merchant's own product taxonomy.
customLabel0

string

Custom label 0 for custom grouping of products.
customLabel1

string

Custom label 1 for custom grouping of products.
customLabel2

string

Custom label 2 for custom grouping of products.
customLabel3

string

Custom label 3 for custom grouping of products.
customLabel4

string

Custom label 4 for custom grouping of products.

Program

Programs as part of which merchant's products are listed across Google.

Enums
PROGRAM_UNSPECIFIED Not specified.
SHOPPING_ADS Shopping Ads.
FREE_PRODUCT_LISTING Free Product Listing.
FREE_LOCAL_PRODUCT_LISTING Free Local Product Listing.
BUY_ON_GOOGLE_LISTING Buy on Google Listing.

Metrics

Performance metrics. Values are only set for metrics requested explicitly in the request's search query.

JSON representation 
{
  "clicks": string,
  "impressions": string,
  "ctr": number,
  "orders": string,
  "shippedOrders": string,
  "unshippedOrders": number,
  "daysToShip": number,
  "aos": number,
  "aovMicros": number,
  "orderedItems": string,
  "orderedItemSalesMicros": string,
  "shippedItems": string,
  "unshippedItems": number,
  "shippedItemSalesMicros": string,
  "rejectedItems": string,
  "itemDaysToShip": number,
  "itemFillRate": number,
  "returnedItems": string,
  "returnsMicros": string,
  "returnRate": number
}
Fields
clicks

string (Int64Value format)

Number of clicks.
impressions

string (Int64Value format)

Number of times merchant's products are shown.
ctr

number

Click-through rate - the number of clicks merchant's products receive (clicks) divided by the number of times the products are shown (impressions).
orders

string (Int64Value format)

Number of placed orders. Excludes customer cancellations that happened within 30 minutes of placing the order.

This metric cannot be segmented by product dimensions.
shippedOrders

string (Int64Value format)

Number of fully shipped orders, reported on the last shipment date.

This metric cannot be segmented by product dimensions.
unshippedOrders

number

Number of orders not shipped or partially shipped up until the end of the queried day. If a multi-day period is specified in the search query, the returned value is the average number of unshipped orders over the days in the queried period.

This metric cannot be segmented by product dimensions.
daysToShip

number

Average number of days between an order being placed and the order being fully shipped, reported on the last shipment date.

This metric cannot be segmented by product dimensions.
aos

number

Average order size - the average number of items in an order.

This metric cannot be segmented by product dimensions.
aovMicros

number

Average order value - the average value (total price of items) of all placed orders.

The currency of the returned value is stored in the currencyCode segment. If this metric is selected, 'segments.currency_code' is automatically added to the SELECT clause in the search query (unless it is explicitly selected by the user) and the currencyCode segment is populated in the response.

This metric cannot be segmented by product dimensions.
orderedItems

string (Int64Value format)

Number of ordered items. Excludes customer cancellations that happened within 30 minutes of placing the order.
orderedItemSalesMicros

string (Int64Value format)

Total price of ordered items. Excludes shipping, taxes (US only), and customer cancellations that happened within 30 minutes of placing the order.

The currency of the returned value is stored in the currencyCode segment. If this metric is selected, 'segments.currency_code' is automatically added to the SELECT clause in the search query (unless it is explicitly selected by the user) and the currencyCode segment is populated in the response.
shippedItems

string (Int64Value format)

Number of shipped items, reported on the shipment date.
unshippedItems

number

Number of ordered items not shipped up until the end of the queried day. If a multi-day period is specified in the search query, the returned value is the average number of unshipped items over the days in the queried period.
shippedItemSalesMicros

string (Int64Value format)

Total price of shipped items, reported on the order date. Excludes shipping and taxes (US only).

The currency of the returned value is stored in the currencyCode segment. If this metric is selected, 'segments.currency_code' is automatically added to the SELECT clause in the search query (unless it is explicitly selected by the user) and the currencyCode segment is populated in the response.
rejectedItems

string (Int64Value format)

Number of ordered items canceled by the merchant, reported on the order date.
itemDaysToShip

number

Average number of days between an item being ordered and the item being
itemFillRate

number

Percentage of shipped items in relation to all finalized items (shipped or rejected by the merchant; unshipped items are not taken into account), reported on the order date. Item fill rate is lowered by merchant rejections.
returnedItems

string (Int64Value format)

Number of ordered items sent back for return, reported on the date when the merchant accepted the return.
returnsMicros

string (Int64Value format)

Total price of ordered items sent back for return, reported on the date when the merchant accepted the return.

The currency of the returned value is stored in the currencyCode segment. If this metric is selected, 'segments.currency_code' is automatically added to the SELECT clause in the search query (unless it is explicitly selected by the user) and the currencyCode segment is populated in the response.
returnRate

number

Total price of returned items divided by the total price of shipped items, reported on the order date.

If this metric is selected, 'segments.currency_code' is automatically added to the SELECT clause in the search query (unless it is explicitly selected by the user) and the currencyCode segment is populated in the response.