Query search analytics

The property as returned by List properties, for example https://example.com/ or sc-domain:example.com. A bare host such as example.com also works: see The site parameter. Missing returns 400 missing_site.

First day, YYYY-MM-DD. Missing returns 400 missing_dates; any other format returns 400 invalid_date. The same applies to endDate.

Last day, YYYY-MM-DD. RankParse checks only the shape of the dates. Google applies its own range rules (such as its history window), and a request Google rejects comes back as 502 gsc_api_error with Google's message.

Comma-separated list of query, page, country, device, date and searchAppearance. Unknown names are dropped silently; if none is valid the call returns 400 invalid_dimensions. The order you give is the order of keys in each row.

web, image, video, news, googleNews or discover. Anything else returns 400 invalid_search_type. Google does not offer every dimension for discover and googleNews (query is not available there).

Keep rows whose page URL equals this exactly.

Keep rows whose page URL contains this text, for a segment such as /blog/. Sending it with filterPage returns 400 conflicting_filters.

Keep rows whose query equals this exactly. Can be combined with either page filter; all must match.

Keep rows whose query contains this text. Sending it with filterQuery returns 400 conflicting_filters.

Keep traffic from one country: an ISO 3166-1 alpha-3 code such as USA or GBR. A two-letter code such as US is accepted for common countries. Anything else returns 400 invalid_country.

Keep traffic from one device type: desktop, mobile or tablet. Anything else returns 400 invalid_device.

Keep rows whose query matches this RE2 regular expression, 1 to 500 characters. For example ^(?:\S+\s+){7,}\S+$ keeps queries of 8 or more words. Sending it with minQueryWords returns 400 conflicting_filters; a length outside 1 to 500 returns 400 invalid_param; a pattern that is clearly not valid RE2 (unbalanced parentheses, an unclosed [, a quantifier with nothing to repeat, lookahead, lookbehind or a backreference) returns 400 invalid_filter_regex before Google is called.

Keep queries of at least this many words, from 2 to 50. The same filter as the regular expression above, built for you: 8 means 8 or more words. Anything else returns 400 invalid_param.

Keep rows with an average position at or above this number. Not a number returns 400 invalid_param.

Keep rows with an average position at or below this number.

Keep rows with a CTR at or below this, as a fraction from 0 to 1 (0.03 means 3%).

Keep rows with at least this many impressions. With compareTo, a row passes when either period meets it.

Keep rows with at least this many clicks (same rule with compareTo).

Offset into Google's rows (ordered by clicks), to read past the first page. Use the next_start_row from a response that says has_more. A negative or non-integer value returns 400 invalid_param, and so does any value above 0 together with compareTo.

previous_period also reads the period of the same length that ends the day before startDate and adds previous, delta and status to every row. Anything else returns 400 invalid_compare_to. It cannot be combined with startRow above 0 or with the date dimension (both return 400 invalid_param). See Comparing periods.

Order the rows by clicks, impressions, ctr or position; with compareTo also by clicks_delta, impressions_delta, ctr_delta or position_delta. The default order is Google's (clicks, descending). Anything else returns 400 invalid_sort.

asc or desc. The default is largest first, except position, where the best (lowest) comes first. For the biggest losers use sort=clicks_delta&order=asc. Anything else returns 400 invalid_order.

Comma-separated subset of keys, clicks, impressions, ctr, position, previous, delta and status. Each row then carries only those fields, which keeps a large response small. An unknown name returns 400 invalid_fields.

Rows to return. Values above 1000 are lowered to 1000; a missing, zero or non-numeric value uses 100.

The property you queried.

Echo of the request.

Echo of the request.

The dimensions that were accepted, in order.

Echoed only when you sent it. The same goes for filterPageContains, filterQuery and minQueryWords.

Echoed when you sent filterQueryRegex, or minQueryWords, in which case it is the regular expression that was built from it.

The search type used.

Present only when RankParse matched your site to a different property; site then holds the property it used.

Echoed only when you sent country, as the alpha-3 code that was used. The same goes for device.

Rows in this response.

Rows that passed every filter before rowLimit trimmed them, out of the rows read from Google.

true when Google returned a full page of rows, so more may exist. Filters, sorting and comparison work on that page only.

Present when has_more is true: pass it as startRow to read the next page.

With compareTo: the startDate and endDate of the period compared against.

With compareTo: true when either period hit the 1000-row read, so a row marked new or lost may only be outside the rows read.

Result rows, at most rowLimit, in Google's order (by clicks, descending). Empty when Google has no data for the request.

How Google aggregated the rows (byProperty, byPage or auto). Omitted when Google does not send it.