asoradar

Official Python SDK for the ASORadar 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. Python ≥ 3.10.

Get 100 Free API Requests

Sign up and get 100 free ASORadar requests — no credit card required.

Install

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

Quickstart

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:

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/*)

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:

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:

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:

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

Error handling

Every failure raises ASORadarError with a machine-usable kind:

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

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:

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

Related

• asoradar on npm — the JavaScript / TypeScript SDK.
• asoradar-mcp — MCP server that exposes this API as tools for AI agents (Claude, Cursor, Codex, …).
• API docs

License

MIT — see LICENSE.