Reserp Python SDK

The official Python SDK for Reserp, a Google Search API for developers and AI agents.

Retrieve structured Google Search results through one stable JSON schema. Start for free with no credit card required.

Website · API documentation · OpenAPI 3.1 · Pricing

Features

• Synchronous and asynchronous clients built on HTTPX.
• Typed responses that preserve the complete API response dictionary.
• One-based pagination plus support for authoritative pagination URLs.
• Configurable retries and timeouts.
• Automatic retries only when the API says the request is retryable and was not billed.

Installation

pip install reserp

Python 3.10 or later is required.

Quick start

import os

from reserp import Reserp

client = Reserp(api_key=os.environ["RESERP_API_KEY"])

response = client.search(
    query="best pizza in dubai",
    gl="ae",
    hl="en",
)

for result in response["results"]:
    print(result.get("text"), result.get("url"))

Create an API key in the Reserp dashboard. Keep API keys on your server; never embed one in browser or mobile code.

The SDK returns the API response as a normal Python dictionary. Result order, nested children, pagination, and billing fields remain intact.

Async client

import asyncio
import os

from reserp import AsyncReserp


async def main() -> None:
    async with AsyncReserp(api_key=os.environ["RESERP_API_KEY"]) as client:
        response = await client.search(
            query="semiconductor manufacturing",
            gl="us",
            hl="en",
        )
        print(response["results"])


asyncio.run(main())

The synchronous client is also a context manager:

with Reserp(api_key=os.environ["RESERP_API_KEY"]) as client:
    response = client.search(query="photonic computing")

Pagination

page is one-based, so you do not need to calculate Google's start offsets:

second_page = client.search(
    query="photonic computing",
    page=2,
)

You can also follow the authoritative pagination URL returned by the API:

first = client.search(query="photonic computing")
second = client.next_page(first)

Do not derive pagination from len(response["results"]). A response can contain organic listings, news, carousels, sitelinks, and nested result blocks.

Google parameters

Use params for additional Google parameters such as tbs and tbm:

news = client.search(
    query="semiconductor manufacturing",
    params={"tbm": "nws", "tbs": "qdr:w"},
)

For complete control, submit a full Google Search URL:

response = client.search_url(
    "https://www.google.com/search?q=semiconductor+manufacturing&gl=us&hl=en&tbs=qdr:w"
)

All Google URL parameters pass through unchanged except parameters documented as unsupported by Reserp. The num parameter is currently unsupported.

Errors and retries

API failures raise ReserpAPIError with the stable public error code and billing state:

from reserp import ReserpAPIError

try:
    response = client.search(query="photonic computing")
except ReserpAPIError as error:
    print(error.status, error.code, error.retryable, error.billed)

The SDK retries retryable API responses up to two times by default, respecting Retry-After for rate limits. It never automatically retries a response whose billed field is true. Network failures are not automatically retried because the client cannot know whether the original request reached the API.

Configure retries and per-attempt timeouts globally or per request:

client = Reserp(
    api_key=os.environ["RESERP_API_KEY"],
    max_retries=1,
    timeout=20.0,
)

response = client.search(
    query="photonic computing",
    max_retries=0,
    timeout=10.0,
)

Set timeout=0 to disable the SDK timeout.

API reference

• Reserp API documentation
• OpenAPI 3.1 document
• Pricing

License

MIT