Build on the AppWanderer App Store data API

Quickstart

The API is versioned under /api/v1 and returns JSON. Apply for a free key below, then send it as a bearer token:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://appwanderer.com/api/v1/record/biggest-app?limit=5

Machine-readable surface: /openapi.json (OpenAPI 3.1) · full endpoint reference and example responses: /data.

Authentication

Send your approved key on every request, as either header:

Authorization: Bearer YOUR_API_KEY
# or
X-API-Key: YOUR_API_KEY

Two tiers. The three single-resource endpoints — record/{slug}, studies/{slug} and app/{id} — are public and rate-limited per IP, so an agent can fetch one specific fact with no key. Every list/bulk endpoint (records, apps, publishers, categories, studies, almanac, movers, search) requires an approved key and returns a JSON 401 without one:

{
  "error": "authentication_required",
  "message": "A valid API key is required...",
  "hint": "Send your approved key as: Authorization: Bearer YOUR_KEY",
  "docs": "https://appwanderer.com/developers"
}

All errors are structured JSON with a machine-readable error code, a message, a resolution hint, and the matching HTTP status — 400 bad request, 401 missing/invalid key, 404 unknown resource, 429 rate limited.

Rate limits

Every response carries the rate-limit state so agents can self-throttle in real time. We emit both the RFC-draft and the X- headers:

RateLimit-Limit: 5000
RateLimit-Remaining: 4998
RateLimit-Reset: 2731            # seconds until the window resets
RateLimit-Policy: 5000;w=3600
X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Reset

The keyed budget is 5,000 requests/hour per key; the public single-resource tier is 240 requests/hour per IP (a valid key raises it to the keyed budget). Both use a rolling one-hour window. Exceeding it returns 429 with a Retry-After header (seconds to wait). Cache where you can — the underlying figures update on a schedule, not per second.

Versioning & deprecation policy

• Path-versioned. The current version is /api/v1. Additive changes (new fields, new endpoints) ship within v1 and will not break clients. Breaking changes ship under a new path, e.g. /api/v2.
• Deprecation signals. When an endpoint or version is deprecated we return the Deprecation header (RFC 8594) with the deprecation date, and a Sunset header with the retirement date, plus a Link to the successor. Deprecated surfaces keep working for at least 6 months after the Deprecation date.
• Changelog. Version changes are announced on this page and to every active key by email before the Sunset date.

Official CLI

A small, dependency-free command-line client wraps the API for scripting and agents. Download it and make it executable:

curl -fsSL https://appwanderer.com/appwanderer-cli.py -o appwanderer && chmod +x appwanderer
export APPWANDERER_API_KEY=YOUR_API_KEY
./appwanderer record biggest-app --limit 5
./appwanderer study app-store-pricing
./appwanderer search weather

Python 3.7+, standard library only. Source: /appwanderer-cli.py. Registry packages (PyPI appwanderer, npm, Homebrew) are planned.

Endpoints

Fifteen read-only endpoints. The three marked Public need no key (rate-limited per IP); the rest need an approved key. See the OpenAPI spec for typed parameters and response schemas, and /data for the annotated reference and example payloads.

Get an API key

Keys are free and issued per application while the API is in beta. Tell us what you would build:

Data is computed from public Apple App Store metadata. Free to cite and reproduce with attribution and a link back. Not affiliated with Apple.