Metadata-Version: 2.4
Name: pangolinfo-niche-data
Version: 0.2.0
Summary: Pangolinfo Niche Data API - Amazon category tree, niche filtering, Best Sellers and New Releases.
Project-URL: Homepage, https://www.pangolinfo.com/amazon-niche-data-api/
Project-URL: Documentation, https://docs.pangolinfo.com
Project-URL: Repository, https://github.com/Pangolin-spg/pangolinfo-niche-data
Project-URL: Changelog, https://github.com/Pangolin-spg/pangolinfo-niche-data/releases
Project-URL: Issues, https://github.com/Pangolin-spg/pangolinfo-niche-data/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,bestsellers,category,niche,pangolinfo,product-research,sdk
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; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: respx; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Description-Content-Type: text/markdown

# pangolinfo-niche-data

Pangolinfo Niche Data API — Amazon category tree, niche filtering, Best Sellers and New Releases.

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

## Installation

```
pip install pangolinfo-niche-data
```

## Quick start

```python
from pangolinfo_niche_data import NicheDataClient

client = NicheDataClient(token="your_bearer_token")

# Browse the category tree
children = client.get_category_children(parent_browse_node_id_path="2619526011")

# Search categories by keyword (English and Chinese)
hits = client.search_categories("coffee")

# Resolve full paths for a list of category IDs
paths = client.batch_category_paths(["2619526011", "172282"])

# Filter categories by marketplace + metrics
result = client.filter_categories(
    marketplace_id="ATVPDKIKX0DER",
    time_range="T360",
    sample_scope="CATEGORY",
    unit_sold_sum_min=1000,
    sort_field="unitSoldSum",
    sort_order="desc",
    size=10,
)

# Discover blue-ocean niches
niches = client.filter_niches(
    marketplace_id="ATVPDKIKX0DER",
    search_volume_t90_min=5000,
    minimum_price=15,
    maximum_price=50,
    size=10,
)

client.close()
```

The client is also usable as a context manager:

```python
with NicheDataClient(token="your_bearer_token") as client:
    print(client.search_categories("coffee"))
```

## Authentication

All requests are authenticated with a **Bearer token** sent in the
`Authorization` header. Get a free API key at
[tool.pangolinfo.com](https://tool.pangolinfo.com).

```python
client = NicheDataClient(token="your_bearer_token")
```

## Base URL

```
http://scrapeapi.pangolinfo.com/api/v1
```

Every endpoint is reached via `POST`. Responses follow the shape:

```json
{ "code": 0, "message": "ok", "data": { ... } }
```

A non-zero `code` is raised as an `APIError`.

## Methods

Python methods use idiomatic `snake_case` parameter names. They are converted
to the API's `camelCase` JSON keys automatically (e.g.
`parent_browse_node_id_path` → `parentBrowseNodeIdPath`). `None` values are
omitted from the request body.

### `get_category_children(...)`

`POST /amzscope/categories/children` — get the child categories of a parent
browse node.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `parent_browse_node_id_path` | `str` | no | Parent node path, e.g. `"2619526011"` or `"2619526011/18116197011"` |
| `page` | `int` | no | Page number |
| `size` | `int` | no | Items per page |

```python
client.get_category_children(parent_browse_node_id_path="2619526011/18116197011", page=1, size=20)
```

### `search_categories(keyword, ...)`

`POST /amzscope/categories/search` — full-text search across category names
(matches English and Chinese).

| Parameter | Type | Required | Description |
|---|---|---|---|
| `keyword` | `str` | yes | Search keywords |
| `page` | `int` | no | Page number |
| `size` | `int` | no | Items per page |

```python
client.search_categories("coffee", page=1, size=20)
```

### `batch_category_paths(category_ids)`

`POST /amzscope/categories/paths` — batch-query the full path for a list of
category IDs.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `category_ids` | `List[str]` | yes | Category ID list, e.g. `["2619526011", "172282"]` |

```python
client.batch_category_paths(["2619526011", "172282"])
```

### `filter_categories(marketplace_id, time_range, sample_scope, **kwargs)`

`POST /amzscope/categories/filter` — filter categories by multi-dimensional
metrics.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `marketplace_id` | `str` | yes | Marketplace identifier |
| `time_range` | `str` | yes | Time range |
| `sample_scope` | `str` | yes | Sample scope |
| `category_id` | `str` | no | Restrict to a category |
| `page` | `int` | no | Page number |
| `size` | `int` | no | Items per page (max 10) |
| `sort_field` | `str` | no | Field to sort by |
| `sort_order` | `str` | no | `"asc"` / `"desc"` |

