Metadata-Version: 2.4
Name: reserp
Version: 0.1.0
Summary: Official Python SDK for the Reserp Google Search API
Project-URL: Homepage, https://reserp.ai
Project-URL: Documentation, https://reserp.ai/docs
Project-URL: Repository, https://github.com/reserp-ai/reserp-python
Project-URL: Issues, https://github.com/reserp-ai/reserp-python/issues
Project-URL: Changelog, https://github.com/reserp-ai/reserp-python/blob/main/CHANGELOG.md
Author-email: Reserp <no-reply@reserp.ai>
License-Expression: MIT
License-File: LICENSE
Keywords: api-client,google-search,google-search-api,python,reserp,sdk,search-api,serp,serp-api
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx<1,>=0.27
Provides-Extra: dev
Requires-Dist: build<2,>=1.2; extra == 'dev'
Requires-Dist: mypy<2,>=1.13; extra == 'dev'
Requires-Dist: pytest<10,>=8.3; extra == 'dev'
Requires-Dist: ruff<1,>=0.8; extra == 'dev'
Requires-Dist: twine<7,>=5.1; extra == 'dev'
Description-Content-Type: text/markdown

<p align="center">
  <a href="https://reserp.ai">
    <img src="https://reserp.ai/icon-512.png" alt="Reserp Google Search API" width="112" height="112">
  </a>
</p>

# Reserp Python SDK

[![PyPI version](https://img.shields.io/pypi/v/reserp.svg)](https://pypi.org/project/reserp/)
[![Python versions](https://img.shields.io/pypi/pyversions/reserp.svg)](https://pypi.org/project/reserp/)
[![CI](https://github.com/reserp-ai/reserp-python/actions/workflows/ci.yml/badge.svg)](https://github.com/reserp-ai/reserp-python/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

The official Python SDK for [Reserp](https://reserp.ai), 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](https://reserp.ai) · [API documentation](https://reserp.ai/docs) · [OpenAPI 3.1](https://reserp.ai/openapi.json) · [Pricing](https://reserp.ai/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

```bash
pip install reserp
```

Python 3.10 or later is required.

## Quick start

```python
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](https://reserp.ai/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

```python
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:

```python
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:

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

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

```python
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`:

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

For complete control, submit a full Google Search URL:

```python
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:

```python
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:

```python
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](https://reserp.ai/docs)
- [OpenAPI 3.1 document](https://reserp.ai/openapi.json)
- [Pricing](https://reserp.ai/pricing)

## License

MIT
