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.

For details on how to construct your query, see the Query Language guide.
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)
  },
  "productView": {
    object (ProductView)
  }
}
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.
productView

object (ProductView)

Product fields requested by the merchant in the query. Field values are only set if the merchant queries ProductView. productView field is available only to allowlisted users who can query the ProductView table.

Segments

Dimensions according to which metrics are segmented in the response. Values of product dimensions, such as offerId, reflect the state of a product at the time of the corresponding event, for example, 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)
  },
  "customerCountryCode": string,
  "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, for example, 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.
customerCountryCode

string

Code of the country where the customer is located at the time of the event. Represented in the ISO 3166 format.

If the customer country cannot be determined, a special 'ZZ' code is returned.
currencyCode

string

Currency in which price metrics are represented, for example, 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 type (1st level) in merchant's own product taxonomy.
productTypeL2

string

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

string

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

string

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

string

Product type (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,
  "conversions": number,
  "conversionValueMicros": string,
  "conversionRate": 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).
conversions

number

Number of conversions attributed to the product, reported on the conversion date. Depending on the attribution model, a conversion might be distributed across multiple clicks, where each click gets its own credit assigned. This metric is a sum of all such credits.

The metric is currently available only for the FREE_PRODUCT_LISTING program.
conversionValueMicros

string (Int64Value format)

Value of conversions in micros attributed to the product, reported on the conversion date.

The metric is currently available only for the FREE_PRODUCT_LISTING program.

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.
conversionRate

number

Number of conversions divided by the number of clicks, reported on the impression date.

The metric is currently available only for the FREE_PRODUCT_LISTING program.
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 and customerCountryCode.
shippedOrders

string (Int64Value format)

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

This metric cannot be segmented by product dimensions and customerCountryCode.
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 and customerCountryCode.
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 and customerCountryCode.
aos

number

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

This metric cannot be segmented by product dimensions and customerCountryCode.
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 and customerCountryCode.
orderedItems

string (Int64Value format)

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

This metric cannot be segmented by customerCountryCode.
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.

This metric cannot be segmented by customerCountryCode.
shippedItems

string (Int64Value format)

Number of shipped items, reported on the shipment date.

This metric cannot be segmented by customerCountryCode.
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.

This metric cannot be segmented by customerCountryCode.
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.

This metric cannot be segmented by customerCountryCode.
rejectedItems

string (Int64Value format)

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

This metric cannot be segmented by customerCountryCode.
itemDaysToShip

number

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

This metric cannot be segmented by customerCountryCode.
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.

This metric cannot be segmented by customerCountryCode.
returnedItems

string (Int64Value format)

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

This metric cannot be segmented by customerCountryCode.
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.

This metric cannot be segmented by customerCountryCode.
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.

This metric cannot be segmented by customerCountryCode.

ProductView

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

JSON representation 
{
  "id": string,
  "offerId": string,
  "title": string,
  "brand": string,
  "currencyCode": string,
  "priceMicros": string,
  "languageCode": string,
  "condition": string,
  "channel": enum (Channel),
  "availability": string,
  "shippingLabel": string,
  "gtin": [
    string
  ],
  "itemGroupId": string,
  "creationTime": string,
  "expirationDate": {
    object (Date)
  },
  "aggregatedDestinationStatus": enum (AggregatedDestinationStatus),
  "itemIssues": [
    {
      object (ItemIssue)
    }
  ]
}
Fields
id

string

The REST ID of the product, in the form of channel:contentLanguage:targetCountry:offerId. Content API methods that operate on products take this as their productId parameter.

Should always be included in the SELECT clause.
offerId

string

Merchant-provided id of the product.
title

string

Title of the product.
brand

string

Brand of the product.
currencyCode

string

Product price currency code (for example, ISO 4217). Absent if product price is not available.
priceMicros

string (Int64Value format)

Product price specified as micros in the product currency. Absent in case the information about the price of the product is not available.
languageCode

string

Language code of the product in BCP 47 format.
condition

string

Condition of the product.
channel

enum (Channel)

Channel of the product (online versus local).
availability

string

Availability of the product.
shippingLabel

string

The normalized shipping label specified in the feed
gtin[]

string

GTIN of the product.
itemGroupId

string

Item group ID provided by the merchant for grouping variants together.
creationTime

string (Timestamp format)

The time the merchant created the product in timestamp seconds.
expirationDate

object (Date)

Expiration date for the product. Specified on insertion.
aggregatedDestinationStatus

enum (AggregatedDestinationStatus)

Aggregated destination status.
itemIssues[]

object (ItemIssue)

accounts.list of item issues for the product.

Channel

The channel of the product.

Enums
CHANNEL_UNSPECIFIED Indicates that the channel is unspecified.
LOCAL Indicates that the channel is local.
ONLINE Indicates that the channel is online.

AggregatedDestinationStatus

The status of the product aggregated for all destinations.

Enums
AGGREGATED_STATUS_UNSPECIFIED Undefined aggregated status.
NOT_ELIGIBLE_OR_DISAPPROVED Offer isn't eligible, or is disapproved for all destinations.
PENDING Offer's status is pending in all destinations.
ELIGIBLE_LIMITED Offer is eligible for some (but not all) destinations.
ELIGIBLE Offer is eligible for all destinations.

ItemIssue

Item issue associated with the product.

JSON representation 
{
  "issueType": {
    object (ItemIssueType)
  },
  "severity": {
    object (ItemIssueSeverity)
  },
  "resolution": enum (IssueResolution)
}
Fields
issueType

object (ItemIssueType)

Item issue type.
severity

object (ItemIssueSeverity)

Item issue severity.
resolution

enum (IssueResolution)

Item issue resolution.

ItemIssueType

Type of the item issue.

JSON representation 
{
  "canonicalAttribute": string
}
Fields
canonicalAttribute

string

Canonical attribute name for attribute-specific issues.

ItemIssueSeverity

Severity of an issue per destination in a region, and aggregated severity.

JSON representation 
{
  "severityPerDestination": [
    {
      object (IssueSeverityPerDestination)
    }
  ],
  "aggregatedSeverity": enum (AggregatedIssueSeverity)
}
Fields
severityPerDestination[]

object (IssueSeverityPerDestination)

Item issue severity for every destination.
aggregatedSeverity

enum (AggregatedIssueSeverity)

Severity of an issue aggregated for destination.

IssueSeverityPerDestination

Issue severity for all affected regions in a destination.

JSON representation 
{
  "disapprovedCountries": [
    string
  ],
  "demotedCountries": [
    string
  ],
  "destination": string
}
Fields
disapprovedCountries[]

string

accounts.list of disapproved countries in the destination.
demotedCountries[]

string

accounts.list of demoted countries in the destination.
destination

string

Issue destination.

AggregatedIssueSeverity

Severity of an issue aggregated for a destination.

Enums
AGGREGATED_ISSUE_SEVERITY_UNSPECIFIED Undefined Issue severity.
DISAPPROVED Issue disapproves the product in at least one of the selected destinations.
DEMOTED Issue demotes the product in all selected destinations it affects.
PENDING Issue resolution is PENDING_PROCESSING.

IssueResolution

How to resolve the issue.

Enums
UNKNOWN Unknown resolution type.
MERCHANT_ACTION The merchant has to fix the issue.
PENDING_PROCESSING The issue will be resolved automatically (for example, image crawl), or Google review. No merchant action is required now. Resolution might lead to another issue (for example, if crawl fails).