megaton

Megaton is a Python and CLI toolkit for Google Analytics 4, Search Console, Google Sheets and BigQuery. Run a single query without an application checkout; use the same operations from scripts, Notebooks and MCP adapters.

Python and CLI

pip install megaton
megaton query --params query.json --credential /path/to/google.json --output result.csv
megaton resources gsc --credential /path/to/google.json
python -m megaton query --params query.json --validate-only

query.json selects the resource and dates explicitly:

{
  "schema_version": "1.0",
  "source": "ga4",
  "property_id": "123456789",
  "date_range": {"start": "2026-01-01", "end": "2026-01-31"},
  "dimensions": ["date"],
  "metrics": ["sessions"]
}

from megaton.query import run_query

result = run_query(params, credential="/path/to/google.json")
df = result.df
result.save("result.csv")

The core package provides single Google queries; megaton-app adds multi-step workflows, Adobe, jobs, audits, validation and delivery. See the machine interface contract for GSC/BQ requests, authentication, JSON output and MCP integration. These commands are available from 2.3.0.

Core Concepts

Version 2.2.0 includes reliability changes. GA4/GSC query errors and Sheets read/upsert errors now raise instead of looking like empty results. Sheets overwrite uses one atomic request; structural mutations are submitted once. See failure handling and migration before upgrading scheduled jobs from 2.1.3.

• Result objects — Method chaining via SearchResult / ReportResult
• Simple flow — Open → Set dates → Run → Save
• Shared operations — Explicit machine requests and interactive Notebook sessions

Quick Start

Prerequisites

You need a Google Cloud service account JSON file with access to GA4, Search Console, or Sheets. See Google Cloud docs for how to create one.

Install

pip install megaton              # core (headless / programmatic use)
pip install megaton[notebook]    # + ipywidgets for the interactive selection UI

ipywidgets is no longer a core dependency (since 2.0). Install the notebook extra when you want the widget-based credential/account/property picker used by Megaton(...) in Jupyter/Colab. For scripts, CI, or headless runs, the core install is enough — use Megaton(..., headless=True), Megaton.for_property(...), or Megaton.for_site(...).

Run a GA4 report and save to Google Sheets

For normal Sheets work, use one flow: mg.open.sheet(...) opens a Spreadsheet, mg.sheets.* selects or manages Worksheets, and mg.sheet.* operates on the selected Worksheet.

from megaton.start import Megaton

# Interactive (Jupyter/Colab): needs megaton[notebook] for the picker UI.
mg = Megaton("/path/to/service_account.json")
# Scripts/CI (core install, no widgets): select the property up front.
# mg = Megaton.for_property("YOUR_GA4_PROPERTY_ID", "/path/to/service_account.json")

# GA4: fetch event data
mg.report.set.dates("2024-01-01", "2024-01-31")
result = mg.report.run(d=["date", "eventName"], m=["eventCount"])

# Save to Google Sheets
mg.open.sheet("https://docs.google.com/spreadsheets/d/...")
mg.sheets.select("_ga_data")
mg.sheet.save(result)
mg.sheet.freeze(rows=1)
mg.sheet.resize(rows=1000, cols=20)
mg.sheet.gridlines.hide()
mg.sheet.tab.color("#2f80ed")

Run the same report over multiple date ranges

df = mg.report.run.ranges(
    date_ranges=[("2024-01-01", "2024-01-31"), ("2025-01-01", "2025-01-31")],
    d=["date", "eventName"],
    m=["eventCount"],
)

Read a worksheet as DataFrame

mg.open.sheet("https://docs.google.com/spreadsheets/d/...")
daily_df = mg.sheets.read("daily")

Duplicate a worksheet and patch a cell

mg.open.sheet("https://docs.google.com/spreadsheets/d/...")
mg.sheets.duplicate(
    "template",
    "report_2024_02",
    cell_update={"cell": "B1", "value": "202402"},
)

Search Console with method chaining

# query_map: dict mapping regex patterns to category names
# e.g. {"brand.*keyword": "Brand", ".*": "(other)"}
result = (mg.search
    .run(dimensions=['query', 'page'], clean=True)
    .categorize('query', by=query_map)
    .filter_impressions(min=100)
)

mg.open.sheet("https://docs.google.com/spreadsheets/d/...")
mg.sheets.select("_query")
mg.sheet.save(result, sort_by="impressions")

Installation

# From PyPI
pip install megaton

# Latest from GitHub
pip install git+https://github.com/mak00s/megaton.git

Documentation

Note: Detailed docs are written in Japanese.

If you're new, start with the cookbook for practical examples, then refer to the API reference for details.

Testing & Coverage

pytest --cov=megaton --cov-report=term-missing

Changelog

• CHANGELOG.md
• docs/changelog-archive.md — 0.x series history

License

MIT License