Google Lens Scraper (google-lens-scraper)

Google Lens Scraper is a high-performance Python package and CLI for reverse-engineered Google Lens visual search, reverse image lookup, and OCR text extraction using Patchright stealth browser automation and native Chromium Protobuf protocols. Fast, developer-friendly, and self-hosted alternative to expensive cloud proxy APIs like SerpApi and TinEye. No API keys required. Optional Pro Tier available with complete features.

Table of Contents

• Why Google Lens Scraper? (Comparison)
• Common Use Cases
• Core Features
• Installation
• Quick Start
  • 1. Command Line (CLI)
  • 2. AI Coding Agents
• Google Lens Pro (Commercial Intelligence Suite)
• Python SDK Integration
  • Visual Search (Sync)
  • Fast-Path OCR (Zero Browser, Sub-Second)
  • Asynchronous Search (AsyncIO)
• Agent Skill Integration
• Authentication & Headless Deployments
• CLI Reference & Commands
• Configuration Options
• Data Models
• Frequently Asked Questions (FAQ)
• License & Terms

Features

• Tri-Modal Search Inputs: Query using public image URLs, local image files (.png, .jpg, .webp), raw image bytes, or existing Google Lens search result URLs (udm=26 / udm=44).
• All-By-Default Execution: One command (google-lens search <image>) retrieves visual matches, normalizes prices, unwraps canonical links, and extracts deep attributes.
• Dual-Engine Architecture:
  • Fast-Path Protobuf Engine: Uses Chromium's native internal endpoint (v1/crupload) for sub-second, zero-browser image uploads, session token generation (gsessionid / lsessionid), and full-text OCR.
  • Stealth Browser Engine: Powered by Patchright (undetected Chromium driver) for complete visual matches, thumbnails, publisher URLs, prices, and Knowledge Graph entities.
• Zero-Friction Agent Fallback: Works natively without an API key! If GEMINI_API_KEY is not present, the bundled Agent Skill directs host LLMs to analyze attributes in-context.
• Nano Banana Pro 8K Studio Generation: Pass --studio to synthesize isolated commercial catalog packshots to disk.
• Permanent Session Authentication:
  • google-lens login command captures Google account credentials once to run 100% headless visual searches indefinitely.
  • Automatic session loading from ~/.config/google-lens-scraper/session.json.
  • Production & CI/CD support via LENS_STORAGE_STATE_JSON or LENS_COOKIES environment variables.
• Anti-Bot Defenses:
  • Coherent Client Hints (sec-ch-ua) matching internal browser fingerprints.
  • Injected session cookies (SOCS, CONSENT, SID, HSID).
  • Persistent browser profiles (user_data_dir) and Chrome DevTools Protocol (cdp_url).
  • HTTP & SOCKS5 proxy support.
• Dual Synchronous & Asynchronous APIs: LensScraper and AsyncLensScraper.
• Command-Line Interface: google-lens CLI for quick searches, OCR, and session management.
• Agent Skill Integration: Built-in open-standard Agent Skill conforming to agentskills.io for VS Code Copilot, Claude Code, Cursor, Codex, and Gemini CLI.

Common Use Cases

• 🔍 Reverse Image Search: Find original image sources, higher-resolution copies, and related web pages from any image URL or local image path.
• 🛍️ E-Commerce & Product Matching: Discover where products, sneakers, clothing, or furniture are sold online and compare prices across merchants.
• ⚡ Sub-Second AI OCR: Extract dense text, receipts, handwritten notes, and serial numbers with Google's state-of-the-art vision models in milliseconds—without launching a browser.
• 🏛️ Knowledge Graph Recognition: Automatically identify landmarks, plants, dog breeds, artwork, and historical figures from photos.
• 🤖 AI Coding Agent Vision Tool: Equip your AI assistant (Claude Code, Cursor, Copilot, Codex, Gemini CLI) to browse the visual web natively.

Installation

pip install google-lens-scraper

(Provides the google-lens CLI command)

Install the stealth Chromium browser binary:

patchright install chromium

