Analyze branded vs non-branded search
The tool splits the window's Google and Bing queries into branded and non-branded demand. Each side has clicks, impressions, click-through rate, average position, and its share of that engine's returned rows. A query is branded when it contains the workspace title or one of its confirmed brand aliases, matched as a whole word and ignoring case. This is the same term set the AI-answer mention monitor uses. The terms applied come back in brandTerms, and the biggest branded queries come back in sampleBrandedQueries, so you can check the split. Correct it with set_workspace_brand_terms and run this again. total sums clicks and impressions, and it counts each query once across engines. total.avgPosition is always null. The engines define position differently and report it on different schedules, so read the per-engine figures. The shares are shares of the rows each engine returned. On a window Google cut, brand queries stay inside the top 5,000 because they have high volume, and the non-branded tail is what the cut removes, so the branded share is overstated. The response says whether that applies to this window, in unsupportedInputs. Google keeps about 5,000 rows per day for each single breakdown once a day is more than about three days old. On a large site the tool is reading the top queries or pages by impressions. Google no longer stores the rest. If that applies to this window, the response names the dates in unsupportedInputs. A missing row means it was outside that list. Google no longer has the row, so there is nothing further to fetch.
analyze_branded_vs_nonbrandedThe tool splits the window's Google and Bing queries into branded and non-branded demand.
Each side has clicks, impressions, click-through rate, average position, and its share of that engine's returned rows. A query is branded when it contains the workspace title or one of its confirmed brand aliases, matched as a whole word and ignoring case. This is the same term set the AI-answer mention monitor uses. The terms applied come back in brandTerms, and the biggest branded queries come back in sampleBrandedQueries, so you can check the split. Correct it with set_workspace_brand_terms and run this again.
total sums clicks and impressions, and it counts each query once across engines. total.avgPosition is always null. The engines define position differently and report it on different schedules, so read the per-engine figures.
The shares are shares of the rows each engine returned. On a window Google cut, brand queries stay inside the top 5,000 because they have high volume, and the non-branded tail is what the cut removes, so the branded share is overstated. The response says whether that applies to this window, in unsupportedInputs.
Google keeps about 5,000 rows per day for each single breakdown once a day is more than about three days old. On a large site the tool is reading the top queries or pages by impressions. Google no longer stores the rest.
If that applies to this window, the response names the dates in unsupportedInputs. A missing row means it was outside that list. Google no longer has the row, so there is nothing further to fetch.
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. |
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. |
searchVertical | "web" | "image" | "video" | No | Which Google search type to read: web (the default), image, or video. Bing Webmaster Tools does not split search types on any traffic report, so image and video return Google only. The response records that Bing was left out, in unsupportedInputs. A missing Bing number then means Bing was not measured. Defaults to "web". |
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." }, "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" }, "searchVertical": { "default": "web", "description": "Which Google search type to read: web (the default), image, or video. Bing Webmaster Tools does not split search types on any traffic report, so image and video return Google only. The response records that Bing was left out, in unsupportedInputs. A missing Bing number then means Bing was not measured.", "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": { "type": "string", "enum": [ "web", "image", "video" ] }, "currentWindow": { "type": "object", "properties": { "start": { "type": "string" }, "end": { "type": "string" } }, "required": [ "start", "end" ], "additionalProperties": false }, "brandTerms": { "type": "array", "items": { "type": "string" } }, "google": { "type": "object", "properties": { "attached": { "type": "boolean" }, "branded": { "type": "object", "properties": { "queryCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "clicks": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "impressions": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "ctr": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "avgPosition": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "positionCoverageImpressions": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "clicksShare": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "impressionsShare": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "queryCount", "clicks", "impressions", "ctr", "avgPosition", "positionCoverageImpressions", "clicksShare", "impressionsShare" ], "additionalProperties": {} }, "nonBranded": { "type": "object", "properties": { "queryCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "clicks": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "impressions": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "ctr": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "avgPosition": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "positionCoverageImpressions": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "clicksShare": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "impressionsShare": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "queryCount", "clicks", "impressions", "ctr", "avgPosition", "positionCoverageImpressions", "clicksShare", "impressionsShare" ], "additionalProperties": {} } }, "required": [ "attached", "branded", "nonBranded" ], "additionalProperties": {} }, "bing": { "type": "object", "properties": { "attached": { "type": "boolean" }, "branded": { "type": "object", "properties": { "queryCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "clicks": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "impressions": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "ctr": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "avgPosition": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "positionCoverageImpressions": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "clicksShare": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "impressionsShare": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "queryCount", "clicks", "impressions", "ctr", "avgPosition", "positionCoverageImpressions", "clicksShare", "impressionsShare" ], "additionalProperties": {} }, "nonBranded": { "type": "object", "properties": { "queryCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "clicks": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "impressions": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "ctr": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "avgPosition": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "positionCoverageImpressions": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "clicksShare": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "impressionsShare": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "queryCount", "clicks", "impressions", "ctr", "avgPosition", "positionCoverageImpressions", "clicksShare", "impressionsShare" ], "additionalProperties": {} } }, "required": [ "attached", "branded", "nonBranded" ], "additionalProperties": {} }, "total": { "type": "object", "properties": { "attached": { "type": "boolean" }, "branded": { "type": "object", "properties": { "queryCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "clicks": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "impressions": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "ctr": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "avgPosition": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "positionCoverageImpressions": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "clicksShare": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "impressionsShare": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "queryCount", "clicks", "impressions", "ctr", "avgPosition", "positionCoverageImpressions", "clicksShare", "impressionsShare" ], "additionalProperties": {} }, "nonBranded": { "type": "object", "properties": { "queryCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "clicks": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "impressions": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "ctr": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "avgPosition": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "positionCoverageImpressions": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "clicksShare": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "impressionsShare": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "queryCount", "clicks", "impressions", "ctr", "avgPosition", "positionCoverageImpressions", "clicksShare", "impressionsShare" ], "additionalProperties": {} } }, "required": [ "attached", "branded", "nonBranded" ], "additionalProperties": {} }, "sampleBrandedQueries": { "type": "array", "items": { "type": "string" } }, "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", "brandTerms", "google", "bing", "total", "sampleBrandedQueries", "unsupportedInputs" ], "additionalProperties": false}