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.

The API is bounded by internal limitations of Search Console and does not guarantee to return all data rows but rather top ones.

See limits to the amount of data available.

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 URL of the property as defined in Search Console. Examples: http://www.example.com/ (for a URL-prefix property) or sc-domain:example.com (for a Domain property)

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
  ],
  "type": 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 PT time (UTC - 7:00/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 PT time (UTC - 7:00/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. You can use any dimension name in dimensionFilterGroups[].filters[].dimension as well as "date". 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 Deprecated, use type instead
type string [Optional] Filter results to the following type:
  • "discover": Discover results
  • "googleNews": Results from news.google.com and the Google News app on Android and iOS. Doesn't include results from the "News" tab in Google Search.
  • "news": Search results from the "News" tab in Google Search.
  • "image": Search results from the "Image" tab in Google Search.
  • "video": Video search results
  • "web": [Default] Filter results to the combined ("All") tab in Google Search. Does not include Discover or Google News 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. Max length 4096 characters. 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". The full list of values and descriptions is also available in the help documentation.
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).
  • "includingRegex": An RE2 syntax regular expression that must be matched.
  • "excludingRegex": An RE2 syntax regular expression that must not be matched.
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.
  • "byNewsShowcasePanel": Aggregate values by News Showcase panel. This must be used in combination with the NEWS_SHOWCASE searchAppearance filter and either type=discover or type=googleNews. If you group by page, filter by page, or filter to another searchAppearance, you can't aggregate by byNewsShowcasePanel.
  • "byPage": Aggregate values by URI.
  • "byProperty": Aggregate values by property. Not supported for type=discover or type=googleNews
rowLimit integer [Optional; Valid range is 1–25,000; Default is 1,000] The maximum number of rows to return. To page through results, use the startRow offset.
startRow integer [Optional; Default is 0] Zero-based index of the first row in the response. Must be a non-negative number. If startRow exceeds the number of results for the query, the response will be a successful response with zero rows.
dataState string [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.

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 together, 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.