🚀 Quick Start

Get results in seconds via the CLI or your AI coding assistant:

1. Command Line (CLI)

# Authenticate once with Google (opens browser to capture session)
google-lens login

# Search any image URL or local photo (retrieves matches, prices, Knowledge Graph)
google-lens "path/to/sneakers.jpg"

# Or extract text with sub-second OCR (fast-path Protobuf, zero browser required):
google-lens "receipt.png" --ocr-only

2. AI Coding Agent (Cursor, Claude Code, Copilot, Codex, Gemini CLI)

# Install the open Agent Skill directly into your workspace
google-lens install-skill

Prompt your AI agent in plain English:

"Find where to buy the jacket in this image: https://example.com/jacket.jpg"
"Find high-quality visual matches and the original source for wallpaper.png"

What Pro Adds:

1. 🔗 Canonical URL Unwrapping: Decodes opaque google.com/url?q=... redirects into direct, clean merchant product links, stripping UTM parameters and tracking noise.
2. 💰 Normalized Pricing & Best Deals: Auto-extracts numeric prices and currencies (USD, EUR, GBP, INR, etc.), computing market average/range and highlighting the lowest-priced verified seller.
3. 🏷️ Merchant Categorization: Labels domains as Official Brand stores (e.g. Nike, Apple), Major Marketplaces (Amazon, eBay, Walmart), or Resellers (StockX, GOAT, Chrono24).
4. 📁 Clean JSON Data Pipelines: Direct --export-json (or --export) flag for developer-grade hierarchical data without sparse, inconsistent CSV columns.
5. ⚡ Multi-Device Activations: Authorize up to 3 machines simultaneously via CLI (google-lens pro activate <key>) or purchase directly (google-lens buy pro) with self-service license management in the Polar customer portal.

Why Google Lens Scraper?

Agent Skill (google-lens)

google-lens-scraper includes a pre-packaged, specification-compliant Agent Skill that gives AI coding agents (VS Code GitHub Copilot, Claude Code, Cursor, Codex, Gemini CLI, Hermes, etc.) native visual search and OCR tools.

Installing the Skill

To install the skill into your current workspace:

google-lens install-skill

This installs the skill to .agents/skills/google-lens/.

Additional Installation Options:

• Global User Install: google-lens install-skill --global (installs to ~/.agents/skills/google-lens/)
• Claude Code: google-lens install-skill --claude (installs to .claude/skills/google-lens/, or combine with --global)
• Custom Directory: google-lens install-skill --dest ./my-skills/
• Force Overwrite: google-lens install-skill --force

Example Prompts for Agents

Once installed, your AI agent automatically activates the skill when you ask visual tasks:

• "Find where to buy the jacket in this image: https://example.com/jacket.jpg"
• "Find high-quality visual matches and the original source for wallpaper.png"
• "Extract all text from receipt.png using Google Lens OCR"
• "Identify what landmark or building is shown in photo.jpg"
• "What is the estimated price of the watch in this picture?"

Authentication (One-Time Setup)

Google Lens requires session trust to display full visual matches on modern search layouts. You can authenticate once and run all subsequent searches headlessly:

CLI Login

# Authenticate and save session locally
google-lens login

# Or authenticate and automatically write credentials to a local .env file
google-lens login --env

A browser window will open. Sign into your Google account (or dismiss any prompts) and press [Enter] in your terminal. Your session will be saved securely to ~/.config/google-lens-scraper/session.json (and written to .env if --env is passed).

Check session status anytime:

google-lens status

To log out:

google-lens logout

Production / Docker / CI Deployments

In containerized, cloud, or headless CI environments where an interactive browser cannot be opened, provide the session state via environment variables or a .env file:

1. Export your authenticated session from your local machine:

   # Automatically create or update your local .env file
   google-lens export-session --env
   
   # Or print the base64 string to copy into a cloud secret manager
   google-lens export-session --base64
   

   What is this? This dumps your authenticated session (Playwright browser storage state containing your Google session cookies) as a single-line base64 string. Using base64 prevents quote-escaping and multiline syntax issues when pasting into .env files, Docker -e flags, Kubernetes secrets, or cloud secret managers.

