Metadata-Version: 2.4
Name: talordata-serp
Version: 0.1.1
Summary: A Python SDK for TalorData SERP API.
Author: TalorData SDK Contributors
Maintainer: TalorData SDK Contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/Talordata/talordata-serp-python
Project-URL: Documentation, https://docs.talordata.com/serp-api/send-your-first-request
Project-URL: Repository, https://github.com/Talordata/talordata-serp-python
Project-URL: Issues, https://github.com/Talordata/talordata-serp-python/issues
Keywords: talordata,serp,search,sdk,api
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
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: Operating System :: OS Independent
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=5.1; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Dynamic: license-file

# TalorData Python SDK

A lightweight Python SDK for the [TalorData SERP API](https://docs.talordata.com/serp-api), inspired by the developer experience of [`serpapi-python`](https://github.com/serpapi/serpapi-python).

Repository: [Talordata/talordata-serp-python](https://github.com/Talordata/talordata-serp-python)

## Install

```bash
pip install talordata-serp
```

## Quick Start

```python
import os

from talordata_serp import Client

client = Client(api_token=os.getenv("TALORDATA_API_TOKEN"))

results = client.search(
    engine="google",
    q="pizza",
)

print(results["search_metadata"]["status"])
print(results["search_information"]["query_displayed"])
```

You can also set the token once in your shell:

```bash
export TALORDATA_API_TOKEN=your_token
```

Then use the top-level helper:

```python
import talordata_serp

results = talordata_serp.search(q="pizza", engine="google")
print(results)
```

## Examples

Runnable examples are included in the `examples/` directory:

- `examples/basic_search.py`
- `examples/search_with_url.py`
- `examples/html_output.py`

Run one with:

```bash
python examples/basic_search.py
```

## API Design

- `Client(api_token=...)`: create a reusable client.
- `client.search(...)`: send a form-encoded `POST` request to `/request` and parse JSON automatically.
- `client.search_json(...)`: same as `search()`, but always returns a plain `dict`.
- `client.search_html(...)`: return raw HTML/text output.
- `talordata_serp.search(...)`: convenience helper for one-off requests.

## Example With URL

The official docs also show `url`-based requests. The SDK supports that directly:

```python
from talordata_serp import Client

client = Client(api_token="your_token")

results = client.search(
    url="https://www.google.com/search",
    q="pizza",
    json=1,
)

print(results.as_dict())
```

## Notes

- Auth uses the `Authorization: Bearer <token>` header.
- Requests are sent as `application/x-www-form-urlencoded`.
- Boolean params are normalized to `"1"` and `"0"` to match common form API expectations.

## Build And Publish

Build distributions locally:

```bash
python -m build
```

Check the generated artifacts:

```bash
python -m twine check dist/*
```

Upload to PyPI:

```bash
python -m twine upload dist/*
```