Many additional filters are accepted as keyword arguments and forwarded with
their key converted to `camelCase`:

- **Range filters** (`*Min` / `*Max` suffixes): `unit_sold_sum`,
  `glance_views_sum`, `search_volume_sum`, `net_shipped_gms_sum`,
  `buy_box_price_avg`, `search_to_purchase_ratio`, `return_ratio`,
  `asin_count`, `offers_per_asin`, `new_asin_count`, `new_brand_count`,
  `avg_ad_spend_per_click` — e.g. `unit_sold_sum_min=1000`,
  `buy_box_price_avg_max=50`.
- **Tier / level filters**: `buy_box_price_tiers`,
  `search_to_purchase_ratio_levels`, `return_ratio_levels`,
  `asin_count_levels`, `offers_per_asin_levels`, `new_asin_count_levels`,
  `new_brand_count_levels`, `avg_ad_spend_per_click_levels`.
- **Trend filters**: `{metric}_trend_directions`, `{metric}_volatility_levels`,
  `{metric}_change_rate_buckets`, `{metric}_last_vs_self_avg_buckets`.
- **Quantile filters**: `{metric}_quantile_buckets`.

```python
client.filter_categories(
    marketplace_id="ATVPDKIKX0DER",
    time_range="T360",
    sample_scope="CATEGORY",
    unit_sold_sum_min=1000,
    buy_box_price_tiers=["0-10", "10-25"],
    sort_field="unitSoldSum",
    sort_order="desc",
    size=10,
)
```

### `filter_niches(marketplace_id, **kwargs)`

`POST /amzscope/niches/filter` — discover blue-ocean niches by competition and
demand metrics.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `marketplace_id` | `str` | yes | Marketplace identifier |
| `niche_id` | `str` | no | Niche identifier |
| `niche_title` | `str` | no | Niche title |
| `page` | `int` | no | Page number |
| `size` | `int` | no | Items per page (max 10) |
| `sort_field` | `str` | no | Field to sort by |
| `sort_order` | `str` | no | `"asc"` / `"desc"` |

Many additional range filters are accepted as keyword arguments (`*Min` /
`*Max` suffixes): `search_volume_t90`, `search_volume_t360`,
`search_volume_growth_t90`, `search_volume_growth_t180`,
`search_volume_growth_t360`, `minimum_units_sold_t360`,
`maximum_units_sold_t360`, `minimum_average_units_sold_t360`,
`maximum_average_units_sold_t360`, `minimum_price`, `maximum_price`,
`return_rate_t360`, `product_count`, `sponsored_products_percentage_t360`,
`prime_products_percentage_t360`, `top5_products_click_share_t360`,
`top20_products_click_share_t360`, `top5_brands_click_share`,
`top20_brands_click_share`, `avg_oos_rate_t360`, `brand_count`,
`selling_partner_count_t360`, `avg_brand_age_t360`,
`avg_selling_partner_age`, `avg_best_seller_rank`, `avg_product_price`,
`avg_review_count`, `avg_review_rating`, `avg_detail_page_quality`,
`successful_launches_t90`, `successful_launches_t180`,
`successful_launches_t360`, `new_products_launched_t180`,
`new_products_launched_t360`.

```python
client.filter_niches(
    marketplace_id="ATVPDKIKX0DER",
    search_volume_t90_min=5000,
    minimum_price=15,
    maximum_price=50,
    sort_field="searchVolumeT90",
    sort_order="desc",
    size=10,
)
```

## Error handling

All errors raised by the client derive from `NicheDataError`.

| Exception | Raised when |
|---|---|
| `NicheDataError` | Base exception (e.g. invalid client arguments) |
| `AuthenticationError` | The API responds with HTTP 401 |
| `APIError` | The API returns a non-zero `code`, an HTTP error, or malformed JSON |
| `TimeoutError` | The request times out |

```python
from pangolinfo_niche_data import NicheDataClient, APIError, AuthenticationError

try:
    with NicheDataClient(token="...") as client:
        result = client.search_categories("coffee")
except AuthenticationError:
    print("Invalid token")
except APIError as exc:
    print(f"API error {exc.code}: {exc.message}")
```

## Links

- **Product page:** [pangolinfo.com/amazon-niche-data-api](https://www.pangolinfo.com/amazon-niche-data-api/)
- **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-niche-data](https://github.com/Pangolin-spg/pangolinfo-niche-data)

## License

MIT — © PANGOLIN INFO TECH PTE. LTD.
