Metadata-Version: 2.5
Name: gsc-pulse
Version: 0.1.0
Summary: An honest, readable HTML report from Google Search Console exports: what grew, what dropped and why, and the five things to do next.
Project-URL: Homepage, https://github.com/Amirjaz/gsc-pulse
Project-URL: Issues, https://github.com/Amirjaz/gsc-pulse/issues
Project-URL: Changelog, https://github.com/Amirjaz/gsc-pulse/blob/main/CHANGELOG.md
Author: Amir Mohammad Jazayeri
License-Expression: MIT
License-File: LICENSE
Keywords: analytics,google-search-console,gsc,report,search-console,seo
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Internet :: WWW/HTTP :: Site Management
Requires-Python: >=3.10
Requires-Dist: jinja2>=3.1
Requires-Dist: numpy>=1.24
Requires-Dist: pandas>=2.0
Requires-Dist: tomli>=2.0; python_version < '3.11'
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Description-Content-Type: text/markdown

<h1 align="center">gsc-pulse</h1>

<p align="center">
  <strong>An honest report from your Google Search Console exports.</strong><br>
  What grew, what dropped and why, and the five things to do next.<br>
  Every number computed from your data. Every recommendation shows its formula.
</p>

<p align="center">
  <a href="https://github.com/Amirjaz/gsc-pulse/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/Amirjaz/gsc-pulse/actions/workflows/ci.yml/badge.svg"></a>
  <a href="https://pypi.org/project/gsc-pulse/"><img alt="PyPI" src="https://img.shields.io/pypi/v/gsc-pulse"></a>
  <a href="https://pypi.org/project/gsc-pulse/"><img alt="Python versions" src="https://img.shields.io/pypi/pyversions/gsc-pulse"></a>
  <a href="https://github.com/Amirjaz/gsc-pulse/blob/main/LICENSE"><img alt="MIT license" src="https://img.shields.io/github/license/Amirjaz/gsc-pulse"></a>
</p>

<p align="center">
  <img src="https://raw.githubusercontent.com/Amirjaz/gsc-pulse/main/docs/img/tour.gif" alt="A tour of a gsc-pulse report: the verdict with bot clicks set apart, the daily chart with a hover tooltip, the five actions, tabbed movers, the bot-burst breakdown and dark mode" width="860">
</p>

```bash
pipx install gsc-pulse          # or: pip install gsc-pulse
gsc-pulse demo -o demo.html     # a fictional site, to see a report right away
gsc-pulse report ./exports/     # your own Search Console exports
```

## Why

Search Console's charts are built to look at, not to decide from. A monthly
total can call a four-day bot burst "growth". A core update can drop a site's
clicks for months before anyone lines the date up with Google's rollout
calendar. And the queries that are one title rewrite away from more clicks are
buried in a 1,000-row table.

gsc-pulse reads the exports you already download, runs four detectors over
them, and writes one HTML file that answers three questions: what changed,
why, and what is worth doing next.

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Amirjaz/gsc-pulse/main/docs/img/monthly-hides-it-dark.svg">
  <img src="https://raw.githubusercontent.com/Amirjaz/gsc-pulse/main/docs/img/monthly-hides-it-light.svg" alt="On the demo site, a monthly view shows October up 28 percent; the daily view shows a 4-day bot burst of 1,584 clicks, and without it October is 0.5 percent below September" width="860">
</picture>

## How it works

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Amirjaz/gsc-pulse/main/docs/img/pipeline-dark.svg">
  <img src="https://raw.githubusercontent.com/Amirjaz/gsc-pulse/main/docs/img/pipeline-light.svg" alt="Exports in (performance, compare, renamed tables, flat tables), four detectors (bot-click bursts, update drops, CTR gaps, striking distance and cannibalisation), one HTML report out" width="860">
</picture>

Nothing is estimated by hand and nothing is borrowed from industry averages:
even the expected CTR at each position is fitted from your own site's queries.
When a question needs data your exports don't have, the report names the exact
export to make instead of guessing.

*Every image on this page comes from the built-in demo, a fictional site
(`acme-dental.example`) with synthetic data. The figures are rebuilt from it by
[`scripts/readme_visuals.py`](scripts/readme_visuals.py), the tour by
[`scripts/tour.py`](scripts/tour.py).*

## What it finds

**Bot-click bursts.** Days where clicks and CTR both jump to at least 2x their
trailing 28-day median (robust z >= 4). A burst has to come back down within a
week; traffic that stays up, like a recovery after an outage, is a real shift,
not bots. If 60% or more of the excess clicks come from one country or one
device, it is flagged as likely bots. Burst clicks are kept out of the headline
growth number and the trend line.

<img src="https://raw.githubusercontent.com/Amirjaz/gsc-pulse/main/docs/screenshots/bot-burst.png" alt="A bot-click burst attributed to one country and one device" width="860">

