Compare Search Analytics

Compare Google Search Console traffic between two date ranges for one property and return the deltas. Fetches both periods in parallel, joins the rows on their dimension keys, and reports per-row and total clicks, impressions, ctr and position change — the period-over-period arithmetic is done for you.

Use for any question that compares two date ranges: month over month, quarter over quarter, year over year, "which queries gained or lost the most clicks", "did mobile grow", "did that update hurt us". Use Query Search Analytics for a single date range, for paging past 5000 rows, and for the hour and searchAppearance dimensions this tool does not accept. Property-level vs page-level position questions also need two Query Search Analytics calls with different aggregationType values.

Returns { current_period, previous_period, totals, rows, row_count, has_more, truncated, note }. totals carries current, previous, delta and pct_change for the whole period, computed from every fetched row rather than just the returned ones. Each row is { keys, current, previous, delta, pct_change }.

Reading the deltas. A key present in only one period gets zeros for the other, so new and lost queries both show up — but its delta.ctr and delta.position are null, because the missing period has no CTR or position to compare against (delta.clicks and delta.impressions are still real numbers). pct_change is null where the previous period was zero — not 0 and not infinity. ctr is a 0-1 fraction (0.1428 means 14.3%) and position is 1-indexed where lower is better, so a NEGATIVE position delta is an improvement; both are impression-weighted, so never re-average them across rows. Query rows always understate the real total because Google omits anonymized (rare) queries — compare with no dimensions, or by date, for true totals. truncated is true when either period hit the internal 5000-row cap, so rows and totals may be incomplete: narrow the range or add a filter. has_more is a different signal — it only means the join produced more rows than rowLimit. note warns about anonymized queries when relevant, otherwise it is null.

Mistakes. "The previous period" means the same number of days immediately before the current period: for 2026-08-01..2026-08-28 (28 days) that is 2026-07-04..2026-07-31. "The same period last year" means both dates shifted back one year. Grouping Discover by query returns a 400 — Discover has no query dimension. Comparing a range that ends today makes the current period look artificially low, because data is final only after about 2-3 days unless dataState is all. filterValue (with filterDimension/filterOperator) is applied identically to both periods and wins over advancedDimensionFilters; the equivalent prop on Query Search Analytics is named subdomainFilter for backwards compatibility.

Example. siteUrl="sc-domain:example.com", currentStartDate="2026-08-01", currentEndDate="2026-08-28", previousStartDate="2026-07-04", previousEndDate="2026-07-31", dimensions=["query"], sortBy="clicks_delta" returns totals: { current: { clicks: 74, ... }, previous: { clicks: 68, ... }, delta: { clicks: 6, ... }, pct_change: { clicks: 0.0882, ... } } and rows such as { keys: ["example brand"], current: { clicks: 41, ... }, previous: { clicks: 33, ... }, delta: { clicks: 8, ... } }.

See the documentation