2. Set the environment variable in your production runtime or .env file:

   # Base64-encoded or raw JSON storage state (ideal for secret managers / Docker)
   export LENS_STORAGE_STATE_JSON="eyJjb29raWVzIjog..."
   
   # Or point to a mounted secret file on disk
   export LENS_STORAGE_STATE_PATH="/secrets/google-lens-session.json"
   
   # Or provide cookie headers directly
   export LENS_COOKIES="SID=...; SOCS=..."
   

Note: If a .env file is present in the working directory, google-lens-scraper will automatically load any LENS_* variables defined in it.

🐍 Python SDK & Developer Integration

1. Synchronous Search (Visual Matches + OCR)

from google_lens_scraper import LensScraper

# Initialize scraper (automatically uses saved session if available)
scraper = LensScraper(headless=True)

# Search local file or image URL
result = scraper.search("path/to/product.jpg")
# result = scraper.search("https://example.com/sneakers.jpg")

# Access detected objects & OCR
print("Identified:", result.knowledge_graph.title if result.knowledge_graph else "N/A")
print("OCR Text:", result.ocr_text)

# Access product attributes (deduced natively without API keys)
if result.analysis and result.analysis.attributes:
    attrs = result.analysis.attributes
    print(f"Brand: {attrs.brand} | Model: {attrs.model_or_name} | Category: {attrs.category}")

# Access Pro commerce intelligence (best deal & clean URLs)
if result.commerce and result.commerce.best_deal:
    deal = result.commerce.best_deal
    print(
        f"Best Deal: {deal.price.amount} {deal.price.currency} at {deal.merchant_name} -> {deal.direct_url}"
    )

# Iterate through visual matches
print(f"\nFound {len(result.visual_matches)} visual matches:")
for match in result.visual_matches:
    print(f"- [{match.source}] {match.title}")
    print(f"  URL: {match.link}")
    if match.price:
        print(f"  Price: {match.price}")
    print(f"  Thumbnail: {match.thumbnail}\n")

2. Fast-Path OCR & Object Detection Only (Sub-Second, No Browser)

If you only need OCR text and bounding boxes without launching a browser:

from google_lens_scraper import LensScraper

scraper = LensScraper()
result = scraper.detect("path/to/receipt.jpg")

print("OCR Text:", result.ocr_text)
for obj in result.detected_objects:
    print("Object:", obj.id, obj.bounding_box)

3. Asynchronous Search

import asyncio
from google_lens_scraper import AsyncLensScraper


async def main():
    scraper = AsyncLensScraper(headless=True)
    result = await scraper.search("https://example.com/watch.jpg")

    for match in result.visual_matches:
        print(f"[{match.source}] {match.title} -> {match.link}")


asyncio.run(main())

Configuration Options

Configure LensConfig for custom proxies, timeouts, or profiles:

from google_lens_scraper import LensConfig, LensScraper

config = LensConfig(
    headless=True,
    timeout=30.0,
    # Residential proxy
    proxy="http://user:pass@proxy.example.com:8080",
    # Custom cookies
    cookies="SID=...; HSID=...",
    # Custom persistent Chrome user data directory
    user_data_dir="~/.config/google-chrome/Default",
    # Or connect to an existing Chrome browser via CDP
    cdp_url="http://localhost:9222",
    # Language and Region
    language="en",
    region="US",
)

scraper = LensScraper(config=config)

CLI Usage

The package includes the google-lens command-line utility:

# -------------------------------------------------------------
# 1. Google Session Authentication
# -------------------------------------------------------------
# Authenticate interactively once to bypass bot detection
google-lens login

# Check authentication status
google-lens status

# Export session state for headless servers / CI (.env or base64)
google-lens export-session --env
google-lens export-session --base64

# Log out / clear saved credentials
google-lens logout

