scrapebadger-cli 0.2.1__py3-none-any.whl

scrapebadger_cli/commands/google.py

@@ -0,0 +1,1117 @@
+"""Google scraper commands — 19 product APIs / 39 endpoints.
+
+Each subcommand maps 1:1 to a ``/v1/google/*`` route. Use ``scrapebadger
+google --help`` to see the full list.
+
+Typical workflow:
+
+    # Web search
+    scrapebadger google search "python 3.13"
+
+    # Shopping search; pipe gpcid into products detail for full specs + offers
+    scrapebadger google shopping "laptop"
+    scrapebadger google product-detail 7768723536481519578 --q "laptop" --include-offers
+"""
+
+import typer
+
+from scrapebadger_cli.client import api_get
+from scrapebadger_cli.output import render
+
+app = typer.Typer(no_args_is_help=True)
+
+FMT = typer.Option("json", "--output", "-o", help="Output format: json, csv, table, markdown")
+FIELDS = typer.Option(None, "--fields", "-f", help="Comma-separated fields to include")
+
+
+# ---------------------------------------------------------------------------
+# Search
+# ---------------------------------------------------------------------------
+
+
+@app.command()
+def search(
+    q: str = typer.Argument(..., help="Search query"),
+    gl: str | None = typer.Option(None, "--gl", help="Country code (e.g. us, gb)"),
+    hl: str | None = typer.Option(None, "--hl", help="Language code (e.g. en, fr)"),
+    num: int | None = typer.Option(None, "--num", "-n", help="Number of results"),
+    start: int | None = typer.Option(None, "--start", help="Page offset (0, 10, 20...)"),
+    domain: str | None = typer.Option(None, "--domain", help="Google domain (e.g. google.co.uk)"),
+    device: str | None = typer.Option(None, "--device", help="'desktop' or 'mobile'"),
+    location: str | None = typer.Option(None, "--location", help="City-level geo-targeting"),
+    tbs: str | None = typer.Option(None, "--tbs", help="Time filter (e.g. qdr:d)"),
+    safe: str | None = typer.Option(None, "--safe", help="Safe search: off, medium, high"),
+    ai_overview: bool = typer.Option(
+        False,
+        "--ai-overview",
+        help="Chase deferred AI Overview page_token when the SERP defers it",
+    ),
+    fmt: str = FMT,
+    fields: str | None = FIELDS,
+) -> None:
+    """Google web search (SERP)."""
+    data = api_get(
+        "/v1/google/search",
+        {
+            "q": q,
+            "gl": gl,
+            "hl": hl,
+            "num": num,
+            "start": start,
+            "domain": domain,
+            "device": device,
+            "location": location,
+            "tbs": tbs,
+            "safe": safe,
+            "ai_overview": ai_overview if ai_overview else None,
+        },
+    )
+    render(data, fmt, fields)
+
+
+@app.command(name="light-search")
+def light_search(
+    q: str = typer.Argument(..., help="Search query"),
+    gl: str | None = typer.Option(None, "--gl", help="Country code"),
+    hl: str | None = typer.Option(None, "--hl", help="Language code"),
+    num: int | None = typer.Option(None, "--num", "-n", help="Results per page (1-100)"),
+    start: int | None = typer.Option(None, "--start", help="Pagination offset"),
+    domain: str | None = typer.Option(None, "--domain", help="Google domain"),
+    location: str | None = typer.Option(None, "--location", help="City-level geo-targeting"),
+    safe: str | None = typer.Option(None, "--safe", help="off / active"),
+    fmt: str = FMT,
+    fields: str | None = FIELDS,
+) -> None:
+    """Google Light Search — organic + related searches only (~40% faster than full SERP)."""
+    data = api_get(
+        "/v1/google/search",
+        {
+            "q": q,
+            "gl": gl,
+            "hl": hl,
+            "num": num,
+            "start": start,
+            "domain": domain,
+            "location": location,
+            "safe": safe,
+            "mode": "fast",
+        },
+    )
+    render(data, fmt, fields)
+
+
+# ---------------------------------------------------------------------------
+# Maps (5 endpoints)
+# ---------------------------------------------------------------------------
+
+
+@app.command(name="maps-search")
+def maps_search(
+    q: str = typer.Argument(..., help="Place search query"),
+    ll: str | None = typer.Option(None, "--ll", help="GPS coords '@lat,lng,zoom'"),
+    gl: str | None = typer.Option(None, "--gl", help="Country code (e.g. us, gb)"),
+    hl: str | None = typer.Option(None, "--hl", help="Language code (e.g. en, fr)"),
+    start: int | None = typer.Option(None, "--start", help="Pagination offset"),
+    fmt: str = FMT,
+    fields: str | None = FIELDS,
+) -> None:
+    """Maps place search."""
+    data = api_get(
+        "/v1/google/maps/search",
+        {"q": q, "ll": ll, "gl": gl, "hl": hl, "start": start},
+    )
+    render(data, fmt, fields)
+
+
+@app.command(name="maps-place")
+def maps_place(
+    place_id: str | None = typer.Option(None, "--place-id", help="Google place ID"),
+    data_id: str | None = typer.Option(None, "--data-id", help="Google Maps data ID"),
+    gl: str | None = typer.Option(None, "--gl", help="Country code"),
+    hl: str | None = typer.Option(None, "--hl", help="Language code"),
+    fmt: str = FMT,
+    fields: str | None = FIELDS,
+) -> None:
+    """Maps place detail. Pass either --place-id or --data-id."""
+    if not place_id and not data_id:
+        raise typer.BadParameter("Either --place-id or --data-id is required")
+    data = api_get(
+        "/v1/google/maps/place",
+        {"place_id": place_id, "data_id": data_id, "gl": gl, "hl": hl},
+    )
+    render(data, fmt, fields)
+
+
+@app.command(name="maps-reviews")
+def maps_reviews(
+    data_id: str = typer.Argument(..., help="Google Maps data ID"),
+    sort_by: str | None = typer.Option(
+        None,
+        "--sort-by",
+        help="qualityScore, newestFirst, ratingHigh, ratingLow",
+    ),
+    hl: str | None = typer.Option(None, "--hl", help="Language code"),
+    next_page_token: str | None = typer.Option(
+        None, "--next-page-token", help="Pagination token from previous response"
+    ),
+    results: int | None = typer.Option(None, "--results", "-n", help="Reviews per page (1-20)"),
+    fmt: str = FMT,
+    fields: str | None = FIELDS,
+) -> None:
+    """Maps reviews for a place."""
+    data = api_get(
+        "/v1/google/maps/reviews",
+        {
+            "data_id": data_id,
+            "sort_by": sort_by,
+            "hl": hl,
+            "next_page_token": next_page_token,
+            "results": results,
+        },
+    )
+    render(data, fmt, fields)
+
+
+@app.command(name="maps-photos")
+def maps_photos(
+    data_id: str = typer.Argument(..., help="Google Maps data ID"),
+    hl: str | None = typer.Option(None, "--hl", help="Language code"),
+    next_page_token: str | None = typer.Option(None, "--next-page-token", help="Pagination token"),
+    fmt: str = FMT,
+    fields: str | None = FIELDS,
+) -> None:
+    """Maps photos for a place."""
+    data = api_get(
+        "/v1/google/maps/photos",
+        {"data_id": data_id, "hl": hl, "next_page_token": next_page_token},
+    )
+    render(data, fmt, fields)
+
+
+@app.command(name="maps-posts")
+def maps_posts(
+    data_id: str = typer.Argument(..., help="Google Maps data ID"),
+    next_page_token: str | None = typer.Option(None, "--next-page-token", help="Pagination token"),
+    fmt: str = FMT,
+    fields: str | None = FIELDS,
+) -> None:
+    """Maps business posts for a place."""
+    data = api_get(
+        "/v1/google/maps/posts",
+        {"data_id": data_id, "next_page_token": next_page_token},
+    )
+    render(data, fmt, fields)
+
+
+# ---------------------------------------------------------------------------
+# News (3 endpoints)
+# ---------------------------------------------------------------------------
+
+
+@app.command()
+def news(
+    q: str = typer.Argument(..., help="News search query"),
+    hl: str | None = typer.Option(None, "--hl", help="Language code (e.g. en, fr)"),
+    gl: str | None = typer.Option(None, "--gl", help="Country code (e.g. US, GB)"),
+    max_results: int | None = typer.Option(None, "--max-results", "-n", help="Max articles"),
+    fmt: str = FMT,
+    fields: str | None = FIELDS,
+) -> None:
+    """News search."""
+    data = api_get(
+        "/v1/google/news/search",
+        {"q": q, "hl": hl, "gl": gl, "max_results": max_results},
+    )
+    render(data, fmt, fields)
+
+
+@app.command(name="news-topics")
+def news_topics(
+    topic: str = typer.Argument(
+        ...,
+        help="WORLD, BUSINESS, TECHNOLOGY, ENTERTAINMENT, SPORTS, SCIENCE, HEALTH",
+    ),
+    hl: str | None = typer.Option(None, "--hl", help="Language code"),
+    gl: str | None = typer.Option(None, "--gl", help="Country code"),
+    max_results: int | None = typer.Option(None, "--max-results", "-n"),
+    fmt: str = FMT,
+    fields: str | None = FIELDS,
+) -> None:
+    """News articles for a predefined topic."""
+    data = api_get(
+        "/v1/google/news/topics",
+        {"topic": topic, "hl": hl, "gl": gl, "max_results": max_results},
+    )
+    render(data, fmt, fields)
+
+
+@app.command(name="news-trending")
+def news_trending(
+    hl: str | None = typer.Option(None, "--hl", help="Language code"),
+    gl: str | None = typer.Option(None, "--gl", help="Country code"),
+    max_results: int | None = typer.Option(None, "--max-results", "-n"),
+    fmt: str = FMT,
+    fields: str | None = FIELDS,
+) -> None:
+    """Trending news stories."""
+    data = api_get(
+        "/v1/google/news/trending",
+        {"hl": hl, "gl": gl, "max_results": max_results},
+    )
+    render(data, fmt, fields)
+
+
+# ---------------------------------------------------------------------------
+# Hotels (2 endpoints)
+# ---------------------------------------------------------------------------
+
+
+@app.command()
+def hotels(
+    q: str = typer.Argument(..., help="Hotel search query or destination"),
+    check_in: str | None = typer.Option(None, "--check-in", help="Check-in date (YYYY-MM-DD)"),
+    check_out: str | None = typer.Option(None, "--check-out", help="Check-out date (YYYY-MM-DD)"),
+    adults: int | None = typer.Option(None, "--adults", "-a", help="Number of adult guests"),
+    currency: str | None = typer.Option(None, "--currency", help="Currency code (e.g. USD, EUR)"),
+    gl: str | None = typer.Option(None, "--gl", help="Country code"),
+    fmt: str = FMT,
+    fields: str | None = FIELDS,
+) -> None:
+    """Hotels search."""
+    data = api_get(
+        "/v1/google/hotels/search",
+        {
+            "q": q,
+            "check_in": check_in,
+            "check_out": check_out,
+            "adults": adults,
+            "currency": currency,
+            "gl": gl,
+        },
+    )
+    render(data, fmt, fields)
+
+
+@app.command(name="hotels-details")
+def hotels_details(
+    property_token: str = typer.Argument(..., help="Property token from search results"),
+    check_in: str = typer.Option(..., "--check-in", help="Check-in date (YYYY-MM-DD)"),
+    check_out: str = typer.Option(..., "--check-out", help="Check-out date (YYYY-MM-DD)"),
+    fmt: str = FMT,
+    fields: str | None = FIELDS,
+) -> None:
+    """Hotel property details."""
+    data = api_get(
+        "/v1/google/hotels/details",
+        {"property_token": property_token, "check_in": check_in, "check_out": check_out},
+    )
+    render(data, fmt, fields)
+
+
+# ---------------------------------------------------------------------------
+# Trends (4 endpoints)
+# ---------------------------------------------------------------------------
+
+
+@app.command()
+def trends(
+    q: str = typer.Argument(..., help="Up to 5 comma-separated terms"),
+    geo: str | None = typer.Option(None, "--geo", help="Location code (e.g. US, GB)"),
+    date: str | None = typer.Option(
+        None, "--date", help="Time range (e.g. 'now 7-d', 'today 12-m', 'all')"
+    ),
+    fmt: str = FMT,
+    fields: str | None = FIELDS,
+) -> None:
+    """Trends: interest over time."""
+    data = api_get("/v1/google/trends/interest", {"q": q, "geo": geo, "date": date})
+    render(data, fmt, fields)
+
+
+@app.command(name="trends-regions")
+def trends_regions(
+    q: str = typer.Argument(..., help="Search term"),
+    geo: str | None = typer.Option(None, "--geo", help="Geographic scope"),
+    fmt: str = FMT,
+    fields: str | None = FIELDS,
+) -> None:
+    """Trends: interest by region."""
+    data = api_get("/v1/google/trends/regions", {"q": q, "geo": geo})
+    render(data, fmt, fields)
+
+
+@app.command(name="trends-related")
+def trends_related(
+    q: str = typer.Argument(..., help="Search term"),
+    geo: str | None = typer.Option(None, "--geo", help="Geographic scope"),
+    fmt: str = FMT,
+    fields: str | None = FIELDS,
+) -> None:
+    """Trends: related topics and queries."""
+    data = api_get("/v1/google/trends/related", {"q": q, "geo": geo})
+    render(data, fmt, fields)
+
+
+@app.command(name="trends-trending")
+def trends_trending(
+    geo: str | None = typer.Option(None, "--geo", help="Region code (e.g. US)"),
+    fmt: str = FMT,
+    fields: str | None = FIELDS,
+) -> None:
+    """Trends: real-time trending searches (legacy single-param)."""
+    data = api_get("/v1/google/trends/trending", {"geo": geo})
+    render(data, fmt, fields)
+
+
+@app.command(name="trends-trending-now")
+def trends_trending_now(
+    geo: str | None = typer.Option(None, "--geo", help="Country code (e.g. US, LT, GB)"),
+    hours: int | None = typer.Option(None, "--hours", help="Look-back window: 4, 24, 48, 168"),
+    category: str | None = typer.Option(
+        None,
+        "--category",
+        help="all | business | entertainment | health | sci_tech | sports | top_stories",
+    ),
+    status: str | None = typer.Option(None, "--status", help="all | active"),
+    sort: str | None = typer.Option(
+        None,
+        "--sort",
+        help="relevance | search_volume | title | recency",
+    ),
+    hl: str | None = typer.Option(None, "--hl", help="Language code"),
+    fmt: str = FMT,
+    fields: str | None = FIELDS,
+) -> None:
+    """Trends: trending searches with the full Google UI filter set."""
+    data = api_get(
+        "/v1/google/trends/trending-now",
+        {
+            "geo": geo,
+            "hours": hours,
+            "category": category,
+            "status": status,
+            "sort": sort,
+            "hl": hl,
+        },
+    )
+    render(data, fmt, fields)
+
+
+@app.command(name="trends-search")
+def trends_search(
+    q: str = typer.Argument(..., help="Up to 5 comma-separated terms (or /m/... MID)"),
+    data_type: str = typer.Option(
+        "TIMESERIES",
+        "--data-type",
+        "-d",
+        help="TIMESERIES | GEO_MAP | GEO_MAP_0 | RELATED_TOPICS | RELATED_QUERIES",
+    ),
+    geo: str | None = typer.Option(None, "--geo", help="Country / region code"),
+    date: str | None = typer.Option(None, "--date", help="Time range"),
+    cat: int | None = typer.Option(None, "--cat", help="Category ID (0 = all)"),
+    gprop: str | None = typer.Option(None, "--gprop", help="images/news/froogle/youtube"),
+    region: str | None = typer.Option(None, "--region", help="COUNTRY/REGION/DMA/CITY"),
+    language: str | None = typer.Option(None, "--language", help="Alias for hl"),
+    tz: str | None = typer.Option(None, "--tz", help="Timezone offset (minutes)"),
+    fmt: str = FMT,
+    fields: str | None = FIELDS,
+) -> None:
+    """Trends: unified search dispatcher (data_type picks the response shape)."""
+    data = api_get(
+        "/v1/google/trends/search",
+        {
+            "q": q,
+            "data_type": data_type,
+            "geo": geo,
+            "date": date,
+            "cat": cat,
+            "gprop": gprop,
+            "region": region,
+            "language": language,
+            "tz": tz,
+        },
+    )
+    render(data, fmt, fields)
+
+
+@app.command(name="trends-autocomplete")
+def trends_autocomplete(
+    q: str = typer.Argument(..., help="Query prefix to resolve into Trends topics"),
+    hl: str | None = typer.Option(None, "--hl", help="Language code (e.g. en-US)"),
+    tz: str | None = typer.Option(None, "--tz", help="Timezone offset in minutes"),
+    fmt: str = FMT,
+    fields: str | None = FIELDS,
+) -> None:
+    """Trends: categorized Knowledge Graph topic entities (mid, type)."""
+    data = api_get("/v1/google/trends/autocomplete", {"q": q, "hl": hl, "tz": tz})
+    render(data, fmt, fields)
+
+
+# ---------------------------------------------------------------------------
+# Jobs
+# ---------------------------------------------------------------------------
+
+
+@app.command()
+def jobs(
+    q: str = typer.Argument(..., help="Job search query"),
+    mode: str = typer.Option(
+        "rpc",
+        "--mode",
+        help="rpc (default, Google Careers, ~1-2s) or serp (public Jobs aggregator)",
+    ),
+    location: str | None = typer.Option(None, "--location", "-l", help="Location (SERP mode)"),
+    gl: str | None = typer.Option(None, "--gl", help="Country code"),
+    country: str | None = typer.Option(None, "--country", help="Alias for --gl"),
+    hl: str | None = typer.Option(None, "--hl", help="Language code"),
+    language: str | None = typer.Option(None, "--language", help="Alias for --hl (e.g. en-US)"),
+    domain: str | None = typer.Option(
+        None, "--domain", help="Google domain (google.com, google.co.uk, …)"
+    ),
+    job_type: str | None = typer.Option(
+        None, "--job-type", help="FULLTIME / PARTTIME / CONTRACTOR / INTERN (SERP)"
+    ),
+    date_posted: str | None = typer.Option(
+        None, "--date-posted", help="today/3days/week/month (SERP)"
+    ),
+    ltype: str | None = typer.Option(
+        None, "--ltype", help="remote/hybrid/onsite/work_from_home (SERP)"
+    ),
+    chips: str | None = typer.Option(None, "--chips", help="Raw chip filter string (SERP)"),
+    uds: str | None = typer.Option(None, "--uds", help="Opaque filter token (SERP)"),
+    uule: str | None = typer.Option(None, "--uule", help="UULE-encoded location (SERP)"),
+    lrad: str | None = typer.Option(None, "--lrad", help="Search radius in miles (SERP)"),
+    next_page_token: str | None = typer.Option(None, "--next-page-token", help="Pagination cursor"),
+    fmt: str = FMT,
+    fields: str | None = FIELDS,
+) -> None:
+    """Google Jobs search (default: Google Careers RPC, ~1-2s)."""
+    data = api_get(
+        "/v1/google/jobs/search",
+        {
+            "q": q,
+            "mode": mode,
+            "location": location,
+            "gl": gl,
+            "country": country,
+            "hl": hl,
+            "language": language,
+            "domain": domain,
+            "job_type": job_type,
+            "date_posted": date_posted,
+            "ltype": ltype,
+            "chips": chips,
+            "uds": uds,
+            "uule": uule,
+            "lrad": lrad,
+            "next_page_token": next_page_token,
+        },
+    )
+    render(data, fmt, fields)
+
+
+# ---------------------------------------------------------------------------
+# Shopping (3 endpoints)
+# ---------------------------------------------------------------------------
+
+
+@app.command()
+def shopping(
+    q: str = typer.Argument(..., help="Product search query"),
+    gl: str | None = typer.Option(None, "--gl", help="Country code"),
+    hl: str | None = typer.Option(None, "--hl", help="Language code"),
+    domain: str | None = typer.Option(None, "--domain", help="Google domain"),
+    page: int | None = typer.Option(None, "--page", help="Zero-based page (each ≈ 60 tiles)"),
+    min_price: float | None = typer.Option(None, "--min-price", help="Minimum price filter"),
+    max_price: float | None = typer.Option(None, "--max-price", help="Maximum price filter"),
+    sort_by: str | None = typer.Option(
+        None, "--sort-by", help="price_low, price_high, rating, reviews"
+    ),
+    free_shipping: bool = typer.Option(False, "--free-shipping", help="Free-shipping filter"),
+    on_sale: bool = typer.Option(False, "--on-sale", help="On-sale filter"),
+    safe: str | None = typer.Option(None, "--safe", help="off / active"),
+    nfpr: int | None = typer.Option(None, "--nfpr", help="1 disables auto-correction"),
+    lr: str | None = typer.Option(None, "--lr", help="Language restrict (lang_en)"),
+    tbs: str | None = typer.Option(None, "--tbs", help="Raw tbs filter"),
+    shoprs: str | None = typer.Option(None, "--shoprs", help="Google internal helper token"),
+    fmt: str = FMT,
+    fields: str | None = FIELDS,
+) -> None:
+    """Google Shopping (udm=28) — product tiles with rich fields."""
+    data = api_get(
+        "/v1/google/shopping/search",
+        {
+            "q": q,
+            "gl": gl,
+            "hl": hl,
+            "domain": domain,
+            "page": page,
+            "min_price": min_price,
+            "max_price": max_price,
+            "sort_by": sort_by,
+            "free_shipping": "true" if free_shipping else None,
+            "on_sale": "true" if on_sale else None,
+            "safe": safe,
+            "nfpr": nfpr,
+            "lr": lr,
+            "tbs": tbs,
+            "shoprs": shoprs,
+        },
+    )
+    render(data, fmt, fields)
+
+
+@app.command()
+def shopping_offers(
+    barcode: str = typer.Argument(..., help="Product barcode — GTIN-8 / UPC-A / EAN-13 / GTIN-14"),
+    gl: str | None = typer.Option(None, "--gl", help="Country code (ISO 3166 alpha-2)"),
+    hl: str | None = typer.Option(None, "--hl", help="Language code"),
+    fmt: str = FMT,
+    fields: str | None = FIELDS,
+) -> None:
+    """Multi-seller Google Shopping prices for a product by barcode (GTIN/EAN/UPC)."""
+    data = api_get(
+        "/v1/google/shopping/offers",
+        {"barcode": barcode, "gl": gl, "hl": hl},
+    )
+    render(data, fmt, fields)
+
+
+# ---------------------------------------------------------------------------
+# Patents (2 endpoints)
+# ---------------------------------------------------------------------------
+
+
+@app.command()
+def patents(
+    q: str = typer.Argument(..., help="Patent search query (Boolean logic supported)"),
+    inventor: str | None = typer.Option(None, "--inventor", help="Filter by inventor name"),
+    assignee: str | None = typer.Option(None, "--assignee", help="Filter by assignee/company"),
+    country: str | None = typer.Option(None, "--country", help="Country code (US, EP, WO, …)"),
+    language: str | None = typer.Option(
+        None, "--language", help="ENGLISH, GERMAN, CHINESE, FRENCH, JAPANESE, KOREAN, SPANISH"
+    ),
+    status: str | None = typer.Option(None, "--status", help="GRANT or APPLICATION"),
+    patent_type: str | None = typer.Option(None, "--patent-type", help="PATENT or DESIGN"),
+    before: str | None = typer.Option(None, "--before", help="Before date YYYYMMDD"),
+    after: str | None = typer.Option(None, "--after", help="After date YYYYMMDD"),
+    sort: str | None = typer.Option(None, "--sort", help="'new' or 'old'"),
+    page: int | None = typer.Option(None, "--page", help="Page number (0-indexed)"),
+    num: int | None = typer.Option(None, "--num", "-n", help="Results per page (1-100)"),
+    fmt: str = FMT,
+    fields: str | None = FIELDS,
+) -> None:
+    """Patents search via the /xhr/query JSON RPC."""
+    data = api_get(
+        "/v1/google/patents/search",
+        {
+            "q": q,
+            "inventor": inventor,
+            "assignee": assignee,
+            "country": country,
+            "language": language,
+            "status": status,
+            "patent_type": patent_type,
+            "before": before,
+            "after": after,
+            "sort": sort,
+            "page": page,
+            "num": num,
+        },
+    )
+    render(data, fmt, fields)
+
+
+@app.command()
+def patent(
+    patent_id: str = typer.Argument(..., help="Publication number (e.g. US10000000B2)"),
+    fmt: str = FMT,
+    fields: str | None = FIELDS,
+) -> None:
+    """Rich patent detail via the /xhr/result endpoint.
+
+    Returns full abstract, every claim, complete description,
+    structured CPC classifications, split backward/forward citations,
+    non-patent citations, concepts, legal events, and figures.
+    """
+    data = api_get("/v1/google/patents/detail", {"patent_id": patent_id})
+    render(data, fmt, fields)
+
+
+# ---------------------------------------------------------------------------
+# Scholar
+# ---------------------------------------------------------------------------
+
+
+@app.command()
+def scholar(
+    q: str = typer.Argument(..., help="Scholarly search query"),
+    hl: str | None = typer.Option(None, "--hl", help="Language code"),
+    as_ylo: int | None = typer.Option(None, "--as-ylo", help="Year lower bound"),
+    as_yhi: int | None = typer.Option(None, "--as-yhi", help="Year upper bound"),
+    as_sdt: str | None = typer.Option(
+        None, "--as-sdt", help="'0' excludes patents, '7' includes them"
+    ),
+    page: int | None = typer.Option(None, "--page", help="Page number (0-based)"),
+    num: int | None = typer.Option(None, "--num", "-n", help="Results per page (1-20)"),
+    fmt: str = FMT,
+    fields: str | None = FIELDS,
+) -> None:
+    """Google Scholar search.
+
+    Each result carries its doc id + type badge, wrapped inline_links
+    (versions + cited_by + related), PDF resources, and structured
+    authors (with author_id for profiled authors — pipe into
+    `scholar-author`). Envelope includes `scholar_results` alias,
+    `related_searches`, and matched `profiles` cards.
+    """
+    data = api_get(
+        "/v1/google/scholar/search",
+        {
+            "q": q,
+            "hl": hl,
+            "as_ylo": as_ylo,
+            "as_yhi": as_yhi,
+            "as_sdt": as_sdt,
+            "page": page,
+            "num": num,
+        },
+    )
+    render(data, fmt, fields)
+
+
+@app.command(name="scholar-profiles")
+def scholar_profiles(
+    mauthors: str = typer.Argument(..., help="Author name query"),
+    hl: str | None = typer.Option(None, "--hl", help="Language code"),
+    after_author: str | None = typer.Option(
+        None, "--after-author", help="Next-page pagination token"
+    ),
+    before_author: str | None = typer.Option(
+        None, "--before-author", help="Previous-page pagination token"
+    ),
+    fmt: str = FMT,
+    fields: str | None = FIELDS,
+) -> None:
+    """Search Google Scholar for author profiles by name."""
+    data = api_get(
+        "/v1/google/scholar/profiles",
+        {
+            "mauthors": mauthors,
+            "hl": hl,
+            "after_author": after_author,
+            "before_author": before_author,
+        },
+    )
+    render(data, fmt, fields)
+
+
+@app.command(name="scholar-author")
+def scholar_author(
+    author_id: str = typer.Argument(..., help="Scholar user ID"),
+    hl: str | None = typer.Option(None, "--hl", help="Language code"),
+    cstart: int | None = typer.Option(None, "--cstart", help="Articles pagination offset"),
+    pagesize: int | None = typer.Option(None, "--pagesize", help="Articles per page"),
+    fmt: str = FMT,
+    fields: str | None = FIELDS,
+) -> None:
+    """Full Scholar author profile.
+
+    Returns structured interests ({title, link}), publications with
+    per-article citation_id + nested cited_by{value, link, citation_id}
+    blocks, lifetime + since-year stats (citations / h-index /
+    i10-index), and co-authors with their author_id.
+    """
+    data = api_get(
+        "/v1/google/scholar/author",
+        {
+            "author_id": author_id,
+            "hl": hl,
+            "cstart": cstart,
+            "pagesize": pagesize,
+        },
+    )
+    render(data, fmt, fields)
+
+
+@app.command(name="scholar-author-citation")
+def scholar_author_citation(
+    author_id: str = typer.Argument(..., help="Scholar user ID"),
+    hl: str | None = typer.Option(None, "--hl", help="Language code"),
+    fmt: str = FMT,
+    fields: str | None = FIELDS,
+) -> None:
+    """Citations-per-year chart for a Scholar author."""
+    data = api_get(
+        "/v1/google/scholar/author/citation",
+        {"author_id": author_id, "hl": hl},
+    )
+    render(data, fmt, fields)
+
+
+@app.command(name="scholar-cite")
+def scholar_cite(
+    q: str = typer.Argument(..., help="Cluster ID from a search result"),
+    hl: str | None = typer.Option(None, "--hl", help="Language code"),
+    fmt: str = FMT,
+    fields: str | None = FIELDS,
+) -> None:
+    """MLA / APA / Chicago / Harvard / Vancouver citation formats for a paper."""
+    data = api_get("/v1/google/scholar/cite", {"q": q, "hl": hl})
+    render(data, fmt, fields)
+
+
+# ---------------------------------------------------------------------------
+# Autocomplete
+# ---------------------------------------------------------------------------
+
+
+@app.command()
+def autocomplete(
+    q: str = typer.Argument(..., help="Query prefix to get suggestions for"),
+    hl: str | None = typer.Option(None, "--hl", help="Language code"),
+    gl: str | None = typer.Option(None, "--gl", help="Country code"),
+    fmt: str = FMT,
+    fields: str | None = FIELDS,
+) -> None:
+    """Google search autocomplete suggestions."""
+    data = api_get("/v1/google/autocomplete", {"q": q, "hl": hl, "gl": gl})
+    render(data, fmt, fields)
+
+
+# ---------------------------------------------------------------------------
+# Images
+# ---------------------------------------------------------------------------
+
+
+@app.command()
+def images(
+    q: str = typer.Argument(..., help="Image search query"),
+    gl: str | None = typer.Option(None, "--gl", help="Country code"),
+    hl: str | None = typer.Option(None, "--hl", help="Language code"),
+    page: int | None = typer.Option(None, "--page", help="Zero-based page (each page ≈ 100 tiles)"),
+    results: int | None = typer.Option(None, "--results", help="Max tiles to return (1-500 cap)"),
+    safe: str | None = typer.Option(None, "--safe", help="off, active"),
+    tbs: str | None = typer.Option(None, "--tbs", help="Raw tbs filter (e.g. qdr:d)"),
+    imgsz: str | None = typer.Option(None, "--imgsz", help="Image size: l, m, i, xXl, xxl, xxxl"),
+    imgcolor: str | None = typer.Option(None, "--imgcolor", help="Image color filter"),
+    imgtype: str | None = typer.Option(
+        None, "--imgtype", help="face, photo, clipart, lineart, animated"
+    ),
+    fmt: str = FMT,
+    fields: str | None = FIELDS,
+) -> None:
+    """Google Images search — title/source/link/thumbnail/original/dimensions/size."""
+    data = api_get(
+        "/v1/google/images/search",
+        {
+            "q": q,
+            "gl": gl,
+            "hl": hl,
+            "page": page,
+            "results": results,
+            "safe": safe,
+            "tbs": tbs,
+            "imgsz": imgsz,
+            "imgcolor": imgcolor,
+            "imgtype": imgtype,
+        },
+    )
+    render(data, fmt, fields)
+
+
+# ---------------------------------------------------------------------------
+# Videos
+# ---------------------------------------------------------------------------
+
+
+@app.command()
+def videos(
+    q: str = typer.Argument(..., help="Video search query"),
+    gl: str | None = typer.Option(None, "--gl", help="Country code"),
+    hl: str | None = typer.Option(None, "--hl", help="Language code"),
+    page: int | None = typer.Option(None, "--page", help="Zero-based page (each page ≈ 10 tiles)"),
+    domain: str | None = typer.Option(None, "--domain", help="Google domain"),
+    location: str | None = typer.Option(None, "--location", help="City-level geo-targeting"),
+    lr: str | None = typer.Option(None, "--lr", help="Language restrict (lang_en)"),
+    uule: str | None = typer.Option(None, "--uule", help="UULE-encoded location"),
+    nfpr: int | None = typer.Option(None, "--nfpr", help="1 disables auto-correction"),
+    safe: str | None = typer.Option(None, "--safe", help="off / active"),
+    tbs: str | None = typer.Option(None, "--tbs", help="Time/duration chip (qdr:w, dur:l)"),
+    fmt: str = FMT,
+    fields: str | None = FIELDS,
+) -> None:
+    """Google Videos search — title/duration/channel/date/video_id per tile."""
+    data = api_get(
+        "/v1/google/videos/search",
+        {
+            "q": q,
+            "gl": gl,
+            "hl": hl,
+            "page": page,
+            "domain": domain,
+            "location": location,
+            "lr": lr,
+            "uule": uule,
+            "nfpr": nfpr,
+            "safe": safe,
+            "tbs": tbs,
+        },
+    )
+    render(data, fmt, fields)
+
+
+# ---------------------------------------------------------------------------
+# Finance
+# ---------------------------------------------------------------------------
+
+
+@app.command()
+def finance(
+    q: str = typer.Argument(
+        ..., help="Ticker (optional exchange): AAPL, AAPL:NASDAQ, BTC-USD, EURUSD"
+    ),
+    hl: str | None = typer.Option(None, "--hl", help="Language code"),
+    gl: str | None = typer.Option(None, "--gl", help="Country code"),
+    fmt: str = FMT,
+    fields: str | None = FIELDS,
+) -> None:
+    """Google Finance quote — via mKsvE RPC."""
+    data = api_get("/v1/google/finance/quote", {"q": q, "hl": hl, "gl": gl})
+    render(data, fmt, fields)
+
+
+# ---------------------------------------------------------------------------
+# AI Mode
+# ---------------------------------------------------------------------------
+
+
+@app.command(name="ai-mode")
+def ai_mode(
+    q: str = typer.Argument(..., help="Search query for AI-generated answer"),
+    gl: str | None = typer.Option(None, "--gl", help="Country code"),
+    hl: str | None = typer.Option(None, "--hl", help="Language code"),
+    html: bool = typer.Option(
+        False,
+        "--html/--no-html",
+        help="Include the raw answer_html body (large; off by default)",
+    ),
+    fmt: str = FMT,
+    fields: str | None = FIELDS,
+) -> None:
+    """Google AI Mode (generative answer) search.
+
+    The response carries structured ``text_blocks`` (prose, headings,
+    comparison tables, lists), ``references``, a compact ``markdown``
+    rendering and — with ``--html`` — the raw ``answer_html`` body.
+    Use ``-o markdown`` to print the answer as readable Markdown.
+    """
+    data = api_get(
+        "/v1/google/ai-mode/search",
+        {"q": q, "gl": gl, "hl": hl, "include_html": str(html).lower()},
+    )
+    # For markdown output, prefer the server-rendered answer Markdown over
+    # the generic row-table renderer — it's the whole point of the format.
+    if fmt == "markdown" and isinstance(data, dict) and data.get("markdown"):
+        typer.echo(data["markdown"])
+        return
+    render(data, fmt, fields)
+
+
+# ---------------------------------------------------------------------------
+# Lens
+# ---------------------------------------------------------------------------
+
+
+@app.command()
+def lens(
+    url: str = typer.Argument(..., help="Public URL of the image to search visually"),
+    query: str | None = typer.Option(None, "--query", help="Text refinement (e.g. 'pizza')"),
+    country: str | None = typer.Option(None, "--country", help="ISO country code (alias for --gl)"),
+    language: str | None = typer.Option(None, "--language", help="Language code (alias for --hl)"),
+    gl: str | None = typer.Option(None, "--gl", help="Country code"),
+    hl: str | None = typer.Option(None, "--hl", help="Language code"),
+    product: bool = typer.Option(False, "--product", help="Bias towards shoppable matches"),
+    visual_matches: bool = typer.Option(
+        True, "--visual-matches/--no-visual-matches", help="Include visual-matches carousel"
+    ),
+    exact_matches: bool = typer.Option(
+        False, "--exact-matches", help="Restrict to exact matches only"
+    ),
+    fmt: str = FMT,
+    fields: str | None = FIELDS,
+) -> None:
+    """Google Lens visual image search.
+
+    Response carries `lens_results` (Scrapingdog parity) with
+    source/favicon/thumbnail/tag/in_stock per match, plus
+    `related_searches` chips. Legacy `results` alias kept for
+    backwards compat.
+    """
+    data = api_get(
+        "/v1/google/lens/search",
+        {
+            "url": url,
+            "query": query,
+            "country": country,
+            "language": language,
+            "gl": gl,
+            "hl": hl,
+            "product": "true" if product else None,
+            "visual_matches": "true" if visual_matches else "false",
+            "exact_matches": "true" if exact_matches else None,
+        },
+    )
+    render(data, fmt, fields)
+
+
+# ---------------------------------------------------------------------------
+# Products (immersive product detail)
+# ---------------------------------------------------------------------------
+
+
+@app.command(name="product-detail")
+def products_detail(
+    product_id: str = typer.Argument(
+        ..., help="Google Shopping gpcid (product_id from /shopping/search tiles)"
+    ),
+    q: str = typer.Option(
+        ...,
+        "--q",
+        "-q",
+        help="Original search query that surfaced the product (required)",
+    ),
+    gl: str | None = typer.Option(None, "--gl", help="Country code"),
+    hl: str | None = typer.Option(None, "--hl", help="Language code"),
+    catalog_id: str | None = typer.Option(
+        None, "--catalog-id", help="Optional catalogid from the Shopping tile"
+    ),
+    image_docid: str | None = typer.Option(None, "--image-docid", help="Optional imageDocid"),
+    headline_offer_docid: str | None = typer.Option(
+        None, "--headline-offer-docid", help="Optional headlineOfferDocid"
+    ),
+    mid: str | None = typer.Option(None, "--mid", help="Optional Knowledge-Graph mid"),
+    include_offers: bool = typer.Option(
+        False, "--include-offers", help="Also fetch merchant offers (+~1 s)"
+    ),
+    include_variants: bool = typer.Option(
+        False, "--include-variants", help="Also fetch size/colour variants (+~1 s)"
+    ),
+    fmt: str = FMT,
+    fields: str | None = FIELDS,
+) -> None:
+    """Google immersive product detail (via /async/oapv RPC)."""
+    data = api_get(
+        "/v1/google/products/detail",
+        {
+            "product_id": product_id,
+            "q": q,
+            "gl": gl,
+            "hl": hl,
+            "catalog_id": catalog_id,
+            "image_docid": image_docid,
+            "headline_offer_docid": headline_offer_docid,
+            "mid": mid,
+            "include_offers": "true" if include_offers else None,
+            "include_variants": "true" if include_variants else None,
+        },
+    )
+    render(data, fmt, fields)
+
+
+# Local Pack is no longer a standalone CLI command — the ``local_results``
+# array now ships inside ``sb-cli google search`` (main SERP response) with
+# the same rich per-place fields. For full place_id-keyed metadata use
+# ``sb-cli google maps-place``.
+
+
+# ---------------------------------------------------------------------------
+# Shorts (short-form vertical videos)
+# ---------------------------------------------------------------------------
+
+
+@app.command(name="shorts")
+def shorts_search(
+    q: str = typer.Argument(..., help="Search query"),
+    gl: str | None = typer.Option(None, "--gl", help="Country code"),
+    hl: str | None = typer.Option(None, "--hl", help="Language code"),
+    domain: str | None = typer.Option(None, "--domain", help="Google domain"),
+    num: int | None = typer.Option(None, "--num", "-n", help="Max tiles to return (1-60 cap)"),
+    start: int | None = typer.Option(None, "--start", help="Pagination offset"),
+    safe: str | None = typer.Option(None, "--safe", help="off / active"),
+    nfpr: int | None = typer.Option(None, "--nfpr", help="1 disables auto-correction"),
+    tbs: str | None = typer.Option(None, "--tbs", help="Raw tbs filter (e.g. qdr:d)"),
+    fmt: str = FMT,
+    fields: str | None = FIELDS,
+) -> None:
+    """Google Shorts — YouTube Shorts + TikTok + Reels."""
+    data = api_get(
+        "/v1/google/shorts/search",
+        {
+            "q": q,
+            "gl": gl,
+            "hl": hl,
+            "domain": domain,
+            "num": num,
+            "start": start,
+            "safe": safe,
+            "nfpr": nfpr,
+            "tbs": tbs,
+        },
+    )
+    render(data, fmt, fields)
+
+
+# ---------------------------------------------------------------------------
+# Flights
+# ---------------------------------------------------------------------------
+
+
+@app.command(name="flights")
+def flights_search(
+    departure_id: str = typer.Argument(..., help="Departure airport IATA (e.g. JFK)"),
+    arrival_id: str = typer.Argument(..., help="Arrival airport IATA (e.g. LHR)"),
+    outbound_date: str = typer.Argument(..., help="Outbound date (YYYY-MM-DD)"),
+    return_date: str | None = typer.Option(
+        None, "--return-date", help="Return date (YYYY-MM-DD, round-trip only)"
+    ),
+    trip_type: str | None = typer.Option(
+        None,
+        "--trip-type",
+        help="round_trip | one_way | multi_city",
+    ),
+    adults: int | None = typer.Option(None, "--adults", help="Adult passengers (1-9)"),
+    children: int | None = typer.Option(None, "--children", help="Children passengers (0-8)"),
+    travel_class: str | None = typer.Option(
+        None,
+        "--travel-class",
+        help="economy | premium_economy | business | first",
+    ),
+    currency: str | None = typer.Option(None, "--currency", help="ISO-4217 currency code"),
+    gl: str | None = typer.Option(None, "--gl", help="Country code"),
+    hl: str | None = typer.Option(None, "--hl", help="Language code"),
+    stops: str | None = typer.Option(None, "--stops", help="any | nonstop | one_stop | two_stops"),
+    max_price: int | None = typer.Option(None, "--max-price", help="Upper price filter"),
+    fmt: str = FMT,
+    fields: str | None = FIELDS,
+) -> None:
+    """Google Flights search — one-way, round-trip, or multi-city itineraries."""
+    data = api_get(
+        "/v1/google/flights/search",
+        {
+            "departure_id": departure_id,
+            "arrival_id": arrival_id,
+            "outbound_date": outbound_date,
+            "return_date": return_date,
+            "trip_type": trip_type,
+            "adults": adults,
+            "children": children,
+            "travel_class": travel_class,
+            "currency": currency,
+            "gl": gl,
+            "hl": hl,
+            "stops": stops,
+            "max_price": max_price,
+        },
+    )
+    render(data, fmt, fields)