megaton

Megaton is a Python toolkit for working with Google Analytics 4, Google Search Console, Google Sheets, and BigQuery from Notebooks with minimal code. It focuses on fast iteration during analysis and provides a UX tailored for Notebook workflows.

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
• Notebook-first — Designed for inspecting intermediate results at every step

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