Score SEO opportunities
The tool ranks work from four other tools into one queue. The four are find_low_hanging_keywords, find_ctr_opportunities, find_content_decay, and find_content_gaps. Use this when the question is what to work on. Call one of those tools when you already know which kind of problem you are chasing, because each has thresholds this tool leaves at its defaults. Every row is priced in one unit. estimatedClicks is the clicks per windowDays at stake if the finding were fixed. When one query or page has more than one signal, the price is the largest signal. Do not add the signals together. A query that is both close to page one and under-clicking is one recovery. basis says what that number assumes, and estimateBases spells each assumption out. A decay row is clicks that were measured and then lost. The other three are projections onto the site's own click-rate curve. If estimatedClicks is null, the site's data could not price that row. Those rows sort last. The queue mixes queries and pages. entityType says which. The same string as a query and as a page is two rows. sources says which types were evaluated, which you left out, and how many candidates each produced. Say that in the answer. If the response says Google cut the window, this queue is the top of what was visible. It is not the top of the whole site. 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.
score_seo_opportunitiesThe tool ranks work from four other tools into one queue.
The four are find_low_hanging_keywords, find_ctr_opportunities, find_content_decay, and find_content_gaps. Use this when the question is what to work on. Call one of those tools when you already know which kind of problem you are chasing, because each has thresholds this tool leaves at its defaults.
Every row is priced in one unit. estimatedClicks is the clicks per windowDays at stake if the finding were fixed. When one query or page has more than one signal, the price is the largest signal. Do not add the signals together. A query that is both close to page one and under-clicking is one recovery.
basis says what that number assumes, and estimateBases spells each assumption out. A decay row is clicks that were measured and then lost. The other three are projections onto the site's own click-rate curve. If estimatedClicks is null, the site's data could not price that row. Those rows sort last.
The queue mixes queries and pages. entityType says which. The same string as a query and as a page is two rows. sources says which types were evaluated, which you left out, and how many candidates each produced. Say that in the answer. If the response says Google cut the window, this queue is the top of what was visible. It is not the top of the whole site.
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. |
types | string | No | Comma-separated opportunity types to evaluate: low_hanging, ctr, decay, gap. Narrow the list to keep the call cheaper. low_hanging, ctr, and gap share one stored scan, and decay costs a second. Defaults to "low_hanging,ctr,decay,gap". |
minImpressions | integer | No | Shared floor: entities below this many impressions over the window are not opportunities on any source. Defaults to 10. |
excludeBranded | boolean | No | Leave branded queries out. This is on by default. A brand query cannot be moved up on the brand's own results, and its high click rate raises the target every projection here is measured against. Defaults to true. |
decayBy | "query" | "page" | No | Dimension the decay source reads. Pages by default, matching find_content_decay: a decaying page is the thing you act on. Defaults to "page". |
decayGranularity | "weekly" | "monthly" | No | Period length for the decay source only. Defaults to "monthly". |
decayPeriods | integer | No | How many whole periods the decay source reads. Defaults to 6. |
checkCannibalization | boolean | No | Check whether several of the site's own pages already split a gap query. If they do, the row recommends a merge. This costs one extra stored read, and it is skipped when no gap row was found. Defaults to true. |
limit | integer | No | How many opportunities to return, highest first. Defaults to 25. |
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" }, "types": { "default": "low_hanging,ctr,decay,gap", "description": "Comma-separated opportunity types to evaluate: low_hanging, ctr, decay, gap. Narrow the list to keep the call cheaper. low_hanging, ctr, and gap share one stored scan, and decay costs a second.", "type": "string" }, "minImpressions": { "default": 10, "description": "Shared floor: entities below this many impressions over the window are not opportunities on any source.", "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "excludeBranded": { "default": true, "description": "Leave branded queries out. This is on by default. A brand query cannot be moved up on the brand's own results, and its high click rate raises the target every projection here is measured against.", "type": "boolean" }, "decayBy": { "default": "page", "description": "Dimension the decay source reads. Pages by default, matching find_content_decay: a decaying page is the thing you act on.", "type": "string", "enum": [ "query", "page" ] }, "decayGranularity": { "default": "monthly", "description": "Period length for the decay source only.", "type": "string", "enum": [ "weekly", "monthly" ] }, "decayPeriods": { "default": 6, "description": "How many whole periods the decay source reads.", "type": "integer", "minimum": 2, "maximum": 104 }, "checkCannibalization": { "default": true, "description": "Check whether several of the site's own pages already split a gap query. If they do, the row recommends a merge. This costs one extra stored read, and it is skipped when no gap row was found.", "type": "boolean" }, "limit": { "default": 25, "description": "How many opportunities to return, highest first.", "type": "integer", "exclusiveMinimum": 0, "maximum": 200 }, "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 }, "periodWindow": { "anyOf": [ { "type": "object", "properties": { "granularity": { "type": "string" }, "periods": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "window": { "type": "object", "properties": { "start": { "type": "string" }, "end": { "type": "string" } }, "required": [ "start", "end" ], "additionalProperties": false }, "periodStarts": { "type": "array", "items": { "type": "string" } }, "excludedPartialPeriod": { "anyOf": [ { "type": "object", "properties": { "start": { "type": "string" }, "end": { "type": "string" } }, "required": [ "start", "end" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "granularity", "periods", "window", "periodStarts", "excludedPartialPeriod" ], "additionalProperties": {} }, { "type": "null" } ] }, "rows": { "type": "array", "items": { "type": "object", "properties": { "entityType": { "type": "string" }, "label": { "type": "string" }, "estimatedClicks": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "leadingKind": { "type": "string" }, "confidence": { "type": "string" }, "recommendation": { "type": "string" }, "kinds": { "type": "array", "items": { "type": "string" } }, "signals": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "engine": { "type": "string" }, "estimatedClicks": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "basis": { "type": "string" }, "confidence": { "type": "string" }, "detail": { "type": "string" }, "position": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "impressions": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "clicks": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "kind", "engine", "estimatedClicks", "basis", "confidence", "detail", "position", "impressions", "clicks" ], "additionalProperties": {} } }, "totalImpressions": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "totalClicks": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "entityType", "label", "estimatedClicks", "leadingKind", "confidence", "recommendation", "kinds", "signals", "totalImpressions", "totalClicks" ], "additionalProperties": {} } }, "sources": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "entityType": { "type": "string" }, "status": { "type": "string" }, "candidates": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "pricedCandidates": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "kind", "entityType", "status", "candidates", "pricedCandidates" ], "additionalProperties": {} } }, "estimateBases": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "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", "periodWindow", "rows", "sources", "estimateBases", "unsupportedInputs" ], "additionalProperties": false}