**Update drops and rises.** Change points in daily clicks (PELT on log clicks,
day-of-week effect removed), matched to the dated list of Google ranking
updates from the [Google Search Status Dashboard](https://status.search.google.com/products/rGHU1u87FJnkP6W2GwMi/history).
A shift counts at 20% or more. Drops with no update nearby are still listed,
with a hint to check technical causes.

**CTR gaps.** Queries at positions 1 to 10 whose CTR is at or below half of
what this site's queries usually get at that position: title and description
rewrite candidates, ranked by missed clicks per month.

**Striking distance and cannibalisation.** Queries at positions 8 to 20 with
real impressions, and queries whose impressions are split across several of
the site's pages.

**What moved, and why.** Per query, page, country and device. Each click change
is split exactly into an impression effect and a CTR effect, then labelled as
a ranking move, a demand change or a CTR change at a steady position. Movers
caused by a bot burst are labelled as such instead of being celebrated.

<img src="https://raw.githubusercontent.com/Amirjaz/gsc-pulse/main/docs/screenshots/movement.png" alt="What moved: tabs per dimension, gainers and losers side by side, bot-driven movers labelled" width="860">

**Five things to do next**, ranked by estimated clicks per month, each with the
formula that produced the estimate:

<img src="https://raw.githubusercontent.com/Amirjaz/gsc-pulse/main/docs/screenshots/actions.png" alt="Five actions, each with its estimate and formula" width="860">

The report itself is one self-contained HTML file: a section nav, KPI cards
that lay this period over the last, a daily chart you can read day by day with
the mouse or the arrow keys, sortable tables, light and dark themes, and a
clean A4 printout. It works offline and with JavaScript turned off.

## What to export from Search Console

Point gsc-pulse at a folder. It reads any number of export zips, extracted
export folders, flat tables and renamed CSV or TSV files, and recognises each
table by its columns.

| Export | How | Unlocks |
|---|---|---|
| **Long history** (required) | Performance > Date: *Last 16 months* > Export > Download CSV | Daily trend, bot bursts, update drops |
| **Compare** (recommended) | Performance > Date > Compare: *Last 28 days vs previous period* > Export | What moved, CTR gaps, striking distance |
| **Monthly exports** (optional) | One export per month, side by side | Month-against-month comparison, matched exactly |
| **Drill-downs** (optional) | The report names the exact custom compare to export, for example the days of a burst vs the days before | Bot-burst attribution, pages behind an update drop |
| **Flat table** (optional) | Looker Studio, Search Analytics for Sheets or BigQuery bulk export, with query and page columns (and a date column) | Cannibalisation, plus everything above for its date range |
| **Renamed tables and script pulls** | CSV or TSV files named like `queries-28d-20261013-20261109.tsv`; `#` comment lines on top are skipped | Kind and date range read from the name when there is no `Filters.csv` |

Search Console's UI export never crosses two dimensions (no query x page, no
date x country), which is why the optional pieces exist.

## Usage

```bash
gsc-pulse report ./exports/                    # writes ./exports/gsc-pulse-report.html
gsc-pulse report ./exports/ -o june.html --period month
gsc-pulse demo -o demo.html                    # synthetic data, fictional site
gsc-pulse synth ./demo-exports/                # just the synthetic exports
```

`--period` is `28d`, `3m` or `month`. Without it, gsc-pulse uses the most
recent month-length comparison the folder can answer exactly (a compare-mode
export, or two back-to-back exports), else the last 28 days against the 28
before. Periods of different length are compared per day.

### Settings

Put a `gsc-pulse.toml` next to your exports (or pass `--config`). The most
useful setting is the brand list, so branded queries don't distort the CTR
curve:

```toml
site_name = "example.com"
brand_terms = ["example", "اگزمپل"]

[ctr_gaps]
min_impressions = 200
```

Every threshold is in [`examples/gsc-pulse.example.toml`](examples/gsc-pulse.example.toml),
and the report's last section prints the values it used. The reasoning behind
each default is in [`docs/decisions.md`](docs/decisions.md).

## Honest limits

- Google publishes no spec for the UI export files. The parser is built from
  real exports and tolerates variations (localised digits, `Dates.csv` or
  `Chart.csv`, compare-mode headers, custom date labels). If yours doesn't
  parse, please open an issue with the header row only, not your data.
- The UI export keeps 1,000 rows per table and Google hides anonymised
  queries; the report shows how much of the site's clicks the query table
  covers.
- The expected-CTR curve is your own site's median, so a CTR gap means "low
  for this site", not "low for the web".
- Click estimates are what the formula says, not a promise. They exist to rank
  the work, and each one shows its inputs.

## Privacy

gsc-pulse runs on your machine and makes no network requests. The report has
no external scripts, fonts or images. The demo, the images on this page and
the tests use only the synthetic generator in `gsc_pulse.synth`.

## Roadmap

Not in v0.1: orphan pages (crawl plus sitemap), PDF output, a Persian
right-to-left layout with Jalali dates, the Search Console API instead of
exports, and an optional LLM-written summary (with every number still computed
in code).

## Development

```bash
python -m venv .venv
.venv/Scripts/activate            # Windows; use .venv/bin/activate elsewhere
pip install -e ".[dev]"
pytest
ruff check . && ruff format --check .
```

Python 3.10 to 3.14. Change points use a small numpy PELT implementation
rather than `ruptures`, which doesn't support Python 3.14 yet.

## License

MIT, see [LICENSE](LICENSE).
