# GSC query export JSON schema (tools & arbitrary paths)

**Last Updated:** 2026-04-01

Files produced by `v2/scripts/tools/collect-tool-gsc-queries.php` (and the same shape for manual/UI exports normalized to this structure).

## Root object

| Field | Type | Description |
|-------|------|-------------|
| `exported_at` | string (YYYY-MM-DD) | Commit / generation date (local date when written). |
| `source` | string | Provenance, e.g. API description. |
| `tool` | string | Research folder slug or basename of path. |
| `page_path` | string | Path only, e.g. `/tools/prozentrechner`. |
| `date_range` | object | **`start`** and **`end`** (YYYY-MM-DD), inclusive GSC API range. |
| `gsc_property` | string | e.g. `https://www.ordio.com/` |
| `row_count` | int | `count(queries)`. |
| `queries` | array | Sorted by clicks desc, then impressions desc. |

## Query row

| Field | Type | Description |
|-------|------|-------------|
| `query` | string | Search query text. |
| `clicks` | int | |
| `impressions` | int | |
| `ctr` | float | 0–1 fraction (not percent). |
| `position` | float | Average position for that query × page. |

## Period comparison (two exports)

Use **two files** with non-overlapping or rolling `date_range` values (e.g. last 28 days vs previous 28 days). Do not merge periods in one file unless you keep clear `date_range` per file.

**Diff output** (`v2/scripts/tools/compare-gsc-query-exports.php`): Markdown summarizing deltas per query. Rules:

- Join rows by **`query`** (exact string match).
- **Δ clicks** = `after.clicks − before.clicks`
- **Δ impressions** = `after.impressions − before.impressions`
- **Δ position** = `after.position − before.position` (negative = improved average position)
- **Top-N tables:** default 20 rows each for: largest click **losses**, largest click **gains**, largest impression **losses** (queries only in one period appear with the other side zeroed).

See [PAGE_IMPROVEMENT_ITERATION_CHECKLIST.md](../PAGE_IMPROVEMENT_ITERATION_CHECKLIST.md) § Period comparison.

## Script: compare two exports

```bash
php v2/scripts/tools/compare-gsc-query-exports.php \
  --before=docs/content/tools/{slug}/data/gsc-queries-prev.json \
  --after=docs/content/tools/{slug}/data/gsc-queries.json \
  --output=docs/content/tools/{slug}/data/gsc-queries-diff.md
```

**Fixtures (smoke test, no API):**

```bash
php v2/scripts/tools/compare-gsc-query-exports.php \
  --before=v2/scripts/tools/fixtures/gsc-queries-period-before.json \
  --after=v2/scripts/tools/fixtures/gsc-queries-period-after.json --top=5
```