Get ranking changes between two periods
get_ranking_changesUse this when the user asks which queries or pages moved up or down between two periods: each is filed as new, lost, improved or declined (improved = better, lower average position). Not for pages losing clicks over time: use find_decaying_content. limit (1-10000, default 50) applies PER BUCKET; counts gives the full size of each bucket before that cut. Buckets run largest first: improved and declined by the size of positionDelta (prevPosition minus position; a new or lost key's missing side reads 0), new by clicks, lost by prevClicks. ctr is a 0-100 percentage. Each period reads its top scanLimit keys by clicks (warehouse: max(limit*10, 1000), capped at 50000; live API: 25000), and counts are measured within them. The warehouse reads every key in either period's top scanLimit in both periods, so new and lost are real; on the live API the reads are independent, so a key just below one cut can show as new or lost. Query movers are only the queries Google lists: on most properties a large share of clicks has no query row (analyze_sampling_impact measures it). Served from the GSC Wizard ClickHouse warehouse when available, otherwise the live Search Console API (see dataSource). Date range is optional: omit startDate/endDate to analyze the last 28 settled days (data lags ~2-3 days).
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"siteUrl": "<siteUrl>"
},
"name": "get_ranking_changes"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| endDate | No | Optional. Window end as YYYY-MM-DD (e.g. 2026-05-31). You do NOT need to know today's date or the latest available date: omit this and the server uses the latest settled Search Console date (data lags ~2-3 days behind today). Never pass null or the string "null". | |
| siteUrl | Yes | ||
| dimension | No | query | |
| startDate | No | Optional. Window start as YYYY-MM-DD (e.g. 2026-05-03). You do NOT need to know today's date. Omit BOTH startDate and endDate to analyze the last 28 settled days automatically (Search Console data lags ~2-3 days). Never pass null or the string "null". | |
| searchType | No | Search type: web (default), image, video, news (the News tab), discover, googleNews (news.google.com), webMultimodal (Google Lens, Circle to Search and image uploads; data from 2026-02-20; not part of all), or all (web + image + video + news + discover combined, position impression-weighted, like the app's "All" filter). Discover, googleNews and webMultimodal carry no query dimension, so query-level results for them are empty; Discover and googleNews also carry no position: it reads null, not 0. | web |
| comparisonEndDate | No | Optional. End of the baseline / comparison period as YYYY-MM-DD. Omit both comparison dates to use the same-length period immediately before the current window; give only this one to end a baseline of the same length here. | |
| comparisonStartDate | No | Optional. Start of the baseline / comparison period as YYYY-MM-DD. Omit both comparison dates to use the same-length period immediately before the current window; give only this one to start a baseline of the same length here. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| new | No | ||
| hint | No | ||
| kind | No | Widget variant: "kpis", "table", or "sections". | |
| kpis | No | KPI cards (kind="kpis"). | |
| lost | No | ||
| note | No | Caveat about the result, when the tool returned one. | |
| rows | No | Data rows (kind="table"), each with every field of the tool's own row; columns name the ones drawn. | |
| notes | No | Caveats about the result, when the tool returned several. | |
| range | No | The window the numbers cover. | |
| scope | No | The brand, content group or topic cluster filter these numbers are narrowed to; absent when the call was unscoped and the numbers cover the whole property. | |
| title | No | ||
| blocks | No | Stacked sub-blocks (kind="sections"). | |
| counts | No | get_ranking_changes: the full size of each bucket before `limit`. | |
| deltas | No | get_site_summary: current minus previous (ctrPoints in percentage points). | |
| reason | No | ||
| source | No | ||
| thenBy | No | Secondary sort field, when the tool states one. | |
| account | No | ||
| columns | No | Column defs (kind="table"). | |
| current | No | get_site_summary: the window's totals (ctr 0-100, impression-weighted avgPosition). | |
| summary | No | Metric totals keyed by GA4 metric name. | |
| warning | No | A caveat that changes how the numbers read. | |
| coverage | No | How much of the property total the returned rows cover, with the property totals inline. Quote totals from here; do not sum the rows. | |
| declined | No | ||
| improved | No | ||
| nextStep | No | ||
| ordering | No | Sort order per list, when the result holds several lists. | |
| previous | No | get_site_summary: the comparison window's totals. | |
| sortedBy | No | Row field the rows are sorted by. | |
| timeZone | No | GA4 property's IANA reporting time zone. | |
| dailyRows | No | get_site_summary: the window day by day, oldest first. | |
| dimension | No | ||
| emptyText | No | ||
| scanLimit | No | ||
| siteScope | No | Set when GA4 numbers were narrowed to this site's hostnames because the property is shared with other sites. | |
| sortOrder | No | "asc" or "desc". | |
| thenOrder | No | The tie-break's direction, present only when it differs from sortOrder. | |
| totalRows | No | ||
| assistants | No | get_ga4_llm_traffic: one row per AI assistant (the table rows). | |
| comparison | No | The comparison window (get_site_summary, get_ranking_changes). | |
| dataSource | No | Where the numbers were read from: the warehouse or the live API. | |
| hasRevenue | No | ||
| pagination | No | Where this page of rows sits in the whole result, and how to fetch the next one. | |
| timeseries | No | get_ga4_overview with includeTimeseries: daily points, oldest first. | |
| partialDays | No | Requested days after settledThrough; their numbers are still incomplete. | |
| prevSummary | No | The comparison period's totals; null when it has no GA4 data. | |
| currencyCode | No | ||
| dataMaturity | No | ||
| emptyBecause | No | ||
| ga4OnlyCount | No | ||
| gscOnlyCount | No | ||
| hasEcommerce | No | ||
| landingPages | No | get_ga4_llm_traffic: landing pages of AI assistant sessions. | |
| matchedCount | No | ||
| methodLimits | No | ||
| hasComparison | No | ||
| notConfigured | No | ||
| totalSessions | No | ||
| prevTimeseries | No | The comparison period's daily points; null when it has no GA4 data. | |
| reauthRequired | No | ||
| settledThrough | No | Last day the data is complete through. | |
| comparisonRange | No | The comparison window of a GA4 view tool; null when there is none. | |
| ecommerceSummary | No | ||
| sourceTimeseries | No | get_ga4_llm_traffic with includeDailySplit: daily sessions per assistant. | |
| comparisonHasData | No | false when the comparison period has no data at all, so there is no comparison. | |
| matchedClickShare | No | A 0-1 fraction of the named-query clicks the estimates cover. | |
| prevTotalSessions | No | ||
| previousDailyRows | No | get_site_summary: the comparison window day by day, oldest first; absent for a window over 180 days. | |
| llmShareOfSessions | No | A 0-1 fraction. | |
| coverageUnavailable | No | Why coverage is null, when it is. | |
| warehouseLatestDate | No | Newest day the warehouse holds for the property; days after it in the range are missing, not zero. | |
| prevEcommerceSummary | No | ||
| prevLlmShareOfSessions | No |