Metadata-Version: 2.4
Name: asoradar
Version: 1.0.0
Summary: Official Python SDK for the ASORadar API — App Store & Google Play reviews, app metadata, rankings, and ASO intelligence.
Project-URL: Homepage, https://asoradar.com
Project-URL: Documentation, https://api.asoradar.com/docs
Project-URL: Repository, https://github.com/asoradar/asoradar-python
Project-URL: Changelog, https://github.com/asoradar/asoradar-python/blob/main/CHANGELOG.md
Author-email: ASORadar <support@asoradar.com>
License-Expression: MIT
License-File: LICENSE
Keywords: api,app-intelligence,app-reviews,app-store,aso,asoradar,client,google-play,reviews,sdk
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
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 :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Description-Content-Type: text/markdown

# asoradar

[![PyPI version](https://img.shields.io/pypi/v/asoradar.svg)](https://pypi.org/project/asoradar/)
[![Python versions](https://img.shields.io/pypi/pyversions/asoradar.svg)](https://pypi.org/project/asoradar/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Official Python SDK for the [ASORadar](https://asoradar.com) API — App Store & Google Play reviews, app metadata, version history, rankings, and ASO intelligence for developers and AI agents.

- **Sync and async** — `ASORadar` and `AsyncASORadar`, same surface.
- **Generated from the live OpenAPI spec** — 44 methods across App Store, Google Play, and Webhooks.
- **Typed** (PEP 561) with machine-usable errors — branch on `err.kind`, not status tables.
- One dependency: [`httpx`](https://www.python-httpx.org/). Python ≥ 3.10.

## Get 100 Free API Requests

[Sign up](https://asoradar.com/registration) and get **100 free ASORadar requests** — no credit card required.

## Install

```bash
pip install asoradar
# or: uv add asoradar / poetry add asoradar
```

## Quickstart

```python
from asoradar import ASORadar

client = ASORadar(access_key="YOUR_KEY")  # https://asoradar.com/tokens

# Recent App Store reviews for Instagram
reviews = client.app_store.reviews(app_id="389801252", country="us")

# Google Play app metadata
app = client.google_play.app("com.whatsapp", country="de")

# What changed in the last releases?
versions = client.app_store.version_history("389801252")

# One-call competitor brief: metadata + ratings + top complaints
brief = client.app_store.clone_brief("6446901002")
```

Async:

```python
from asoradar import AsyncASORadar

async with AsyncASORadar(access_key="YOUR_KEY") as client:
    reviews = await client.app_store.reviews(app_id="389801252")
```

## Usage

The client mirrors the API's three surfaces:

### `client.app_store` — App Store (`/a1/*`)

```python
client.app_store.reviews(app_id="389801252", rating=1, search="crash")
client.app_store.reviews_by_version(app_id="389801252", version="435.0.0")
client.app_store.reviews_sentiment("389801252")
client.app_store.app_by_name(name="Instagram")
client.app_store.app("389801252")
client.app_store.search(term="photo editor", country="us")
client.app_store.suggest(term="insta")
client.app_store.list(collection="topfreeapplications", num=50)
client.app_store.similar("389801252")
client.app_store.developer("389801255")
client.app_store.developer_portfolio_stats("389801255")
client.app_store.categories()
client.app_store.version_history("389801252")
client.app_store.version_history_diff("389801252")
client.app_store.metadata_diff("389801252")
client.app_store.privacy("389801252")
client.app_store.privacy_diff("389801252")
client.app_store.ratings("389801252")
client.app_store.clone_brief("389801252")
client.app_store.niche_scan(category="6008", country="us")
```

### `client.google_play` — Google Play (`/g1/*`)

Same shape with Google-specific extras:

```python
client.google_play.reviews(app_id="com.whatsapp", country="de")
client.google_play.permissions("com.whatsapp")
client.google_play.permissions_diff("com.whatsapp")
client.google_play.datasafety("com.whatsapp")
client.google_play.datasafety_diff("com.whatsapp")
# ...plus reviews/search/suggest/list/similar/developer/categories/
#    metadata_diff/clone_brief/niche_scan/reviews_sentiment, as on app_store
```

### `client.webhooks` — subscriptions (`/webhooks`)

Get notified on app changes, chart movement, or review keyword matches:

```python
sub = client.webhooks.create(
    kind="app_changes",
    target_url="https://example.com/hooks/asoradar",
    criteria={"store": "apple", "app_id": "389801252"},
)
# sub["secret"] is returned ONCE — store it to verify HMAC signatures.

client.webhooks.list()
client.webhooks.get(sub["id"])
client.webhooks.rotate_secret(sub["id"])
client.webhooks.delete(sub["id"])
```

### Freshness

Read endpoints are cache-first. Pass `fresh=True` to force a live refresh:

```python
client.app_store.reviews(app_id="389801252", fresh=True)
```

## Error handling

Every failure raises `ASORadarError` with a machine-usable `kind`:

```python
from asoradar import ASORadar, ASORadarError

try:
    client.app_store.reviews(app_id="389801252")
except ASORadarError as err:
    match err.kind:
        case "budget_exceeded":   # 402 — top up, do not retry
            ...
        case "rate_limited":      # 429 — wait err.retry_after_seconds
            ...
        case "auth":              # 401/403 — check your access key
            ...
        case "validation" | "not_found" | "server" | "timeout" | "network" | "api":
            ...
    print(err.status, err.kind, err.body)
```

## Options

```python
ASORadar(
    access_key="...",                       # required — https://asoradar.com/tokens
    base_url="https://api.asoradar.com",    # optional
    timeout=30.0,                           # optional, per request (seconds)
    transport=custom_httpx_transport,       # optional — tests, proxies
)
```

## Escape hatch

Endpoints newer than this SDK build are still reachable with full auth / error handling:

```python
client.request("GET", "/a1/brand-new-endpoint", query={"app_id": "..."})
```

## Related

- [`asoradar`](https://www.npmjs.com/package/asoradar) on npm — the JavaScript / TypeScript SDK.
- [`asoradar-mcp`](https://www.npmjs.com/package/asoradar-mcp) — MCP server that exposes this API as tools for AI agents (Claude, Cursor, Codex, …).
- [API docs](https://api.asoradar.com/docs)

## License

MIT — see [LICENSE](LICENSE).
