Skip to content
gsearch

v0.1.0

The first public release of gsearch: the full command surface, six verticals, roughly forty rich-feature extractors, a DuckDB store, JSON and Markdown export, and CAPTCHA recovery through a persistent profile.

The first public release. gsearch drives a real Chrome through patchright, waits for a Google Search results page to render, and reads the rich blocks straight out of the live DOM. There is no API key and no per-query bill, because there is no service in the middle: it renders the page you would see yourself and shapes the result into one structured object.

What you get

  • Read the rich blocks. gsearch search pulls roughly forty kinds of Google answer card from a single rendered page: the knowledge panel, weather, sports standings and scores, schedule and player stats, translation, dictionary, calculator, unit converter, currency, direct answer, time, stock and crypto quotes, finance fundamentals, the featured snippet, the AI overview, things to know, videos, recipes, podcasts, web stories, shopping, hotels, flights, events, jobs, the local pack, social posts, discussions, spelling corrections, and search refinements, plus the organic results, People Also Ask, related searches, and top stories underneath.
  • Six verticals. -v switches between web, images, videos, news, shopping, and books, each with its own extractor and result shape.
  • Structured output. --json prints the whole result to stdout for jq or another program, and every run also writes a dated JSON and Markdown file under ~/data/gsearch.
  • A DuckDB store. --save upserts each result into DuckDB, and info, dump, and export give you a feature breakdown, a reprint of recent searches, and a re-export to files.
  • Raw API capture. capture records the raw batchexecute and /_/search responses Google fires while a SERP loads, one file per response, for research.
  • CAPTCHA recovery. A persistent Chrome profile at ~/.cache/gsearch-profile carries a solved consent or CAPTCHA forward, so after one --no-headless solve the headless runs that follow go straight through.

The five commands

Command What it does
search Fetch all rich content for a query (the main command)
info Show DuckDB statistics and a feature breakdown
dump Print recent searches stored in the database
export Re-export recent stored results to JSON + Markdown
capture Save the raw AJAX/XHR responses Google makes while loading a SERP

How it works

gsearch launches Google Chrome through patchright, which patches the CDP-level tells that mark an automated browser, navigates to the ordinary https://www.google.com/search URL, waits for the page to render, and runs extract.js against the live DOM. The result comes back to Python for the terminal summary, the JSON and Markdown export, and optional DuckDB storage.

Install

uv tool install gsearch
patchright install chromium      # the browser patchright drives
gsearch search "epl"

Or from source:

git clone https://github.com/tamnd/gsearch
cd gsearch
make sync
make browser
uv run gsearch search "epl"

gsearch needs Python 3.11 or later and a Chrome or Chromium build for patchright to drive. See installation for the details.

3 min read