# Gsc

> Fetch data from Google Search Console API including search analytics with flexible dimensions (query, page, country, device, date), URL inspection for indexation status, site management, and sitemap data. Use to retrieve GSC data for SEO analysis, keyword research, indexation audits, or performance tracking. Supports time period comparisons, dimension filtering, and all GSC API endpoints.

- Skill: `buzzmatic/gsc` (Agent Skill, multi-file: 15 files)
- Install (CLI): `npx skillmds@latest add buzzmatic/gsc`
- Raw SKILL.md: https://api.skillmd.com/api/skills/buzzmatic/gsc/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Marketing & Growth
- Author: Buzzmatic (https://skillmd.com/u/buzzmatic)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/buzzmatic/gsc

---


# Google Search Console Skill

Fetch and process data from the Google Search Console API.

## Quick Start

All scripts:
- Save raw JSON and processed CSV to `./output/` under the current working directory
- Return JSON with `{"output_files": [...], "summary": "..."}`

## Core Operations

### Search Analytics

Fetch performance data with flexible dimensions:

```bash
python skills/gsc/scripts/fetch_analytics.py \
  --site-url "https://example.com" \
  --start-date "2024-01-01" \
  --end-date "2024-01-31" \
  --dimensions query,page \
  --row-limit 1000
```

**Common dimension combinations:**
- `query` - Top search queries
- `page` - Top landing pages
- `query,page` - Queries per page
- `page,country` - Pages by country
- `query,device` - Queries by device type
- `country,device` - Geographic and device breakdown

**Optional filters:**
```bash
--filter 'page contains /blog/' \
--filter 'query notContains brand' \
--filter 'country equals USA'
```

**Time period comparison:**
```bash
--compare-start "2025-12-01" \
--compare-end "2025-12-31"
```

This adds comparison metrics (change %, growth) to the output.

### URL Inspection

Check indexation status for specific URLs:

```bash
python skills/gsc/scripts/inspect_url.py \
  --site-url "https://example.com" \
  --inspect-url "https://example.com/page-to-check"
```

Returns coverage status, indexability, mobile usability, AMP status, and structured data.

### Site Management

List all verified sites:

```bash
python skills/gsc/scripts/list_sites.py
```

Get site details:

```bash
python skills/gsc/scripts/get_site.py \
  --site-url "https://example.com"
```

### Sitemaps

List sitemaps for a site:

```bash
python skills/gsc/scripts/list_sitemaps.py \
  --site-url "https://example.com"
```

Get sitemap details:

```bash
python skills/gsc/scripts/get_sitemap.py \
  --site-url "https://example.com" \
  --sitemap-url "https://example.com/sitemap.xml"
```

## Advanced Topics

For detailed API parameters, filtering syntax, and dimension combinations, see:
- [API Reference](references/api_reference.md) - Complete GSC API documentation
- [Examples](references/examples.md) - Common query patterns and use cases

## Authentication

Scripts authenticate to Google via the shared `lib/google_auth` helper. Provide
OAuth2 credentials through environment variables (or a `.env` file at the repo root):
- `GOOGLE_CLIENT_ID`
- `GOOGLE_CLIENT_SECRET`
- `GOOGLE_REFRESH_TOKEN`

Alternatively, place a token file under `secrets/` at the repo root
(e.g. `secrets/gsc_token.json` or a unified token). The GSC scopes are
`https://www.googleapis.com/auth/webmasters.readonly` (read) and
`https://www.googleapis.com/auth/webmasters` (write, used by sitemap submit).

## Output Format

All scripts return:

```json
{
  "output_files": [
    "output/gsc_analytics_raw.json",
    "output/gsc_analytics.csv"
  ],
  "summary": "Fetched 1,247 rows: 847 queries across 156 pages"
}
```

CSV includes all requested dimensions plus metrics:
- `clicks` - Number of clicks
- `impressions` - Number of impressions
- `ctr` - Click-through rate
- `position` - Average position

When comparison enabled, adds:
- `clicks_compare` - Clicks in comparison period
- `clicks_change` - Absolute change
- `clicks_change_pct` - Percentage change
- (same for impressions, ctr, position)