Query your data with filters and parameters that you define. Returns zero or more rows grouped by the row keys that you define. You must define a date range of one or more days.

When date is one of the group by values, any days without data are omitted from the result list. If you need to know which days have data, issue a broad date range query grouped by date for any metric, and see which day rows are returned.

Scopes

You will need authorization for at least one of the following scopes to make a valid call:

  • https://www.googleapis.com/auth/webmasters
  • https://www.googleapis.com/auth/webmasters.readonly

If unset, the scope for this method defaults to https://www.googleapis.com/auth/webmasters. You can set the scope for this method like this: webmasters3 --scope <scope> searchanalytics query ...

Required Scalar Argument

  • <site-url> (string)
    • The site's URL, including protocol. For example: http://www.example.com/

Required Request Value

The request value is a data-structure with various fields. Each field may be a simple scalar or another data-structure. In the latter case it is advised to set the field-cursor to the data-structure's field to specify values more concisely.

For example, a structure like this:

SearchAnalyticsQueryRequest:
  aggregation-type: string
  data-state: string
  dimensions: [string]
  end-date: string
  row-limit: integer
  search-type: string
  start-date: string
  start-row: integer

can be set completely with the following arguments which are assumed to be executed in the given order. Note how the cursor position is adjusted to the respective structures, allowing simple field names to be used most of the time.

  • -r . aggregation-type=et

    • [Optional; Default is "auto"] How data is aggregated. If aggregated by property, all data for the same property is aggregated; if aggregated by page, all data is aggregated by canonical URI. If you filter or group by page, choose AUTO; otherwise you can aggregate either by property or by page, depending on how you want your data calculated; see the help documentation to learn how data is calculated differently by site versus by page.

      Note: If you group or filter by page, you cannot aggregate by property.

      If you specify any value other than AUTO, the aggregation type in the result will match the requested type, or if you request an invalid type, you will get an error. The API will never change your aggregation type if the requested type is invalid. * data-state=magna - [Optional] If "all" (case-insensitive), data will include fresh data. If "final" (case-insensitive) or if this parameter is omitted, the returned data will include only finalized data. * dimensions=no - [Optional] Zero or more dimensions to group results by. Dimensions are the group-by values in the Search Analytics page. Dimensions are combined to create a unique row key for each row. Results are grouped in the order that you supply these dimensions. - Each invocation of this argument appends the given value to the array. * end-date=ipsum - [Required] End date of the requested date range, in YYYY-MM-DD format, in PST (UTC - 8:00). Must be greater than or equal to the start date. This value is included in the range. * row-limit=73 - [Optional; Default is 1000] The maximum number of rows to return. Must be a number from 1 to 5,000 (inclusive). * search-type=at - [Optional; Default is "web"] The search type to filter for. * start-date=sanctus - [Required] Start date of the requested date range, in YYYY-MM-DD format, in PST time (UTC - 8:00). Must be less than or equal to the end date. This value is included in the range. * start-row=21 - [Optional; Default is 0] Zero-based index of the first row in the response. Must be a non-negative number.

About Cursors

The cursor position is key to comfortably set complex nested structures. The following rules apply:

  • The cursor position is always set relative to the current one, unless the field name starts with the . character. Fields can be nested such as in -r f.s.o .
  • The cursor position is set relative to the top-level structure if it starts with ., e.g. -r .s.s
  • You can also set nested fields without setting the cursor explicitly. For example, to set a value relative to the current cursor position, you would specify -r struct.sub_struct=bar.
  • You can move the cursor one level up by using ... Each additional . moves it up one additional level. E.g. ... would go three levels up.

Optional Output Flags

The method's return value a JSON encoded structure, which will be written to standard output by default.

  • -o out
    • out specifies the destination to which to write the server's result to. It will be a JSON-encoded structure. The destination may be - to indicate standard output, or a filepath that is to contain the received bytes. If unset, it defaults to standard output.

Optional General Properties

The following properties can configure any call, and are not specific to this method.

  • -p alt=string

    • Data format for the response.

  • -p fields=string

    • Selector specifying which fields to include in a partial response.

  • -p key=string

    • API key. Your API key identifies your project and provides you with API access, quota, and reports. Required unless you provide an OAuth 2.0 token.

  • -p oauth-token=string

    • OAuth 2.0 token for the current user.

  • -p pretty-print=boolean

    • Returns response with indentations and line breaks.

  • -p quota-user=string

    • An opaque string that represents a user for quota purposes. Must not exceed 40 characters.

  • -p user-ip=string

    • Deprecated. Please use quotaUser instead.