searchdiff 0.1.0__tar.gz

searchdiff-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tsuruta Lab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

searchdiff-0.1.0/PKG-INFO

@@ -0,0 +1,142 @@
+Metadata-Version: 2.4
+Name: searchdiff
+Version: 0.1.0
+Summary: Did the change work? Weekly blocks, cliffs, and difference-in-differences for Google Search Console data, from a CSV or the API.
+Author: Tsuruta Lab
+License: MIT
+Project-URL: Homepage, https://github.com/tsurutanmen/searchdiff
+Project-URL: Issues, https://github.com/tsurutanmen/searchdiff/issues
+Keywords: search console,seo,difference in differences,ctr,analytics
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Internet :: WWW/HTTP :: Site Management
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: api
+Requires-Dist: google-auth>=2.0; extra == "api"
+Requires-Dist: requests>=2.25; extra == "api"
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Dynamic: license-file
+
+# searchdiff
+
+Did the change work?
+
+Search Console answers two questions badly on its own. "When did traffic drop, and how far back is
+it?" gets a daily chart with the weekday wobble in it. "We rewrote the titles, did it help?" gets a
+before/after on the changed pages, which contains the season, the algorithm update, and the change,
+all mixed together. `searchdiff` gives the first question weekly blocks from a fixed anchor, and the
+second a control group and a difference in differences.
+
+```
+pip install git+https://github.com/tsurutanmen/searchdiff                 # CSV only, no dependencies
+pip install "git+https://github.com/tsurutanmen/searchdiff#egg=searchdiff[api]"   # plus the API
+```
+
+## Weekly blocks
+
+```
+$ searchdiff weeks daily.csv --anchor 2026-07-18
+
+week                    days  clicks   /day     impr    ctr   pos  vs prev  of peak
+2026-07-18..07-24     7    1486  212.3    28420   5.2%   6.6      +2%      95%
+2026-07-25..07-31     7    1487  212.4    28605   5.2%   7.0      +0%      95%
+2026-08-01..08-07     7    1562  223.1    28365   5.5%   6.1      +5%     100%  peak
+2026-08-08..08-14     7    1000  142.9    17816   5.6%   6.1     -36%      64%  CLIFF
+2026-08-15..08-21     7    1031  147.3    18516   5.6%   5.9      +3%      66%
+2026-08-22..08-28     7    1197  171.0    20313   5.9%   6.2     +16%      77%
+2026-08-29..08-31     3     483  161.0     8482   5.7%   7.6      -6%      72%
+last block is partial; its /day figure is comparable, its totals are not
+note: cliff in the block starting 2026-08-08 (-36%); latest block is at 72% of peak
+```
+
+`daily.csv` here is the `Dates` export from the Performance report, unchanged. Any CSV with
+`date,clicks,impressions[,position]` works, with or without a `page` column. Blocks are counted
+from the anchor in both directions, so the same anchor gives the same blocks next month.
+
+## Did the change work
+
+```
+$ searchdiff effect pages.csv --change 2026-08-04 --treated "re:/p/0[0-4]$" --window 28
+
+change on 2026-08-04, 28 days before and after
+
+            pages            clicks/day              impr/day                 ctr        position
+treated         5     30.25 ->     21.50     564.4 ->     409.5    5.36% ->    5.25%    7.2 ->    8.0
+control        35    182.57 ->    143.82    3487.6 ->    2512.7    5.23% ->    5.72%    7.7 ->    7.4
+
+difference in differences (treated change minus control change):
+  ctr           -0.60 points   (treated -0.11, control +0.49)
+  clicks/day     -7.7 %        (treated -28.9%, control -21.2%)
+  impr/day       +0.5 %        (treated -27.4%, control -28.0%)
+  position      +0.95 ranks    (treated +0.72, control -0.23; negative is better)
+```
+
+The treated pages lost 29% of their clicks after the change. So did everything else: a traffic cliff
+hit the whole site four days later. The difference in differences is within a CTR point of zero. The
+rewrite did nothing, and a before/after on the five pages alone would have called it a disaster.
+
+The same data with pages that really did get a lift:
+
+```
+  ctr           +3.41 points   (treated +3.33, control -0.09)
+  clicks/day    +49.0 %        (treated +20.4%, control -28.6%)
+```
+
+`pages.csv` needs `date,page,clicks,impressions[,position]` rows, which the API gives and the UI does
+not. `--treated` and `--control` take a substring, a glob, `re:` a regex, or `@file` with one URL per
+line. The control defaults to every page not treated; a control of the same kind as the treated pages
+is better. `--gap N` skips the first N days after the change for edits that take time to be re-indexed.
+
+The report adds notes when the window runs past the data, when the treated group has too few clicks
+for anything to be distinguishable from noise, and when treated and control moved together.
+
+## Fetching from the API
+
+```
+searchdiff fetch --site https://example.com/ --key service-account.json \
+    --start 2026-06-01 --end 2026-08-31 --out pages.csv --coverage
+```
+
+The service account's e-mail has to be added as a user of the property. `--coverage` prints how much
+of the clicks the query dimension shows. Search Console hides rare queries; on a site of ours the
+query-level sum was 39% of the total while the page-level sum matched it. Analyse by page unless the
+words are the point. Paging past 25,000 rows is handled.
+
+## Python
+
+```python
+import datetime as dt, searchdiff as sd
+
+rows = sd.load_csv("pages.csv")
+print(sd.weekly(rows, anchor=dt.date(2026, 7, 18)))
+rep = sd.effect(rows, dt.date(2026, 8, 4), sd.matcher("re:/blog/"), window=28)
+rep.did          # {'ctr': points, 'clicks': relative, 'impressions': relative, 'position': ranks}
+rep.to_dict()
+```
+
+## Where this came from
+
+A title rewrite on a set of comparison pages, measured before/after, looked like nothing: 3.38% to
+3.37%. A second rewrite on another set, the same. Both times the tempting reading was "wait longer".
+With the untouched pages as control the answer was the same and available on day 28, and the
+proposal to rewrite 475 more titles was dropped. The weekly-block view is how a 40% cliff and its
+slow return were tracked without re-reading a daily chart every session. The tool packages those
+two habits.
+
+## Claude Code skill
+
+`skill/searchdiff/SKILL.md` teaches Claude Code to reach for the control group instead of the
+before/after, and how to read the two tables. Install by copying the folder:
+
+```
+cp -r skill/searchdiff ~/.claude/skills/searchdiff
+```
+
+## License
+
+MIT.

