Metadata-Version: 2.4
Name: pangolinfo-amazon-scraper
Version: 0.1.0
Summary: Pangolinfo Amazon Scraper - Official Python SDK for structured e-commerce data from Amazon, Walmart, and more.
Project-URL: Homepage, https://www.pangolinfo.com
Project-URL: Documentation, https://docs.pangolinfo.com
Project-URL: Repository, https://github.com/Pangolin-spg/pangolinfo-amazon-scraper
Project-URL: Changelog, https://github.com/Pangolin-spg/pangolinfo-amazon-scraper/releases
Project-URL: Issues, https://github.com/Pangolin-spg/pangolinfo-amazon-scraper/issues
Project-URL: Free API Key, https://tool.pangolinfo.com
Author-email: "PANGOLIN INFO TECH PTE. LTD." <support@pangolinfo.com>
License-Expression: MIT
License-File: LICENSE
Keywords: amazon,api,ecommerce,pangolinfo,product-data,scraper,scraping,sdk,serp,walmart
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
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: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Requires-Dist: httpx>=0.24
Provides-Extra: dev
Requires-Dist: build>=1.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: respx>=0.20; extra == 'dev'
Requires-Dist: twine>=4.0; extra == 'dev'
Description-Content-Type: text/markdown

# pangolinfo-amazon-scraper

Official Python SDK for the **Pangolinfo Scrape API** — structured e-commerce data from Amazon, Walmart, eBay, Shopify and more, delivered as JSON, clean HTML or LLM-friendly Markdown.

