Google Lens Pro (google-lens-pro)

Google Lens Pro is a high-performance Python package and CLI for reverse-engineered Google Lens visual search, Google Shopping scraping, reverse image lookup, and multimodal commercial intelligence 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 Pro? (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.
• Category-Agnostic AI Match Evaluation: Bundled candidate evaluations classify matches into exact_match, similar, reference, or unrelated with human-readable rationale (relevance_reason) and automatically identify the target product (target_product) across luxury goods, electronics, fashion, and collectibles.
• 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:
  • lens login command captures Google account credentials once to run 100% headless visual searches indefinitely.
  • Automatic session loading from ~/.config/google-lens-pro/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: GoogleLens, LensScraper, and AsyncGoogleLens with native concurrent destination enrichment (enrich_async) and fusion (fuse_async).
• Command-Line Interface: Fast lens and google-lens CLI for quick visual searches, shopping, 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 & Multi-Store Pricing: Discover where products, sneakers, clothing, or electronics are sold online and compare prices across 50+ merchants (StockX, GOAT, Flight Club, eBay, Walmart).
• ⚡ 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-pro

(Provides the lens and google-lens CLI commands)

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. 🌐 Multi-Store Pricing Fusion (--enrich): Concurrently scrapes Google Shopping SERPs and fuses 50+ live merchant offers (StockX, GOAT, Flight Club, eBay, Walmart, Poshmark) with Google Lens visual discovery.
2. 🔎 Direct Store Product URL Crawler: Runs a page-pooled stealth browser (patchright/Chromium) over merchant search results to resolve exact, direct product SKU URLs (e.g. poshmark.com/listing/..., lyst.com/shoes/...), with title-similarity validation so a search never resolves to the wrong product. Offers with no verifiable store link fall back to a Google Shopping product page or search rather than a dead URL.
3. 📦 Schema.org & Next.js Hydration Extraction: Parses LD-JSON (Product, Offer), Next.js hydration payload (__NEXT_DATA__), and OpenGraph tags directly from merchant product pages.
4. 🎯 Page Intent Classification (page_type): Automatically categorizes destination URLs into product, article, social (Instagram, TikTok, Pinterest), portfolio, marketplace, or uncategorized so you can instantly filter out non-shoppable links.
5. 📊 Stock & Availability Detection (stock_status): Identifies real-time merchant stock levels (in_stock, out_of_stock, preorder) directly from product feeds.
6. 🏷️ Item Condition & SKU Extraction (condition, sku): Captures condition (new, used, refurbished) and product identifiers (GTIN, UPC, SKU) for resale pricing and catalog matching.
7. 🔗 Canonical URL Unwrapping: Decodes opaque google.com/url?q=... redirects into direct, clean merchant product links, stripping UTM parameters, ad click-trackers, and Chrome text fragments.
8. 💰 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.
9. 🏪 Merchant Categorization: Labels sellers as Official Brand stores (e.g. Nike, Apple), Major Marketplaces (Amazon, eBay, Walmart), or Resellers (StockX, GOAT, Chrono24).
10. 📁 Clean JSON-First Data Pipelines: Direct --export-json (or --export) flag for developer-grade hierarchical data without sparse, inconsistent CSV columns or null noise.
11. ⚡ Multi-Device Activations: Authorize up to 3 machines simultaneously via CLI (lens pro activate <key>) or purchase directly (lens buy pro) with self-service license management in the Polar customer portal.
12. 🎯 Category-Agnostic Semantic Match Evaluation (relevance): Separates exact product matches from accessories, lookalikes, and unrelated SERP noise (exact_match, similar, reference, unrelated) with transparent, human-readable rationale (relevance_reason).
13. 🏷️ Target Product Identification (target_product): Automatically detects the canonical item name and silhouette from visual cues and metadata, anchoring all price comparison and match score analytics.

Why Google Lens Pro?

Agent Skill (google-lens-pro)

google-lens-pro 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:

lens install-skill

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

Additional Installation Options:

• Global User Install: lens install-skill --global (installs to ~/.agents/skills/google-lens-pro/)
• Claude Code: lens install-skill --claude (installs to .claude/skills/google-lens-pro/, or combine with --global)
• Custom Directory: lens install-skill --dest ./my-skills/
• Force Overwrite: 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
lens login

# Or authenticate and automatically write credentials to a local .env file
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-pro/session.json (and written to .env if --env is passed).

Check session status anytime:

lens status

To log out:

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
   lens export-session --env
   
   # Or print the base64 string to copy into a cloud secret manager
   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-pro will automatically load any LENS_* variables defined in it.

🐍 Python SDK & Developer Integration

1. Synchronous Search (Visual Matches + OCR)

from google_lens_pro import GoogleLens, 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_pro import GoogleLens, 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 (AsyncIO + Concurrent Pro Enrichment)

import asyncio
from google_lens_pro import AsyncGoogleLens, AsyncLensScraper


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

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

    # Pro commerce intelligence (async destination enrichment & relevance)
    if result.commerce:
        print(f"\nTarget Product: {result.commerce.summary.target_product}")
        for match in result.commerce.items:
            rel = f"[{match.relevance.value}]" if match.relevance else ""
            print(
                f"- {match.title} | {match.price.raw if match.price else 'N/A'} {rel} -> {match.direct_url}"
            )


asyncio.run(main())

Configuration Options

Configure LensConfig for custom proxies, timeouts, or profiles:

from google_lens_pro 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 & Gemini Configuration
# -------------------------------------------------------------
# Configure Google AI Studio key (optional, for --studio packshots & deep attributes)
google-lens setup-ai --key "<your-gemini-api-key>"

# Configure billing tier for exact cost accounting (unknown, free, or paid)
google-lens setup-ai --tier paid       # Or: --tier free / --tier unknown

# Check AI Studio key and tier status
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 (target_product, min/max/average price across verified listings, currency, best_deal), items (all matches classified by page_type, match_score, and semantic relevance), products (filtered commercial listings), is_preview.
• EnrichedCommerceMatch (Pro): title, direct_url (unwrapped clean canonical URL), price (raw, amount, currency), merchant_name, merchant_category, thumbnail, match_score (0-100% token overlap), relevance (exact_match, similar, reference, unrelated), relevance_reason, page_type, brand, sku, condition, stock_status, in_stock.
• 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, billing_tier.

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 concurrent destination page enrichment, Schema.org LD-JSON and Next.js hydration extraction, page intent classification, stock status detection, direct canonical URL unwrapping, multi-currency price arbitrage, best-deal ranking, and automated JSON export pipelines.