searchdiff-0.1.0/README.md

@@ -0,0 +1,118 @@
+# searchdiff
+
+Did the change work?
+
+Search Console answers two questions badly on its own. "When did traffic drop, and how far back is
+it?" gets a daily chart with the weekday wobble in it. "We rewrote the titles, did it help?" gets a
+before/after on the changed pages, which contains the season, the algorithm update, and the change,
+all mixed together. `searchdiff` gives the first question weekly blocks from a fixed anchor, and the
+second a control group and a difference in differences.
+
+```
+pip install git+https://github.com/tsurutanmen/searchdiff                 # CSV only, no dependencies
+pip install "git+https://github.com/tsurutanmen/searchdiff#egg=searchdiff[api]"   # plus the API
+```
+
+## Weekly blocks
+
+```
+$ searchdiff weeks daily.csv --anchor 2026-07-18
+
+week                    days  clicks   /day     impr    ctr   pos  vs prev  of peak
+2026-07-18..07-24     7    1486  212.3    28420   5.2%   6.6      +2%      95%
+2026-07-25..07-31     7    1487  212.4    28605   5.2%   7.0      +0%      95%
+2026-08-01..08-07     7    1562  223.1    28365   5.5%   6.1      +5%     100%  peak
+2026-08-08..08-14     7    1000  142.9    17816   5.6%   6.1     -36%      64%  CLIFF
+2026-08-15..08-21     7    1031  147.3    18516   5.6%   5.9      +3%      66%
+2026-08-22..08-28     7    1197  171.0    20313   5.9%   6.2     +16%      77%
+2026-08-29..08-31     3     483  161.0     8482   5.7%   7.6      -6%      72%
+last block is partial; its /day figure is comparable, its totals are not
+note: cliff in the block starting 2026-08-08 (-36%); latest block is at 72% of peak
+```
+
+`daily.csv` here is the `Dates` export from the Performance report, unchanged. Any CSV with
+`date,clicks,impressions[,position]` works, with or without a `page` column. Blocks are counted
+from the anchor in both directions, so the same anchor gives the same blocks next month.
+
+## Did the change work
+
+```
+$ searchdiff effect pages.csv --change 2026-08-04 --treated "re:/p/0[0-4]$" --window 28
+
+change on 2026-08-04, 28 days before and after
+
+            pages            clicks/day              impr/day                 ctr        position
+treated         5     30.25 ->     21.50     564.4 ->     409.5    5.36% ->    5.25%    7.2 ->    8.0
+control        35    182.57 ->    143.82    3487.6 ->    2512.7    5.23% ->    5.72%    7.7 ->    7.4
+
+difference in differences (treated change minus control change):
+  ctr           -0.60 points   (treated -0.11, control +0.49)
+  clicks/day     -7.7 %        (treated -28.9%, control -21.2%)
+  impr/day       +0.5 %        (treated -27.4%, control -28.0%)
+  position      +0.95 ranks    (treated +0.72, control -0.23; negative is better)
+```
+
+The treated pages lost 29% of their clicks after the change. So did everything else: a traffic cliff
+hit the whole site four days later. The difference in differences is within a CTR point of zero. The
+rewrite did nothing, and a before/after on the five pages alone would have called it a disaster.
+
+The same data with pages that really did get a lift:
+
+```
+  ctr           +3.41 points   (treated +3.33, control -0.09)
+  clicks/day    +49.0 %        (treated +20.4%, control -28.6%)
+```
+
+`pages.csv` needs `date,page,clicks,impressions[,position]` rows, which the API gives and the UI does
+not. `--treated` and `--control` take a substring, a glob, `re:` a regex, or `@file` with one URL per
+line. The control defaults to every page not treated; a control of the same kind as the treated pages
+is better. `--gap N` skips the first N days after the change for edits that take time to be re-indexed.
+
+The report adds notes when the window runs past the data, when the treated group has too few clicks
+for anything to be distinguishable from noise, and when treated and control moved together.
+
+## Fetching from the API
+
+```
+searchdiff fetch --site https://example.com/ --key service-account.json \
+    --start 2026-06-01 --end 2026-08-31 --out pages.csv --coverage
+```
+
+The service account's e-mail has to be added as a user of the property. `--coverage` prints how much
+of the clicks the query dimension shows. Search Console hides rare queries; on a site of ours the
+query-level sum was 39% of the total while the page-level sum matched it. Analyse by page unless the
+words are the point. Paging past 25,000 rows is handled.
+
+## Python
+
+```python
+import datetime as dt, searchdiff as sd
+
+rows = sd.load_csv("pages.csv")
+print(sd.weekly(rows, anchor=dt.date(2026, 7, 18)))
+rep = sd.effect(rows, dt.date(2026, 8, 4), sd.matcher("re:/blog/"), window=28)
+rep.did          # {'ctr': points, 'clicks': relative, 'impressions': relative, 'position': ranks}
+rep.to_dict()
+```
+
+## Where this came from
+
+A title rewrite on a set of comparison pages, measured before/after, looked like nothing: 3.38% to
+3.37%. A second rewrite on another set, the same. Both times the tempting reading was "wait longer".
+With the untouched pages as control the answer was the same and available on day 28, and the
+proposal to rewrite 475 more titles was dropped. The weekly-block view is how a 40% cliff and its
+slow return were tracked without re-reading a daily chart every session. The tool packages those
+two habits.
+
+## Claude Code skill
+
+`skill/searchdiff/SKILL.md` teaches Claude Code to reach for the control group instead of the
+before/after, and how to read the two tables. Install by copying the folder:
+
+```
+cp -r skill/searchdiff ~/.claude/skills/searchdiff
+```
+
+## License
+
+MIT.

