Metadata-Version: 2.4
Name: chocodata
Version: 0.1.0
Summary: Official Python SDK for the Chocodata web scraping API. Typed methods for Amazon, Walmart, eBay, Bing, TikTok, YouTube and Instagram, plus a generic client for all 499 endpoints.
Project-URL: Homepage, https://chocodata.com
Project-URL: Repository, https://github.com/ChocoData-com/chocodata-python
Project-URL: Issues, https://github.com/ChocoData-com/chocodata-python/issues
Author: Chocodata
License: MIT
License-File: LICENSE
Keywords: amazon-scraper,bing-scraper,chocodata,ebay-scraper,scraper,scraping-api,tiktok-scraper,walmart-scraper,web-scraping
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# chocodata

Official Python SDK for the [Chocodata](https://chocodata.com) web scraping API.

Typed methods for the endpoints most people start with, a generic client for the rest of the catalog, retry with backoff, and a structured error type. No dependencies: standard library only.

```bash
pip install chocodata
```

Python 3.9+.

## Quick start

```python
from chocodata import Chocodata

chocodata = Chocodata("asa_live_YOUR_KEY")

product = chocodata.amazon.product(query="0143127748")
print(product["title"], product["price"])
```

Get a key at [chocodata.com](https://chocodata.com). The free tier is 1,000 requests, one time, no card.

## Authentication

The key travels as a query parameter, which the SDK handles for you. There is no header auth: sending `Authorization: Bearer` or `X-API-Key` returns 401.

## Endpoints

Every method below was smoke-tested against production before release.

```python
# Ecommerce
chocodata.amazon.product(query="0143127748")               # ASIN or ISBN
chocodata.amazon.product(query="0143127748", domain="de")  # prices localise to the marketplace
chocodata.amazon.search(query="laptop")

chocodata.walmart.product(url="https://www.walmart.com/ip/19075520026")
chocodata.walmart.search(query="laptop")

chocodata.ebay.product(url="https://www.ebay.com/itm/298520538688")
chocodata.ebay.search(query="laptop")

# Search engines  (note: Bing takes `q`, not `query`)
chocodata.bing.search(q="coffee", count=10)
chocodata.bing.images(q="red panda", count=20, safe_search="strict")

# Social / video
chocodata.tiktok.profile(username="rotana")
chocodata.youtube.video(video_id="dQw4w9WgXcQ")
chocodata.instagram.profile(username="nasa")
```

**Parameters are not uniform across targets, and the SDK does not pretend otherwise.** `amazon.product` takes `query`; `walmart.product` takes `url` or `id` and rejects `query`; `bing.search` takes `q`.

## Everything else

The catalog has 499 endpoints. Anything without a dedicated method is reachable through the same code path:

```python
chocodata.scrape("bing", "videos", {"q": "coffee"})
chocodata.scrape("reddit", "post", {"post_id": "627akk", "subreddit": "askscience"})
```

## Errors

```python
from chocodata import Chocodata, ChocodataError

try:
    chocodata.tiktok.profile(username="a-handle-that-is-gone")
except ChocodataError as e:
    print(e.status)      # 404
    print(e.code)        # 'item_not_found'
    print(e.retryable)   # False
    print(e.request_id)  # for support
```

| Status | Code | Meaning |
|---|---|---|
| 400 | `invalid_params` | A required parameter is missing or the wrong type. The body names it. |
| 401 | `INVALID_API_KEY` | Key missing, unrecognised, or revoked. |
| 402 | `INSUFFICIENT_CREDITS` | Balance exhausted. |
| 404 | `item_not_found` | The item genuinely does not exist. Not retryable. |
| 429 | `RATE_LIMITED` | Over 120 requests / 60s, or over your plan's concurrency. |
| 502 | `extraction_failed` / `target_unreachable` | Retryable; the SDK already retried. |

**You are only charged on a 2xx.** Errors cost no credits.

## Retries

Retryable failures (429, 5xx, network) are retried with exponential backoff plus jitter. The SDK trusts the server's `retryable` flag, so a 404 is never retried.

```python
chocodata = Chocodata(
    "asa_live_YOUR_KEY",
    max_retries=3,   # default 2
    timeout=120.0,   # default 90.0
    debug=True,      # log every call
)
```

## Concurrency

`AsyncChocodata` runs each request in a worker thread via `asyncio.to_thread`, so it composes with `asyncio.gather`. It is a concurrency wrapper, not a native async HTTP stack.

```python
import asyncio
from chocodata import AsyncChocodata

async def main():
    client = AsyncChocodata("asa_live_YOUR_KEY")
    asins = ["0143127748", "B09B8V1LZ3", "B0BSHF7WHW"]
    results = await asyncio.gather(*[
        client.ascrape("amazon", "product", {"query": a}) for a in asins
    ])
    for r in results:
        print(r["asin"], r.get("title"))

asyncio.run(main())
```

Requests are limited to 120 per key per 60 seconds, plus a per-plan concurrency ceiling.

## License

MIT
