gsc_compare_periods
Compare current and prior time periods for search performance metrics, identify gainers, losers, and statistical outliers in clicks, impressions, CTR, and position.
Instructions
Compare two equal-length time windows (current vs prior) and return per-key deltas in clicks, impressions, CTR, and position, plus keys present in only one window. v0.2.0: optional sort_by / sort_dir / min_delta_* filters and an anomalies_only z-score gate so the same tool covers 'biggest gainers', 'biggest losers', 'meaningful movers', and 'statistical outliers' without needing separate tools. When anomalies_only=true, the response's filters_applied.sigma_used field reports the population-stdev (sigma) actually computed from the matched rows' sort_by metric distribution; the effective z-score cutoff applied is sigma_threshold * sigma_used.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| top | No | Cap the returned rows. No cap by default. | |
| days | No | Alias for current_days. current_days wins when both are set. | |
| limit | No | Alias for row_limit. row_limit wins when both are set. | |
| sort_by | No | Metric to sort matched rows by. Defaults to delta_clicks. | |
| gap_days | No | Days between the two windows. Defaults to 0. | |
| site_url | No | Defaults to the configured default site. | |
| sort_dir | No | Sort direction. 'desc' for biggest gainers (default). 'asc' for biggest losers. Note: delta_position is reversed (negative = improvement), so use 'asc' to find rank gains. | |
| row_limit | No | Rows per window query. Defaults to 1000. | |
| dimensions | No | Defaults to ["query"]. | |
| current_days | No | Length of each window in days. Defaults to 28. | |
| anomalies_only | No | If true, keep only rows where the sort_by metric exceeds sigma_threshold standard deviations from the matched-rows mean (statistical outliers). Default false. | |
| sigma_threshold | No | Threshold for anomalies_only. Defaults to 2.0 (~95th percentile under normality). | |
| min_delta_clicks | No | Filter to rows with abs(delta_clicks) >= this. Defaults to 0 (no filter). | |
| min_delta_position | No | Filter to rows with abs(delta_position) >= this. Defaults to 0. | |
| min_delta_impressions | No | Filter to rows with abs(delta_impressions) >= this. Defaults to 0. |