> Built and maintained by [PANGOLIN INFO TECH PTE. LTD.](https://www.pangolinfo.com)

[![PyPI version](https://img.shields.io/pypi/v/pangolinfo-amazon-scraper.svg)](https://pypi.org/project/pangolinfo-amazon-scraper/)
[![Python versions](https://img.shields.io/pypi/pyversions/pangolinfo-amazon-scraper.svg)](https://pypi.org/project/pangolinfo-amazon-scraper/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/Pangolin-spg/pangolinfo-amazon-scraper/blob/main/LICENSE)

## Why this SDK

The Pangolinfo Scrape API dynamically adapts to page-structure changes so you never maintain fragile selectors. You get:

- **Structured JSON** for product details, keyword search, rankings, reviews and more
- **Raw HTML** and **Markdown** output for AI/LLM pipelines
- **99.9% uptime** with built-in anti-bot handling and residential IP rotation
- **Sync + async** interfaces from a single package
- Coverage of **Amazon, Walmart, eBay, Shopify, Shopee**

## Installation

```bash
pip install pangolinfo-amazon-scraper
```

## Quick start

### 1. Get a free API key

Sign up at [tool.pangolinfo.com](https://tool.pangolinfo.com) — open-source contributors get **200 free API calls** and full parser templates. See the [free-tier details](https://docs.pangolinfo.com).

### 2. Use the SDK

```python
from pangolinfo_amazon_scraper import PangolinfoClient

# Authenticate with a token from your dashboard...
client = PangolinfoClient(token="your_bearer_token")

# ...or with email/password (the SDK logs in for you)
# client = PangolinfoClient(email="you@example.com", password="secret")

# Fetch an Amazon product by ASIN
result = client.amazon.get_product("B0DYTF8L2W", zipcode="10041")
print(result.json_data)
# {"asin": "B0DYTF8L2W", "title": "...", "price": ..., "rating": ..., ...}
```

### Async usage

```python
import asyncio
from pangolinfo_amazon_scraper import AsyncPangolinfoClient

async def main():
    async with AsyncPangolinfoClient(token="your_bearer_token") as client:
        result = await client.amazon.get_product("B0DYTF8L2W")
        print(result.json_data)

asyncio.run(main())
```

## Features

### Multiple output formats

```python
# Structured JSON (default)
result = client.scrape(
    url="https://www.amazon.com/dp/B0DYTF8L2W",
    parser_name="amzProductDetail",
    formats=["json"],
)

# LLM-friendly Markdown
md = client.scrape(url="...", parser_name="amzProductDetail", formats=["markdown"])
print(md.markdown)

# Raw HTML
html = client.scrape(url="...", parser_name="amzProductDetail", formats=["rawHtml"])
print(html.html)

# All three at once
result = client.scrape(url="...", parser_name="amzProductDetail", formats=["json", "rawHtml", "markdown"])
```

### Platform helpers

```python
# Amazon
client.amazon.get_product("B0DYTF8L2W", zipcode="10041")
client.amazon.search("wireless earbuds", domain="www.amazon.com")

# Walmart
client.walmart.get_product("123456789")
client.walmart.search("blender")
```

### Generic scrape (any platform / parser)

```python
from pangolinfo_amazon_scraper import PARSERS

# Use a known parser key
result = client.scrape(
    url="https://www.amazon.com/dp/B0DYTF8L2W",
    parser_name=PARSERS["amazon_product_detail"],
    formats=["json"],
    zipcode="10041",
)

# Or pass the raw parser name the API accepts
result = client.scrape(
    url="https://www.ebay.com/itm/...",
    parser_name="ebayProductDetail",
    formats=["json"],
)
```

### Async callbacks for high-throughput jobs

```python
result = client.scrape(
    url="https://www.amazon.com/dp/B0DYTF8L2W",
    parser_name="amzProductDetail",
    formats=["json"],
    callback_url="https://your-server.com/webhook",  # async mode
)
```

## API reference

### `PangolinfoClient`

| Method | Description |
|---|---|
| `PangolinfoClient(token=...)` | Create a client with an existing bearer token |
| `PangolinfoClient(email=..., password=...)` | Create a client that logs in lazily |
| `client.scrape(url, parser_name, formats, zipcode, ...)` | Core scrape call |
| `client.amazon.get_product(asin, zipcode)` | Amazon product detail |
| `client.amazon.search(keyword)` | Amazon keyword search |
| `client.walmart.get_product(product_id)` | Walmart product detail |
| `client.walmart.search(keyword)` | Walmart keyword search |
| `client.login()` | Force (re)authentication |
| `client.close()` | Close the HTTP connection pool |

### `AsyncPangolinfoClient`

Async mirror of `PangolinfoClient` — every method is a coroutine and supports
`async with`.

### `ScrapeResult`

| Attribute | Type | Description |
|---|---|---|
| `result.json_data` | `dict` / `list` / `None` | Parsed JSON payload |
| `result.html` | `str` / `None` | Raw HTML (when `rawHtml` requested) |
| `result.markdown` | `str` / `None` | Markdown (when `markdown` requested) |
| `result.success` | `bool` | `True` when `code == 0` |
| `result.code` | `int` | API response code |
| `result.raw` | `dict` | Full unmodified response |

### Exceptions

| Exception | When |
|---|---|
| `PangolinfoError` | Base class for all SDK errors |
| `AuthenticationError` | Login failed or credentials missing |
| `APIError` | API returned non-zero `code` |
| `TimeoutError` | Request exceeded the timeout |
| `ValidationError` | Invalid arguments supplied |

## Supported parsers

| Key | Parser name | Platform |
|---|---|---|
| `amazon_product_detail` | `amzProductDetail` | Amazon |
| `amazon_keyword_search` | `amzKeywordSearch` | Amazon |
| `amazon_best_sellers` | `amzBestSellers` | Amazon |
| `amazon_reviews` | `amzReview` | Amazon |
| `walmart_product_detail` | `wmtProductDetail` | Walmart |
| `walmart_keyword_search` | `wmtKeywordSearch` | Walmart |

> `amzProductDetail` is confirmed in the official example. Other parsers
> follow the Pangolinfo [documentation naming](https://docs.pangolinfo.com) —
> pass any raw parser name to `client.scrape()` if yours isn't listed.

## Links

- **Homepage:** [pangolinfo.com](https://www.pangolinfo.com)
- **Documentation:** [docs.pangolinfo.com](https://docs.pangolinfo.com)
- **Get a free API key:** [tool.pangolinfo.com](https://tool.pangolinfo.com)
- **Source code:** [github.com/Pangolin-spg/pangolinfo-amazon-scraper](https://github.com/Pangolin-spg/pangolinfo-amazon-scraper)
- **Support:** support@pangolinfo.com

## Development

```bash
# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Build distributions
python -m build

# Upload to PyPI
twine upload dist/*
```

## License

[MIT](LICENSE) — © PANGOLIN INFO TECH PTE. LTD.
