Search Analytics: query

Requires authorization

Query your search traffic data with filters and parameters that you define. The method returns zero or more rows grouped by the row keys (dimensions) that you define. You must define a date range of one or more days.

When date is one of the dimensions, any days without data are omitted from the result list. To learn which days have data, issue a query without filters grouped by date, for the date range of interest.

Results are sorted by click count descending. If two rows have the same click count, they are sorted in an arbitrary way.

See the python sample for calling this method.

JSON POST Example:
POST https://www.googleapis.com/webmasters/v3/sites/https%3A%2F%2Fwww.example.com%2F/searchAnalytics/query?key={MY_API_KEY}
{
  "startDate": "2015-04-01",
  "endDate": "2015-05-01",
  "dimensions": ["country","device"]
}
Try it now.

Request

HTTP request

POST https://www.googleapis.com/webmasters/v3/sites/siteUrl/searchAnalytics/query

Parameters

Parameter name Value Description
Path parameters
siteUrl string The URI of the property as defined in Search Console. Examples: http://www.example.com/ or android-app://com.example/

Authorization

This request requires authorization with at least one of the following scopes (read more about authentication and authorization).

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

Request body

In the request body, supply data with the following structure:

{
  "startDate": string,
  "endDate": string,
  "dimensions": [
    string
  ],
  "searchType": string,
  "dimensionFilterGroups": [
    {
      "groupType": string,
      "filters": [
        {
          "dimension": string,
          "operator": string,
          "expression": string
        }
      ]
    }
  ],
  "aggregationType": string,
  "rowLimit": integer,
  "startRow": integer
}
Property name Value Description Notes
startDate string [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.
endDate string [Required] End date of the requested date range, in YYYY-MM-DD format, in PST time (UTC - 8:00). Must be greater than or equal to the start date. This value is included in the range.
dimensions[] list [Optional] Zero or more dimensions to group results by. Results are grouped in the order that you supply these dimensions. The list of valid dimension names is shown in the dimensionFilterGroups[].filters[].dimension description. The grouping dimension values are combined to create a unique key for each result row. If no dimensions are specified, all values will be combined into a single row. There is no limit to the number of dimensions that you can group by, but you cannot group by the same dimension twice. Example: [country, device]
searchType string [Optional] The search type to filter for.

Acceptable values are:
  • "image": Image search results
  • "video": Video search results
  • "web": [Default] Web search results
dimensionFilterGroups[] list [Optional] Zero or more groups of filters to apply to the dimension grouping values. All filter groups must match in order for a row to be returned in the response. Within a single filter group, you can specify whether all filters must match, or at least one must match.
dimensionFilterGroups[].groupType string Whether all filters in this group must return true ("and"), or one or more must return true (not yet supported).

Acceptable values are:
  • "and": All filters in the group must return true for the filter group to be true.
dimensionFilterGroups[].filters[] list [Optional] Zero or more filters to test against the row. Each filter consists of a dimension name, an operator, and a value. Examples:
country equals FRA
query contains mobile use
device notContains tablet
dimensionFilterGroups[].filters[].dimension string The dimension that this filter applies to. You can filter by any dimension listed here, even if you are not grouping by that dimension.

Acceptable values are:
  • "country": Filter against the specified country, as specified by 3-letter country code (ISO 3166-1 alpha-3).
  • "device": Filter results against the specified device type. Supported values:
    • DESKTOP
    • MOBILE
    • TABLET
  • "page": Filter against the specified URI string.
  • "query": Filter against the specified query string.
  • "searchAppearance": Filter against a specific search result feature. To see a list of available values, run a query grouped by "searchAppearance".
dimensionFilterGroups[].filters[].operator string [Optional] How your specified value must match (or not match) the dimension value for the row.

Acceptable values are:
  • "contains": The row value must either contain or equal your expression (non-case-sensitive).
  • "equals": [Default] Your expression must exactly equal the row value (case-sensitive for page and query dimensions).
  • "notContains": The row value must not contain your expression either as a substring or a (non-case-sensitive) complete match.
  • "notEquals": Your expression must not exactly equal the row value (case-sensitive for page and query dimensions).
dimensionFilterGroups[].filters[].expression string The value for the filter to match or exclude, depending on the operator.
aggregationType string

[Optional] 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.



Acceptable values are:
  • "auto": [Default] Let the service decide the appropriate aggregation type.
  • "byPage": Aggregate values by URI.
  • "byProperty": Aggregate values by property.
rowLimit integer [Optional; Valid range is 1–5,000; Default is 1,000] The maximum number of rows to return. The API does not support paged results.
startRow integer [Optional; Default is 0] Zero-based index of the first row in the response. Must be a non-negative number.

Response

Results are grouped according to the dimensions specified in the request. All values with the same set of dimension values will be grouped into a single row. For example, if you group by the country dimension, all results for "usa" will be grouped goether, all results for "mdv" will be grouped together, and so on. If you grouped by country and device, then all results for "usa, tablet" will be grouped, all results for "usa, mobile" will be grouped, and so on. See the Search Analytics report documentation to learn the specifics of how clicks, impressions, and so on are calculated, and what they mean.

Results are sorted by click count, in descending order, unless you group by date, in which case results are sorted by date, in ascending order (oldest first, newest last). If there is a tie between two rows, the sort order is arbitrary.

See the rowLimit property in the request to learn the maximum number of values that can be returned.

{
  "rows": [
    {
      "keys": [
        string
      ],
      "clicks": double,
      "impressions": double,
      "ctr": double,
      "position": double
    }
  ],
  "responseAggregationType": string
}
Property name Value Description Notes
rows[] list A list of rows grouped by the key values in the order given in the query.
rows[].keys[] list A list of the dimension values for that row, grouped according to the dimensions in the request, in the order specified in the request.
rows[].clicks double Click count for the row.
rows[].impressions double Impression count for the row.
rows[].ctr double Click Through Rate (CTR) for the row. Values range from 0 to 1.0, inclusive.
rows[].position double Average position in search results.
responseAggregationType string How the results were aggregated. See the help documentation to learn how data is calculated differently by site versus by page.

Acceptable values are:
  • "auto"
  • "byPage": Results were aggregated by page.
  • "byProperty": Results were aggregated by property.

Try it!

Use the APIs Explorer below to call this method on live data and see the response.