Run a custom search-analytics query
The tool groups and counts search data by the fields you choose. Use it when no named tool asks the question you have. A named tool is the better call when one fits, because it also classifies and explains its rows. This tool only groups and counts. You can group by date, query, page, searchEngine, and searchVertical. Those are the columns the data has. There is no country or device breakdown for either engine. Bing Webmaster Tools exposes none on any traffic report, and Google's split is not stored here. Every result is for the whole property. Asking for country or device is an error. It is not an empty result. Filters are a field, an operator, and a value, and they are combined with AND. There is no OR, and filters cannot be nested. Text fields, query and page, take eq, contains, notContains, startsWith, and endsWith, matched without regard to case. Metric fields, clicks, impressions, ctr, and position, take eq, gt, gte, lt, and lte. Metric filters run after the engines are merged, so a threshold is on the row you see. page is matched with the scheme, www, and trailing slash removed, so use contains for a section such as /blog/. Filtering a field you do not group by is allowed. position is null on every row unless you group by searchEngine. Google's and Bing's position scales are not confirmed to be comparable, so a blended figure would not be a real number on either engine. Add searchEngine to the grouping to get position. Read sources before you trust a missing row. A request that does not touch query or page is served from the complete daily totals, and it agrees exactly with get_performance_trend. A request grouped or filtered by query alone, or by page alone, is served from a breakdown Google stores as about the top 5,000 rows per day, so a missing row is not evidence of no traffic. Using query and page together reads the deeper raw feed. sources.read false means that engine was not read at all, because it is not attached or it was left out. That is different from measuring zero. truncated covers both your limit and the read's own scan ceiling.
get_advanced_search_analyticsThe tool groups and counts search data by the fields you choose.
Use it when no named tool asks the question you have. A named tool is the better call when one fits, because it also classifies and explains its rows. This tool only groups and counts.
You can group by date, query, page, searchEngine, and searchVertical. Those are the columns the data has. There is no country or device breakdown for either engine. Bing Webmaster Tools exposes none on any traffic report, and Google's split is not stored here. Every result is for the whole property. Asking for country or device is an error. It is not an empty result.
Filters are a field, an operator, and a value, and they are combined with AND. There is no OR, and filters cannot be nested. Text fields, query and page, take eq, contains, notContains, startsWith, and endsWith, matched without regard to case. Metric fields, clicks, impressions, ctr, and position, take eq, gt, gte, lt, and lte. Metric filters run after the engines are merged, so a threshold is on the row you see. page is matched with the scheme, www, and trailing slash removed, so use contains for a section such as /blog/. Filtering a field you do not group by is allowed.
position is null on every row unless you group by searchEngine. Google's and Bing's position scales are not confirmed to be comparable, so a blended figure would not be a real number on either engine. Add searchEngine to the grouping to get position.
Read sources before you trust a missing row. A request that does not touch query or page is served from the complete daily totals, and it agrees exactly with get_performance_trend. A request grouped or filtered by query alone, or by page alone, is served from a breakdown Google stores as about the top 5,000 rows per day, so a missing row is not evidence of no traffic. Using query and page together reads the deeper raw feed. sources.read false means that engine was not read at all, because it is not attached or it was left out. That is different from measuring zero. truncated covers both your limit and the read's own scan ceiling.
Parameters
| Parameter | Type | Required | Notes |
|---|---|---|---|
site | string | Yes | The site to look up, as a bare domain ("example.com") or a URL. The tool strips the scheme, www, path, and trailing slash. The site must belong to a workspace you own. Call list_sites first if you are not sure of the exact domain. |
dimensions | ("date" | "query" | "page" | "searchEngine" | "searchVertical")[] | No | What to group rows by. An empty list returns one row for the whole window. Order is cosmetic. Defaults to ["query"]. |
filters | ({ field, operator, value })[] | No | Predicates, ANDed together. Defaults to []. |
sort | { field, direction } | No | Defaults to clicks descending. A dimension may be sorted on only when it is one of the dimensions grouped by. Rows with no value for the sort field always come last. |
windowDays | integer | No | Length of the current window, in days. Defaults to 28. |
to | string | No | Last day of the current window (YYYY-MM-DD). Defaults to the most recent date either engine has data for. |
minImpressions | integer | No | Minimum window impressions for a row to be returned. This filter runs in storage, so raising it is the cheapest way to keep a wide query, such as date plus query, under the read's scan ceiling. Defaults to 1. |
limit | integer | No | Maximum rows returned. matchedRows reports how many matched before this cut. Defaults to 100. |
searchVertical | "web" | "image" | "video" | No | Pin one Google search type. Unlike the other tools, this has no default, because searchVertical can also be a grouping. Pin it or split by it. Do not do both. Bing is left out whenever a search type is involved, since Bing splits none. |
Full input JSON SchemaTypes, defaults and validation rules
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "site": { "type": "string", "minLength": 1, "description": "The site to look up, as a bare domain (\"example.com\") or a URL. The tool strips the scheme, www, path, and trailing slash. The site must belong to a workspace you own. Call list_sites first if you are not sure of the exact domain." }, "dimensions": { "default": [ "query" ], "description": "What to group rows by. An empty list returns one row for the whole window. Order is cosmetic.", "type": "array", "items": { "type": "string", "enum": [ "date", "query", "page", "searchEngine", "searchVertical" ] } }, "filters": { "default": [], "description": "Predicates, ANDed together.", "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "enum": [ "query", "page", "searchEngine", "clicks", "impressions", "ctr", "position" ] }, "operator": { "type": "string", "enum": [ "eq", "contains", "notContains", "startsWith", "endsWith", "gt", "gte", "lt", "lte" ] }, "value": { "type": "string", "minLength": 1, "description": "Text to match, or a number for a metric field." } }, "required": [ "field", "operator", "value" ] } }, "sort": { "description": "Defaults to clicks descending. A dimension may be sorted on only when it is one of the dimensions grouped by. Rows with no value for the sort field always come last.", "type": "object", "properties": { "field": { "type": "string", "enum": [ "clicks", "impressions", "ctr", "position", "date", "query", "page", "searchEngine", "searchVertical" ] }, "direction": { "default": "desc", "type": "string", "enum": [ "asc", "desc" ] } }, "required": [ "field" ] }, "windowDays": { "default": 28, "description": "Length of the current window, in days.", "type": "integer", "exclusiveMinimum": 0, "maximum": 365 }, "to": { "description": "Last day of the current window (YYYY-MM-DD). Defaults to the most recent date either engine has data for.", "type": "string" }, "minImpressions": { "default": 1, "description": "Minimum window impressions for a row to be returned. This filter runs in storage, so raising it is the cheapest way to keep a wide query, such as date plus query, under the read's scan ceiling.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "limit": { "default": 100, "description": "Maximum rows returned. `matchedRows` reports how many matched before this cut.", "type": "integer", "exclusiveMinimum": 0, "maximum": 500 }, "searchVertical": { "description": "Pin one Google search type. Unlike the other tools, this has no default, because searchVertical can also be a grouping. Pin it or split by it. Do not do both. Bing is left out whenever a search type is involved, since Bing splits none.", "type": "string", "enum": [ "web", "image", "video" ] } }, "required": [ "site" ]}Response
Full output JSON SchemaEvery field the response can contain
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "site": { "type": "string" }, "workspaceId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "searchVertical": { "anyOf": [ { "type": "string", "enum": [ "web", "image", "video" ] }, { "type": "null" } ] }, "currentWindow": { "type": "object", "properties": { "start": { "type": "string" }, "end": { "type": "string" } }, "required": [ "start", "end" ], "additionalProperties": false }, "dimensions": { "type": "array", "items": { "type": "string", "enum": [ "date", "query", "page", "searchEngine", "searchVertical" ] } }, "filters": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "operator": { "type": "string" }, "value": { "type": "string" } }, "required": [ "field", "operator", "value" ], "additionalProperties": {} } }, "sort": { "type": "object", "properties": { "field": { "type": "string" }, "direction": { "type": "string" } }, "required": [ "field", "direction" ], "additionalProperties": {} }, "limit": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "grain": { "type": "string", "enum": [ "site", "query", "page", "query_page" ] }, "sources": { "type": "array", "items": { "type": "object", "properties": { "searchEngine": { "type": "string", "enum": [ "google", "bing" ] }, "read": { "type": "boolean" }, "datasets": { "type": "array", "items": { "type": "string" } }, "rowCapped": { "type": "boolean" }, "note": { "type": "string" } }, "required": [ "searchEngine", "read", "datasets", "rowCapped", "note" ], "additionalProperties": {} } }, "rows": { "type": "array", "items": { "type": "object", "properties": { "date": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "query": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "page": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "searchEngine": { "anyOf": [ { "type": "string", "enum": [ "google", "bing" ] }, { "type": "null" } ] }, "searchVertical": { "anyOf": [ { "type": "string", "enum": [ "web", "image", "video" ] }, { "type": "null" } ] }, "clicks": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "impressions": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "ctr": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "position": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "positionCoverageImpressions": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "searchEngine", "searchVertical", "clicks", "impressions", "ctr", "position", "positionCoverageImpressions" ], "additionalProperties": {} } }, "matchedRows": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "truncated": { "type": "boolean" }, "unsupportedInputs": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "engine": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "reason": { "type": "string" } }, "required": [ "field", "reason" ], "additionalProperties": {} } }, "lastSyncedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "site", "workspaceId", "searchVertical", "currentWindow", "dimensions", "filters", "sort", "limit", "grain", "sources", "rows", "matchedRows", "truncated", "unsupportedInputs" ], "additionalProperties": false}