Official Python client for the SerpShot API - Get real-time Google search results programmatically.

中文文档 | English

• ⚡ Lightning Fast - Get results in 1-2 seconds with optimized infrastructure
• 🌍 Global Coverage - Support for 200+ countries and regions
• 🔒 Reliable & Secure - 99.9% uptime SLA with enterprise-grade security
• 🚀 Developer Friendly - Sync/async support, full type hints, intuitive API
• 🔄 Batch Queries - Process up to 100 queries in a single request
• 🛡️ Smart Retries - Built-in retry logic handles network issues automatically

pip install serpshot

uv add serpshot

Free to use, just register to get your API key.

from serpshot import SerpShot

with SerpShot(api_key="your-api-key") as client:
    response = client.search("Python programming")
    for result in response.results:
        print(f"{result.title}: {result.link}")

Set SERPSHOT_API_KEY env var to skip passing the key explicitly:

with SerpShot() as client:
    response = client.search("Python programming")

Async:

import asyncio
from serpshot import AsyncSerpShot

async def main():
    async with AsyncSerpShot() as client:
        response = await client.search("Python programming")

asyncio.run(main())

SerpShot includes a built-in MCP server, letting AI assistants (Claude, Cursor, Windsurf, etc.) call Google Search directly as a tool.

pip install 'serpshot[mcp]'
# or
uv add 'serpshot[mcp]'

Add the following to your MCP client's config (Claude Code, Cursor, Windsurf, etc.):

{
  "mcpServers": {
    "serpshot": {
      "command": "python",
      "args": ["-m", "serpshot.mcp"],
      "env": { "SERPSHOT_API_KEY": "your_key_here" }
    }
  }
}

Or with uvx (no install required):

{
  "mcpServers": {
    "serpshot": {
      "command": "uvx",
      "args": ["--from", "serpshot[mcp]", "serpshot-mcp"],
      "env": { "SERPSHOT_API_KEY": "your_key_here" }
    }
  }
}

Use AsyncSerpShot for async usage — same interface, all methods are awaitable.

Returns SearchResponse, or list[SearchResponse] when query is a list.

Same parameters as search() except lr and location are not supported.

with SerpShot() as client:
    print(client.get_available_credits())

SearchResponse

SearchResult: title, link, snippet, position

ImageResult: title, link, thumbnail, source, source_link, width, height, position

with SerpShot() as client:
    responses = client.search(["Python", "JavaScript", "Rust"], num=10)
    for r in responses:
        print(f"{r.query}: {r.results[0].title}")

from serpshot import SerpShot, AuthenticationError, RateLimitError, InsufficientCreditsError, APIError, NetworkError

try:
    with SerpShot() as client:
        response = client.search("test query")
except AuthenticationError:
    print("Invalid API key")
except RateLimitError as e:
    print(f"Rate limited, retry after {e.retry_after}s")
except InsufficientCreditsError as e:
    print(f"Need {e.credits_required} credits")
except (APIError, NetworkError) as e:
    print(f"Error: {e}")

The SDK handles rate limiting automatically with exponential backoff. Track credit usage via response.credits_used.

git clone https://github.com/downdawn/serpshot-python.git
cd serpshot-python
uv sync --dev
pytest

MIT — see LICENSE.

• 📧 support@serpshot.com
• 📖 Documentation
• 🐛 Issues
• 🔑 Get API Key