Ranking Changes

Report the winners and losers between two periods on one property and explain the biggest moves. Unlike the weekly-report skill, which is a fixed digest over the last settled week, this skill lets the user choose both windows, including year over year. The user's request may contain a property, the two periods in any phrasing ("September vs August", "last 14 days vs the 14 before", "Q3 2026 vs Q3 2025"), a dimension to lead with (queries or pages), a search type, and a focus hint such as a country or a section; honor each.

Workflow

1. Resolve the property. If the user's request or the conversation names a property, use it. Site URLs use GSC formats: sc-domain:example.com or https://www.example.com/. Otherwise call list_sites and pick the obvious match. If several plausible properties exist, ask the user which one before continuing.

2. Fix the two windows. The default is the last 28 settled days compared with the previous 28, which is what the tools use when all four date fields are omitted. Otherwise:

   • Translate the user's phrasing into startDate/endDate (the current window) and comparisonStartDate/comparisonEndDate (the baseline) as YYYY-MM-DD, and keep both windows the same length.
   • Keep the newest 2 days out of the current window: GSC data lags about 2 to 3 days, so never treat the most recent 2 days as complete, and if a dip appears at the very edge of the range, say it is likely reporting lag, not a real drop.
   • For year over year, use the same calendar dates one year earlier; on a site with a weekly rhythm shift by 364 days rather than 365 so the weekdays line up.
   • State both windows on the first line of the output. If get_position_distribution answers the baseline window with emptyBecause, or get_ranking_changes files nearly every key as new with an empty lost bucket (its own emptyBecause appears only when both periods are empty), the stored history does not reach that far; say so instead of guessing.

3. Query movers. Call get_ranking_changes with dimension: "query", the four dates from step 2, and limit: 50 (per bucket, 1 to 10000; raise it to 200 on a large property). Pass searchType only when the user asked for image, video or news; the default is web.

   • Read counts for the full size of each bucket, then the buckets new, lost, improved and declined.
   • Each row carries key, clicks, impressions, ctr, position, prevClicks, prevImpressions, prevPosition and positionDelta (prevPosition minus position: positive is an improvement, negative a decline; a new or lost key's missing side reads 0).
   • improved and declined arrive sorted by the size of the position move, new by clicks and lost by prevClicks; re-rank improved and declined by click impact (clicks for improved, prevClicks for declined) before choosing the rows to show.
   • Note dataSource: on the live API a key just below the scan cut can show as new or lost, so treat small new and lost rows there with care.