Skip to main content

gsc-pulse

An honest report from your Google Search Console exports.
What grew, what dropped and why, and the five things to do next.
Every number computed from your data. Every recommendation shows its formula.

CI PyPI Python versions MIT license

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

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.

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

How it works

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

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, the tour by 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.

A bot-click burst attributed to one country and one device

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. 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.

What moved: tabs per dimension, gainers and losers side by side, bot-driven movers labelled

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

Five actions, each with its estimate and formula

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

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:

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

[ctr_gaps]
min_impressions = 200

Every threshold is in 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.

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

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.

Metadata

Release files for gsc-pulse 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for gsc-pulse 0.1.0
File Size Uploaded Provenance Actions
gsc_pulse-0.1.0.tar.gz 90.1 kB With provenance Details for gsc_pulse-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for gsc-pulse 0.1.0
File Interpreter ABI Platform Actions
gsc_pulse-0.1.0-py3-none-any.whl Python 3 none any Details for gsc_pulse-0.1.0-py3-none-any.whl

Total release size: 176.4 kB

Release files / gsc_pulse-0.1.0.tar.gz

Download URL gsc_pulse-0.1.0.tar.gz
Size 90.1 kB
Tags Source
SHA-256 checksum
How to use checksums
00a96f0e8d91e94ab105e2e183f7ba41e406bba33ad8c6ef1c9920a8b9809f19
BLAKE2b-256 checksum
How to use checksums
0c6c759525ae8569fb796c0c0861914876a82baca8eb8934048b8c7873f57fae
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

Release files / gsc_pulse-0.1.0-py3-none-any.whl

Download URL gsc_pulse-0.1.0-py3-none-any.whl
Size 86.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
5fa296bbfaaff09f47fe71fa4e05e2ab985643e2b8774bc10bdc505ae9cf30ee
BLAKE2b-256 checksum
How to use checksums
2efbf2c10b96d53749fc7c8d45c92dcf3c85a79a54d6a53974746de3f8564f07
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

Security for gsc-pulse 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for gsc_pulse-0.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page