searchdiff-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "searchdiff"
+version = "0.1.0"
+description = "Did the change work? Weekly blocks, cliffs, and difference-in-differences for Google Search Console data, from a CSV or the API."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Tsuruta Lab" }]
+keywords = ["search console", "seo", "difference in differences", "ctr", "analytics"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Internet :: WWW/HTTP :: Site Management",
+]
+dependencies = []
+
+[project.optional-dependencies]
+api = ["google-auth>=2.0", "requests>=2.25"]
+test = ["pytest>=7"]
+
+[project.urls]
+Homepage = "https://github.com/tsurutanmen/searchdiff"
+Issues = "https://github.com/tsurutanmen/searchdiff/issues"
+
+[project.scripts]
+searchdiff = "searchdiff.cli:main"
+
+[tool.setuptools.packages.find]
+include = ["searchdiff*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

searchdiff-0.1.0/searchdiff/__init__.py

@@ -0,0 +1,14 @@
+"""searchdiff: did the change work?
+
+Search Console data as weekly blocks (where was the cliff, how far back is
+it) and as a difference in differences (the pages you changed against the
+pages you did not, before and after).  Reads the UI's CSV exports or pulls
+from the API with a service account.
+"""
+
+from .data import Row, Totals, load_csv, write_csv
+from .weeks import weekly, WeeksReport
+from .effect import effect, matcher, EffectReport
+
+__version__ = "0.1.0"
+__all__ = ["Row", "Totals", "load_csv", "write_csv", "weekly", "WeeksReport", "effect", "matcher", "EffectReport"]

searchdiff-0.1.0/searchdiff/api.py

@@ -0,0 +1,77 @@
+"""Pull rows from the Search Console API with a service account.
+
+Needs the ``api`` extra: pip install "searchdiff[api]".
+The service account's e-mail must be added as a user of the property.
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+from typing import Dict, List, Optional, Sequence
+
+from .data import Row
+
+SCOPE = "https://www.googleapis.com/auth/webmasters.readonly"
+ROW_LIMIT = 25000
+
+
+def _session(key_path: str):
+    try:
+        from google.oauth2 import service_account
+        from google.auth.transport.requests import AuthorizedSession
+    except ImportError as exc:  # pragma: no cover
+        raise ImportError("pip install 'searchdiff[api]' for the Search Console API") from exc
+    creds = service_account.Credentials.from_service_account_file(key_path, scopes=[SCOPE])
+    return AuthorizedSession(creds)
+
+
+def query(site: str, key_path: str, start: dt.date, end: dt.date, dimensions: Sequence[str] = ("date", "page"),
+          session=None, search_type: str = "web", data_state: str = "final") -> List[Dict]:
+    """All rows for the dimensions, following ``startRow`` until the API runs dry."""
+    import urllib.parse
+    sess = session or _session(key_path)
+    url = f"https://www.googleapis.com/webmasters/v3/sites/{urllib.parse.quote(site, safe='')}/searchAnalytics/query"
+    out: List[Dict] = []
+    start_row = 0
+    while True:
+        body = {"startDate": start.isoformat(), "endDate": end.isoformat(), "dimensions": list(dimensions),
+                "rowLimit": ROW_LIMIT, "startRow": start_row, "type": search_type, "dataState": data_state}
+        r = sess.post(url, json=body, timeout=120)
+        r.raise_for_status()
+        rows = r.json().get("rows", [])
+        out.extend(rows)
+        if len(rows) < ROW_LIMIT:
+            break
+        start_row += ROW_LIMIT
+    return out
+
+
+def to_rows(api_rows: Sequence[Dict], dimensions: Sequence[str]) -> List[Row]:
+    di = {d: i for i, d in enumerate(dimensions)}
+    out = []
+    for r in api_rows:
+        keys = r.get("keys", [])
+        out.append(Row(
+            date=dt.date.fromisoformat(keys[di["date"]]) if "date" in di else None,
+            page=keys[di["page"]] if "page" in di else None,
+            clicks=float(r.get("clicks", 0)), impressions=float(r.get("impressions", 0)),
+            position=float(r["position"]) if "position" in r else None,
+        ))
+    return out
+
+
+def fetch(site: str, key_path: str, start: dt.date, end: dt.date, dimensions: Sequence[str] = ("date", "page")) -> List[Row]:
+    return to_rows(query(site, key_path, start, end, dimensions), dimensions)
+
+
+def coverage(site: str, key_path: str, start: dt.date, end: dt.date, session=None) -> Dict[str, float]:
+    """How much of the traffic the query dimension shows.  Search Console hides
+    rare queries, so the sum over queries is usually well below the total; the
+    sum over pages is not.  Analyse by page unless you need the words."""
+    total = query(site, key_path, start, end, dimensions=(), session=session)
+    q = query(site, key_path, start, end, dimensions=("query",), session=session)
+    p = query(site, key_path, start, end, dimensions=("page",), session=session)
+    tc = sum(r.get("clicks", 0) for r in total)
+    return {"total_clicks": tc,
+            "query_share": (sum(r.get("clicks", 0) for r in q) / tc) if tc else 0.0,
+            "page_share": (sum(r.get("clicks", 0) for r in p) / tc) if tc else 0.0}

searchdiff-0.1.0/searchdiff/cli.py

@@ -0,0 +1,73 @@
+"""searchdiff weeks DATA.csv [--anchor DATE]
+   searchdiff effect DATA.csv --change DATE --treated SPEC [--control SPEC] [--window 28] [--gap 0]
+   searchdiff fetch --site URL --key sa.json --start DATE --end DATE --out DATA.csv [--coverage]"""
+
+from __future__ import annotations
+
+import argparse
+import datetime as dt
+import json
+import sys
+
+from .data import load_csv, write_csv
+from .weeks import weekly
+from .effect import effect, matcher
+
+
+def _d(s: str) -> dt.date:
+    return dt.date.fromisoformat(s)
+
+
+def main(argv=None) -> int:
+    try:
+        sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+    except (AttributeError, ValueError):
+        pass
+    ap = argparse.ArgumentParser(prog="searchdiff", description="Did the change work? Search Console data as weekly blocks and difference-in-differences.")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    w = sub.add_parser("weeks", help="weekly blocks from an anchor date, cliffs, share of peak")
+    w.add_argument("data"); w.add_argument("--anchor", type=_d); w.add_argument("--block", type=int, default=7)
+    w.add_argument("--json")
+
+    e = sub.add_parser("effect", help="before/after on changed pages against a control")
+    e.add_argument("data"); e.add_argument("--change", type=_d, required=True)
+    e.add_argument("--treated", required=True, help="substring, glob, re:regex, or @file of URLs")
+    e.add_argument("--control", help="same forms; default: every page not treated")
+    e.add_argument("--window", type=int, default=28); e.add_argument("--gap", type=int, default=0)
+    e.add_argument("--json")
+
+    f = sub.add_parser("fetch", help="pull date x page rows from the API with a service account")
+    f.add_argument("--site", required=True, help="property, e.g. https://example.com/ or sc-domain:example.com")
+    f.add_argument("--key", required=True, help="service account JSON")
+    f.add_argument("--start", type=_d, required=True); f.add_argument("--end", type=_d, required=True)
+    f.add_argument("--out", required=True); f.add_argument("--dimensions", default="date,page")
+    f.add_argument("--coverage", action="store_true", help="also report how much traffic the query dimension shows")
+
+    a = ap.parse_args(argv)
+    if a.cmd == "weeks":
+        rep = weekly(load_csv(a.data), anchor=a.anchor, block_days=a.block)
+        print(rep)
+        if a.json:
+            json.dump(rep.to_dict(), open(a.json, "w", encoding="utf-8"), indent=1)
+    elif a.cmd == "effect":
+        rep = effect(load_csv(a.data), a.change, matcher(a.treated), matcher(a.control) if a.control else None,
+                     window=a.window, gap=a.gap)
+        print(rep)
+        if a.json:
+            json.dump(rep.to_dict(), open(a.json, "w", encoding="utf-8"), indent=1)
+    else:
+        from .api import fetch, coverage
+        dims = [d.strip() for d in a.dimensions.split(",") if d.strip()]
+        rows = fetch(a.site, a.key, a.start, a.end, dims)
+        write_csv(rows, a.out)
+        print(f"wrote {len(rows)} rows to {a.out}")
+        if a.coverage:
+            c = coverage(a.site, a.key, a.start, a.end)
+            print(f"total clicks {c['total_clicks']:.0f}; the query dimension shows {c['query_share']:.0%} of them, "
+                  f"the page dimension {c['page_share']:.0%}. Analyse by page unless you need the words.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

searchdiff-0.1.0/searchdiff/data.py

@@ -0,0 +1,119 @@
+"""Rows of Search Console data and how to read them from a CSV.
+
+A row is (date, page, clicks, impressions, position).  CTR is always
+recomputed from clicks and impressions, never read from the file, because
+exported CTRs are rounded and averaged CTRs are wrong.
+
+Accepted CSV shapes (header names are matched case-insensitively, a few
+synonyms are understood):
+
+    date,clicks,impressions[,ctr][,position]                   the UI "Dates" export
+    date,page,clicks,impressions[,ctr][,position]              per page per day (API)
+    page,clicks,impressions[,ctr][,position]                   the UI "Pages" export (no dates)
+"""
+
+from __future__ import annotations
+
+import csv
+import datetime as dt
+from dataclasses import dataclass
+from typing import Iterable, List, Optional
+
+SYNONYMS = {
+    "date": {"date", "day", "日付"},
+    "page": {"page", "url", "top pages", "pages", "ページ", "上位ページ"},
+    "clicks": {"clicks", "click", "クリック数", "クリック"},
+    "impressions": {"impressions", "impr", "表示回数", "表示"},
+    "position": {"position", "avg position", "average position", "掲載順位", "平均掲載順位"},
+}
+
+
+@dataclass(frozen=True)
+class Row:
+    date: Optional[dt.date]
+    page: Optional[str]
+    clicks: float
+    impressions: float
+    position: Optional[float]      # impression-weighted when aggregated
+
+
+def _col(header: List[str], key: str) -> Optional[int]:
+    names = {h.strip().lower(): i for i, h in enumerate(header)}
+    for syn in SYNONYMS[key]:
+        if syn in names:
+            return names[syn]
+    return None
+
+
+def _num(s: str) -> float:
+    s = (s or "").strip().replace(",", "").replace("%", "")
+    if s in ("", "-"):
+        return 0.0
+    return float(s)
+
+
+def _date(s: str) -> dt.date:
+    s = s.strip()
+    for fmt in ("%Y-%m-%d", "%Y/%m/%d", "%d/%m/%Y", "%m/%d/%Y", "%Y%m%d"):
+        try:
+            return dt.datetime.strptime(s, fmt).date()
+        except ValueError:
+            pass
+    return dt.date.fromisoformat(s[:10])
+
+
+def load_csv(path: str, delimiter: str = ",") -> List[Row]:
+    with open(path, newline="", encoding="utf-8-sig") as f:
+        reader = csv.reader(f, delimiter=delimiter)
+        header = next(reader)
+        ci = {k: _col(header, k) for k in SYNONYMS}
+        if ci["clicks"] is None or ci["impressions"] is None:
+            raise ValueError(f"need clicks and impressions columns; got {header}")
+        rows = []
+        for r in reader:
+            if not r or all(not c.strip() for c in r):
+                continue
+            rows.append(Row(
+                date=_date(r[ci["date"]]) if ci["date"] is not None else None,
+                page=r[ci["page"]].strip() if ci["page"] is not None else None,
+                clicks=_num(r[ci["clicks"]]),
+                impressions=_num(r[ci["impressions"]]),
+                position=_num(r[ci["position"]]) if ci["position"] is not None and r[ci["position"]].strip() else None,
+            ))
+    return rows
+
+
+def write_csv(rows: Iterable[Row], path: str) -> None:
+    with open(path, "w", newline="", encoding="utf-8") as f:
+        w = csv.writer(f)
+        w.writerow(["date", "page", "clicks", "impressions", "ctr", "position"])
+        for r in rows:
+            ctr = r.clicks / r.impressions if r.impressions else 0.0
+            w.writerow([r.date.isoformat() if r.date else "", r.page or "", int(r.clicks), int(r.impressions),
+                        f"{ctr:.4f}", "" if r.position is None else f"{r.position:.2f}"])
+
+
+@dataclass
+class Totals:
+    clicks: float = 0.0
+    impressions: float = 0.0
+    pos_weighted: float = 0.0
+    days: int = 0
+
+    def add(self, r: Row) -> None:
+        self.clicks += r.clicks
+        self.impressions += r.impressions
+        if r.position is not None:
+            self.pos_weighted += r.position * r.impressions
+
+    @property
+    def ctr(self) -> float:
+        return self.clicks / self.impressions if self.impressions else 0.0
+
+    @property
+    def position(self) -> Optional[float]:
+        return self.pos_weighted / self.impressions if self.impressions and self.pos_weighted else None
+
+    def per_day(self, key: str) -> float:
+        v = getattr(self, key)
+        return v / self.days if self.days else 0.0

searchdiff-0.1.0/searchdiff/effect.py

@@ -0,0 +1,145 @@
+"""Did the change work?  Before/after on the changed pages against a control.
+
+The number that answers the question is the difference in differences:
+
+    (treated_after - treated_before) - (control_after - control_before)
+
+for CTR (the usual target of a title or description rewrite), for clicks per
+day and for impressions per day.  The control's own change is printed next
+to it, because a treated group that "improved" by exactly what the control
+improved did not improve.
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+import fnmatch
+import re
+from dataclasses import dataclass, field
+from typing import Callable, Dict, List, Optional, Sequence
+
+from .data import Row, Totals
+
+
+def matcher(spec: Optional[str]) -> Callable[[str], bool]:
+    """A page selector: a regex (prefix 're:'), a glob with * or ?, a substring, or a file of URLs (prefix '@')."""
+    if not spec:
+        return lambda page: False
+    if spec.startswith("@"):
+        with open(spec[1:], encoding="utf-8") as f:
+            urls = {ln.strip() for ln in f if ln.strip() and not ln.startswith("#")}
+        return lambda page: page in urls
+    if spec.startswith("re:"):
+        rx = re.compile(spec[3:])
+        return lambda page: bool(rx.search(page))
+    if any(ch in spec for ch in "*?["):
+        return lambda page: fnmatch.fnmatch(page, spec)
+    return lambda page: spec in page
+
+
+@dataclass
+class Group:
+    name: str
+    pages: int
+    before: Totals
+    after: Totals
+
+    def delta(self, key: str) -> float:
+        """CTR: difference in points. Position: difference in ranks.
+        Clicks and impressions: relative change of the per-day rate, so groups
+        of different sizes can be compared."""
+        if key == "ctr":
+            return self.after.ctr - self.before.ctr
+        if key == "position":
+            a, b = self.after.position, self.before.position
+            return (a - b) if a is not None and b is not None else float("nan")
+        b = self.before.per_day(key)
+        return (self.after.per_day(key) - b) / b if b else float("nan")
+
+
+@dataclass
+class EffectReport:
+    change_date: dt.date
+    window: int
+    treated: Group
+    control: Group
+    did: Dict[str, float] = field(default_factory=dict)
+    notes: List[str] = field(default_factory=list)
+
+    def __str__(self) -> str:
+        t, c = self.treated, self.control
+        L = [f"change on {self.change_date.isoformat()}, {self.window} days before and after", ""]
+        L.append(f"{'':10s} {'pages':>6s} {'clicks/day':>21s} {'impr/day':>21s} {'ctr':>19s} {'position':>15s}")
+        for g in (t, c):
+            pb, pa = g.before.position, g.after.position
+            pos = f"{pb:6.1f} -> {pa:6.1f}" if pb is not None and pa is not None else f"{'':6s}    {'':6s}"
+            L.append(f"{g.name:10s} {g.pages:6d} {g.before.per_day('clicks'):9.2f} -> {g.after.per_day('clicks'):9.2f} "
+                     f"{g.before.per_day('impressions'):9.1f} -> {g.after.per_day('impressions'):9.1f} "
+                     f"{g.before.ctr:8.2%} -> {g.after.ctr:8.2%} {pos:>15s}")
+        L.append("")
+        L.append("difference in differences (treated change minus control change):")
+        L.append(f"  ctr          {self.did['ctr']:+6.2f} points   (treated {t.delta('ctr')*100:+.2f}, control {c.delta('ctr')*100:+.2f})")
+        L.append(f"  clicks/day   {self.did['clicks']*100:+6.1f} %        (treated {t.delta('clicks'):+.1%}, control {c.delta('clicks'):+.1%})")
+        L.append(f"  impr/day     {self.did['impressions']*100:+6.1f} %        (treated {t.delta('impressions'):+.1%}, control {c.delta('impressions'):+.1%})")
+        if "position" in self.did and self.did["position"] == self.did["position"]:
+            L.append(f"  position     {self.did['position']:+6.2f} ranks    (treated {t.delta('position'):+.2f}, control {c.delta('position'):+.2f}; negative is better)")
+        for n in self.notes:
+            L.append(f"note: {n}")
+        return "\n".join(L)
+
+    def to_dict(self) -> dict:
+        def g(x: Group):
+            return {"name": x.name, "pages": x.pages,
+                    "before": {"clicks_per_day": x.before.per_day("clicks"), "impressions_per_day": x.before.per_day("impressions"),
+                               "ctr": x.before.ctr, "position": x.before.position, "days": x.before.days},
+                    "after": {"clicks_per_day": x.after.per_day("clicks"), "impressions_per_day": x.after.per_day("impressions"),
+                              "ctr": x.after.ctr, "position": x.after.position, "days": x.after.days}}
+        return {"change_date": self.change_date.isoformat(), "window": self.window,
+                "treated": g(self.treated), "control": g(self.control), "did": self.did, "notes": self.notes}
+
+
+def _totals(rows: Sequence[Row], lo: dt.date, hi: dt.date) -> Totals:
+    t = Totals()
+    days = set()
+    for r in rows:
+        if r.date is not None and lo <= r.date <= hi:
+            t.add(r)
+            days.add(r.date)
+    t.days = (hi - lo).days + 1
+    return t
+
+
+def effect(rows: List[Row], change_date: dt.date, treated: Callable[[str], bool],
+           control: Optional[Callable[[str], bool]] = None, window: int = 28, gap: int = 0) -> EffectReport:
+    """``gap`` days after the change are excluded, for changes that take time to be re-indexed."""
+    paged = [r for r in rows if r.date is not None and r.page]
+    if not paged:
+        raise ValueError("the effect view needs rows with both a date and a page")
+    tr = [r for r in paged if treated(r.page)]
+    ct = [r for r in paged if (control(r.page) if control else not treated(r.page))]
+    b_lo, b_hi = change_date - dt.timedelta(days=window), change_date - dt.timedelta(days=1)
+    a_lo, a_hi = change_date + dt.timedelta(days=gap), change_date + dt.timedelta(days=gap + window - 1)
+    first = min(r.date for r in paged); last = max(r.date for r in paged)
+
+    T = Group("treated", len({r.page for r in tr}), _totals(tr, b_lo, b_hi), _totals(tr, a_lo, a_hi))
+    C = Group("control", len({r.page for r in ct}), _totals(ct, b_lo, b_hi), _totals(ct, a_lo, a_hi))
+    rep = EffectReport(change_date=change_date, window=window, treated=T, control=C)
+    rep.did = {
+        "ctr": (T.delta("ctr") - C.delta("ctr")) * 100.0,
+        "clicks": T.delta("clicks") - C.delta("clicks"),
+        "impressions": T.delta("impressions") - C.delta("impressions"),
+        "position": T.delta("position") - C.delta("position"),
+    }
+    if T.pages == 0:
+        rep.notes.append("no treated pages matched")
+    if C.pages == 0:
+        rep.notes.append("no control pages; the before/after of the treated group alone cannot separate the change from the season")
+    if b_lo < first or a_hi > last:
+        rep.notes.append(f"data covers {first.isoformat()}..{last.isoformat()}; the window {b_lo.isoformat()}..{a_hi.isoformat()} is cut short")
+    if T.before.impressions and T.before.impressions < 200 * 1:
+        rep.notes.append("treated group has few impressions before the change; a CTR point is worth less than a click here")
+    if T.before.clicks + T.after.clicks < 30:
+        rep.notes.append("fewer than 30 treated clicks in total; nothing here is distinguishable from noise")
+    if T.pages and C.pages and abs(C.delta("ctr")) > 0 and abs(T.delta("ctr") - C.delta("ctr")) < 0.002:
+        rep.notes.append("treated and control moved together: the change did not do anything the control did not also do")
+    return rep

searchdiff-0.1.0/searchdiff/weeks.py

@@ -0,0 +1,116 @@
+"""Weekly blocks from an anchor date, with cliffs and recovery."""
+
+from __future__ import annotations
+
+import datetime as dt
+from dataclasses import dataclass, field
+from typing import List, Optional
+
+from .data import Row, Totals
+
+CLIFF = -0.30      # week-over-week change that counts as a cliff
+
+
+@dataclass
+class Week:
+    start: dt.date
+    end: dt.date
+    days: int
+    totals: Totals
+    change: Optional[float] = None       # clicks/day vs previous block
+    of_peak: float = 0.0
+    flag: str = ""
+
+
+@dataclass
+class WeeksReport:
+    anchor: dt.date
+    weeks: List[Week] = field(default_factory=list)
+    partial_last: bool = False
+    notes: List[str] = field(default_factory=list)
+
+    def __str__(self) -> str:
+        L = [f"weekly blocks from {self.anchor.isoformat()}", ""]
+        L.append(f"{'week':23s} {'days':>4s} {'clicks':>7s} {'/day':>6s} {'impr':>8s} {'ctr':>6s} {'pos':>5s} {'vs prev':>8s} {'of peak':>8s}  ")
+        for w in self.weeks:
+            t = w.totals
+            ch = "" if w.change is None else f"{w.change:+.0%}"
+            pos = "" if t.position is None else f"{t.position:.1f}"
+            L.append(f"{w.start.isoformat()}..{w.end.strftime('%m-%d'):6s} {w.days:4d} {t.clicks:7.0f} {t.per_day('clicks'):6.1f} "
+                     f"{t.impressions:8.0f} {t.ctr:6.1%} {pos:>5s} {ch:>8s} {w.of_peak:8.0%}  {w.flag}")
+        if self.partial_last:
+            L.append("last block is partial; its /day figure is comparable, its totals are not")
+        for n in self.notes:
+            L.append(f"note: {n}")
+        return "\n".join(L)
+
+    def to_dict(self) -> dict:
+        return {"anchor": self.anchor.isoformat(), "partial_last": self.partial_last, "notes": self.notes,
+                "weeks": [{"start": w.start.isoformat(), "end": w.end.isoformat(), "days": w.days,
+                           "clicks": w.totals.clicks, "impressions": w.totals.impressions, "ctr": w.totals.ctr,
+                           "position": w.totals.position, "clicks_per_day": w.totals.per_day("clicks"),
+                           "change": w.change, "of_peak": w.of_peak, "flag": w.flag} for w in self.weeks]}
+
+
+def weekly(rows: List[Row], anchor: Optional[dt.date] = None, block_days: int = 7) -> WeeksReport:
+    dated = [r for r in rows if r.date is not None]
+    if not dated:
+        raise ValueError("no dated rows; the weeks view needs a date column")
+    days = sorted({r.date for r in dated})
+    first, last = days[0], days[-1]
+    if anchor is None:
+        anchor = first
+    # walk backwards from the anchor so blocks before it also line up
+    start = anchor
+    while start - dt.timedelta(days=block_days) >= first:
+        start -= dt.timedelta(days=block_days)
+    while start > first:
+        start -= dt.timedelta(days=block_days)
+
+    by_day = {}
+    for r in dated:
+        t = by_day.setdefault(r.date, Totals())
+        t.add(r)
+    rep = WeeksReport(anchor=anchor)
+    cur = start
+    prev_rate = None
+    while cur <= last:
+        end = cur + dt.timedelta(days=block_days - 1)
+        tot = Totals()
+        n = 0
+        for d in days:
+            if cur <= d <= end:
+                t = by_day[d]
+                tot.clicks += t.clicks; tot.impressions += t.impressions; tot.pos_weighted += t.pos_weighted
+                n += 1
+        tot.days = n
+        if n:
+            w = Week(start=cur, end=min(end, last), days=n, totals=tot)
+            rate = tot.per_day("clicks")
+            if prev_rate:
+                w.change = (rate - prev_rate) / prev_rate
+            prev_rate = rate if rate else prev_rate
+            rep.weeks.append(w)
+        cur = end + dt.timedelta(days=1)
+    if rep.weeks:
+        peak = max(w.totals.per_day("clicks") for w in rep.weeks) or 1.0
+        for w in rep.weeks:
+            w.of_peak = w.totals.per_day("clicks") / peak
+            if w.change is not None and w.change <= CLIFF:
+                w.flag = "CLIFF"
+            elif w.of_peak >= 0.999:
+                w.flag = "peak"
+        rep.partial_last = rep.weeks[-1].days < block_days
+        cliffs = [w for w in rep.weeks if w.flag == "CLIFF"]
+        if cliffs:
+            c = cliffs[-1]
+            after = [w for w in rep.weeks if w.start > c.start]
+            if after:
+                rep.notes.append(f"cliff in the block starting {c.start.isoformat()} ({c.change:+.0%}); "
+                                 f"latest block is at {rep.weeks[-1].of_peak:.0%} of peak")
+        span = (last - first).days + 1
+        if span < 28:
+            rep.notes.append(f"only {span} days of data; week-over-week changes are noisy below four weeks")
+        if last >= dt.date.today() - dt.timedelta(days=3):
+            rep.notes.append("Search Console lags two to three days; the last block will grow")
+    return rep

searchdiff-0.1.0/searchdiff.egg-info/PKG-INFO

@@ -0,0 +1,142 @@
+Metadata-Version: 2.4
+Name: searchdiff
+Version: 0.1.0
+Summary: Did the change work? Weekly blocks, cliffs, and difference-in-differences for Google Search Console data, from a CSV or the API.
+Author: Tsuruta Lab
+License: MIT
+Project-URL: Homepage, https://github.com/tsurutanmen/searchdiff
+Project-URL: Issues, https://github.com/tsurutanmen/searchdiff/issues
+Keywords: search console,seo,difference in differences,ctr,analytics
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Internet :: WWW/HTTP :: Site Management
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: api
+Requires-Dist: google-auth>=2.0; extra == "api"
+Requires-Dist: requests>=2.25; extra == "api"
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Dynamic: license-file
+
+# searchdiff
+
+Did the change work?
+
+Search Console answers two questions badly on its own. "When did traffic drop, and how far back is
+it?" gets a daily chart with the weekday wobble in it. "We rewrote the titles, did it help?" gets a
+before/after on the changed pages, which contains the season, the algorithm update, and the change,
+all mixed together. `searchdiff` gives the first question weekly blocks from a fixed anchor, and the
+second a control group and a difference in differences.
+
+```
+pip install git+https://github.com/tsurutanmen/searchdiff                 # CSV only, no dependencies
+pip install "git+https://github.com/tsurutanmen/searchdiff#egg=searchdiff[api]"   # plus the API
+```
+
+## Weekly blocks
+
+```
+$ searchdiff weeks daily.csv --anchor 2026-07-18
+
+week                    days  clicks   /day     impr    ctr   pos  vs prev  of peak
+2026-07-18..07-24     7    1486  212.3    28420   5.2%   6.6      +2%      95%
+2026-07-25..07-31     7    1487  212.4    28605   5.2%   7.0      +0%      95%
+2026-08-01..08-07     7    1562  223.1    28365   5.5%   6.1      +5%     100%  peak
+2026-08-08..08-14     7    1000  142.9    17816   5.6%   6.1     -36%      64%  CLIFF
+2026-08-15..08-21     7    1031  147.3    18516   5.6%   5.9      +3%      66%
+2026-08-22..08-28     7    1197  171.0    20313   5.9%   6.2     +16%      77%
+2026-08-29..08-31     3     483  161.0     8482   5.7%   7.6      -6%      72%
+last block is partial; its /day figure is comparable, its totals are not
+note: cliff in the block starting 2026-08-08 (-36%); latest block is at 72% of peak
+```
+
+`daily.csv` here is the `Dates` export from the Performance report, unchanged. Any CSV with
+`date,clicks,impressions[,position]` works, with or without a `page` column. Blocks are counted
+from the anchor in both directions, so the same anchor gives the same blocks next month.
+
+## Did the change work
+
+```
+$ searchdiff effect pages.csv --change 2026-08-04 --treated "re:/p/0[0-4]$" --window 28
+
+change on 2026-08-04, 28 days before and after
+
+            pages            clicks/day              impr/day                 ctr        position
+treated         5     30.25 ->     21.50     564.4 ->     409.5    5.36% ->    5.25%    7.2 ->    8.0
+control        35    182.57 ->    143.82    3487.6 ->    2512.7    5.23% ->    5.72%    7.7 ->    7.4
+
+difference in differences (treated change minus control change):
+  ctr           -0.60 points   (treated -0.11, control +0.49)
+  clicks/day     -7.7 %        (treated -28.9%, control -21.2%)
+  impr/day       +0.5 %        (treated -27.4%, control -28.0%)
+  position      +0.95 ranks    (treated +0.72, control -0.23; negative is better)
+```
+
+The treated pages lost 29% of their clicks after the change. So did everything else: a traffic cliff
+hit the whole site four days later. The difference in differences is within a CTR point of zero. The
+rewrite did nothing, and a before/after on the five pages alone would have called it a disaster.
+
+The same data with pages that really did get a lift:
+
+```
+  ctr           +3.41 points   (treated +3.33, control -0.09)
+  clicks/day    +49.0 %        (treated +20.4%, control -28.6%)
+```
+
+`pages.csv` needs `date,page,clicks,impressions[,position]` rows, which the API gives and the UI does
+not. `--treated` and `--control` take a substring, a glob, `re:` a regex, or `@file` with one URL per
+line. The control defaults to every page not treated; a control of the same kind as the treated pages
+is better. `--gap N` skips the first N days after the change for edits that take time to be re-indexed.
+
+The report adds notes when the window runs past the data, when the treated group has too few clicks
+for anything to be distinguishable from noise, and when treated and control moved together.
+
+## Fetching from the API
+
+```
+searchdiff fetch --site https://example.com/ --key service-account.json \
+    --start 2026-06-01 --end 2026-08-31 --out pages.csv --coverage
+```
+
+The service account's e-mail has to be added as a user of the property. `--coverage` prints how much
+of the clicks the query dimension shows. Search Console hides rare queries; on a site of ours the
+query-level sum was 39% of the total while the page-level sum matched it. Analyse by page unless the
+words are the point. Paging past 25,000 rows is handled.
+
+## Python
+
+```python
+import datetime as dt, searchdiff as sd
+
+rows = sd.load_csv("pages.csv")
+print(sd.weekly(rows, anchor=dt.date(2026, 7, 18)))
+rep = sd.effect(rows, dt.date(2026, 8, 4), sd.matcher("re:/blog/"), window=28)
+rep.did          # {'ctr': points, 'clicks': relative, 'impressions': relative, 'position': ranks}
+rep.to_dict()
+```
+
+## Where this came from
+
+A title rewrite on a set of comparison pages, measured before/after, looked like nothing: 3.38% to
+3.37%. A second rewrite on another set, the same. Both times the tempting reading was "wait longer".
+With the untouched pages as control the answer was the same and available on day 28, and the
+proposal to rewrite 475 more titles was dropped. The weekly-block view is how a 40% cliff and its
+slow return were tracked without re-reading a daily chart every session. The tool packages those
+two habits.
+
+## Claude Code skill
+
+`skill/searchdiff/SKILL.md` teaches Claude Code to reach for the control group instead of the
+before/after, and how to read the two tables. Install by copying the folder:
+
+```
+cp -r skill/searchdiff ~/.claude/skills/searchdiff
+```
+
+## License
+
+MIT.

searchdiff-0.1.0/searchdiff.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+LICENSE
+README.md
+pyproject.toml
+searchdiff/__init__.py
+searchdiff/api.py
+searchdiff/cli.py
+searchdiff/data.py
+searchdiff/effect.py
+searchdiff/weeks.py
+searchdiff.egg-info/PKG-INFO
+searchdiff.egg-info/SOURCES.txt
+searchdiff.egg-info/dependency_links.txt
+searchdiff.egg-info/entry_points.txt
+searchdiff.egg-info/requires.txt
+searchdiff.egg-info/top_level.txt
+tests/test_searchdiff.py

searchdiff-0.1.0/searchdiff.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

searchdiff-0.1.0/searchdiff.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+searchdiff = searchdiff.cli:main

searchdiff-0.1.0/searchdiff.egg-info/requires.txt

@@ -0,0 +1,7 @@
+
+[api]
+google-auth>=2.0
+requests>=2.25
+
+[test]
+pytest>=7

searchdiff-0.1.0/searchdiff.egg-info/top_level.txt

@@ -0,0 +1 @@
+searchdiff

searchdiff-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

searchdiff-0.1.0/tests/test_searchdiff.py

@@ -0,0 +1,107 @@
+import datetime as dt
+import os
+import subprocess
+import sys
+
+import pytest
+
+import searchdiff as sd
+from searchdiff.api import to_rows
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+DATA = os.path.join(HERE, "data")
+
+
+@pytest.fixture(scope="module", autouse=True)
+def data():
+    if not os.path.exists(os.path.join(DATA, "pages.csv")):
+        subprocess.check_call([sys.executable, os.path.join(HERE, "make_data.py")])
+
+
+def test_load_ui_export_shape():
+    rows = sd.load_csv(os.path.join(DATA, "daily.csv"))
+    assert len(rows) == 90 and rows[0].page is None and rows[0].date == dt.date(2026, 6, 3)
+    assert rows[0].position is not None
+
+
+def test_weeks_find_the_cliff():
+    rep = sd.weekly(sd.load_csv(os.path.join(DATA, "daily.csv")), anchor=dt.date(2026, 7, 18))
+    flags = {w.start: w.flag for w in rep.weeks}
+    assert flags[dt.date(2026, 8, 8)] == "CLIFF"
+    assert any("cliff in the block starting 2026-08-08" in n for n in rep.notes)
+    assert any(w.flag == "peak" for w in rep.weeks)
+    assert all(0 < w.of_peak <= 1.0 for w in rep.weeks)
+    # blocks line up on the anchor
+    assert dt.date(2026, 7, 18) in flags
+
+
+def test_weeks_anchor_defaults_to_first_day():
+    rep = sd.weekly(sd.load_csv(os.path.join(DATA, "daily.csv")))
+    assert rep.weeks[0].start == dt.date(2026, 6, 3)
+    assert rep.weeks[-1].days <= 7
+
+
+def test_effect_null_change_is_null():
+    rows = sd.load_csv(os.path.join(DATA, "pages.csv"))
+    rep = sd.effect(rows, dt.date(2026, 8, 4), sd.matcher("re:/p/0[0-4]$"), window=28)
+    assert rep.treated.pages == 5 and rep.control.pages == 35
+    assert abs(rep.did["ctr"]) < 1.0            # within a CTR point of zero
+    # the cliff hit both groups: treated alone looks like a loss, the control explains it
+    assert rep.treated.delta("impressions") < 0 and rep.control.delta("impressions") < 0
+
+
+def test_effect_real_lift_is_seen():
+    rows = sd.load_csv(os.path.join(DATA, "pages.csv"))
+    rep = sd.effect(rows, dt.date(2026, 8, 4), sd.matcher("re:/p/1[0-4]$"), control=sd.matcher("re:/p/[23][0-9]$"), window=28)
+    assert rep.did["ctr"] > 2.0
+    assert rep.did["clicks"] > 0.2                 # more than +20% relative to the control's change
+
+
+def test_matchers(tmp_path):
+    assert sd.matcher("/p/01")("https://example.com/p/01")
+    assert sd.matcher("*/p/0?")("https://example.com/p/07")
+    assert not sd.matcher("re:/p/1")("https://example.com/p/07")
+    f = tmp_path / "urls.txt"; f.write_text("https://example.com/p/03\n# c\n")
+    assert sd.matcher("@" + str(f))("https://example.com/p/03")
+    assert not sd.matcher(None)("anything")
+
+
+def test_effect_notes_when_window_exceeds_data():
+    rows = sd.load_csv(os.path.join(DATA, "pages.csv"))
+    rep = sd.effect(rows, dt.date(2026, 8, 25), sd.matcher("/p/00"), window=28)
+    assert any("cut short" in n for n in rep.notes)
+
+
+def test_api_rows_conversion():
+    api_rows = [{"keys": ["2026-08-01", "https://e.com/a"], "clicks": 3, "impressions": 50, "ctr": 0.06, "position": 4.2}]
+    rows = to_rows(api_rows, ("date", "page"))
+    assert rows[0].date == dt.date(2026, 8, 1) and rows[0].page == "https://e.com/a" and rows[0].clicks == 3
+
+
+def test_api_query_pages_with_mock():
+    from searchdiff.api import query, ROW_LIMIT
+
+    class Resp:
+        def __init__(self, rows): self._rows = rows
+        def raise_for_status(self): pass
+        def json(self): return {"rows": self._rows}
+
+    class Sess:
+        def __init__(self): self.calls = []
+        def post(self, url, json, timeout):
+            self.calls.append(json["startRow"])
+            n = ROW_LIMIT if json["startRow"] == 0 else 3
+            return Resp([{"keys": ["2026-08-01", "x"], "clicks": 1, "impressions": 1} for _ in range(n)])
+
+    s = Sess()
+    rows = query("https://e.com/", "unused", dt.date(2026, 8, 1), dt.date(2026, 8, 2), session=s)
+    assert len(rows) == ROW_LIMIT + 3 and s.calls == [0, ROW_LIMIT]
+
+
+def test_cli(tmp_path, capsys):
+    from searchdiff.cli import main
+    out = tmp_path / "w.json"
+    assert main(["weeks", os.path.join(DATA, "daily.csv"), "--anchor", "2026-07-18", "--json", str(out)]) == 0
+    assert "CLIFF" in capsys.readouterr().out and out.exists()
+    assert main(["effect", os.path.join(DATA, "pages.csv"), "--change", "2026-08-04", "--treated", "re:/p/0[0-4]$"]) == 0
+    assert "difference in differences" in capsys.readouterr().out