# -------------------------------------------------------------
# 2. Visual Search & Intelligence (Core Search & OCR)
# -------------------------------------------------------------
# Search an image (runs visual search, price normalization & native attribute extraction)
google-lens image.jpg

# Search public image URL
google-lens "https://example.com/item.jpg"

# Sub-second OCR and object detection only (zero browser overhead)
google-lens document.png --ocr-only

# Output raw JSON to stdout (great for jq / piping)
google-lens image.jpg --json-output | jq .visual_matches

# Use a proxy
google-lens image.jpg --proxy "http://user:pass@proxy:8080"

# -------------------------------------------------------------
# 3. Pro Licensing & Plans (Optional Commercial Tier)
# -------------------------------------------------------------
# Purchase Pro license (opens Polar.sh checkout in browser)
google-lens buy pro                    # Opens Lifetime checkout (default)
google-lens buy --plan annual          # Or: --plan monthly

# Activate license in terminal (direct key or interactive prompt)
google-lens pro activate "<your-polar-license-key>"
google-lens pro activate               # Interactive prompt

# Check license status & authorized devices
google-lens pro status

# Deactivate license on this machine
google-lens pro deactivate

# Export enriched product & arbitrage deals to clean JSON (Pro feature)
google-lens image.jpg --export-json deals.json

# -------------------------------------------------------------
# 4. AI Studio (Optional 8K Packshots)
# -------------------------------------------------------------
# Optional: Configure Google AI Studio key (only needed for 8K --studio packshots)
google-lens setup-ai --key "<your-gemini-api-key>"
google-lens setup-ai --status

# Generate 8K commercial studio packshot via Nano Banana Pro
google-lens image.jpg --studio --studio-output ./packshot.png

Tip: In zsh and other POSIX shells, always enclose URLs containing query parameters (&, ?) in quotation marks (e.g. google-lens "https://...") to prevent shell parse errors.

Data Models

Results are encapsulated in the LensSearchResult Pydantic model:

class LensSearchResult(BaseModel):
    query_url: Optional[str]  # Executed Google Lens URL
    search_session_id: Optional[str]  # Google gsessionid token
    server_session_id: Optional[str]  # Google lsessionid token
    ocr_text: Optional[str]  # Full OCR text extracted
    detected_objects: List[DetectedObject]  # Detected bounding boxes & labels
    visual_matches: List[VisualMatch]  # Web shopping and visual match items
    knowledge_graph: Optional[KnowledgeGraph]  # Encyclopedic Knowledge Graph card
    commerce: Optional[CommerceIntelligence]  # Pro: Clean URLs, normalized prices, best deal
    analysis: Optional[VisualAnalysis]  # Native & multimodal product attributes
    studio_asset: Optional[GeneratedStudioAsset]  # Synthesized 8K commercial packshot
    cost: Optional[Dict[str, Any]]  # Real-time token usage and USD financial cost

    def to_dict(self) -> dict: ...
    def to_json(self) -> str: ...

Core Sub-Models:

• VisualMatch: title, link, thumbnail, source, price.
• CommerceIntelligence (Pro): summary (min/max/average price across listings), items (clean canonical URLs, merchant classification), best_deal (lowest-price verified seller).
• VisualAnalysis: summary, attributes (brand, model_or_name, category, color, materials, condition_assessment, authenticity_markers, confidence_score), resale_recommendation, tags.
• GeneratedStudioAsset: image_path (saved 8K file), prompt_used, aspect_ratio, model.
• Cost Telemetry: tokens.total, tokens.prompt, tokens.output, cost_usd.total.

Frequently Asked Questions (FAQ)

License & Commercial Terms

• Community Core & Agent Skill: Open source under the MIT License. Free for unlimited local visual search, reverse image lookups, sub-second Protobuf OCR, Knowledge Graph card extraction, and native zero-key attribute deductions.
• Pro Commercial Intelligence Suite (license.py, commerce.py): Proprietary, see LICENSE. Requires an active license key from Polar.sh for direct canonical URL unwrapping, normalized multi-currency price arbitrage, best-deal ranking, and automated CSV export pipelines.