# App Store Reviews API — unified Apple App Store + Google Play reviews, ratings, top charts and ASO discovery

> unified Apple + Play reviews for one or more apps
> ReefAPI engine `app-store` · 7 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/app-store/v1/<action>` with a JSON body.
- **Auth:** header `x-api-key: <YOUR_REEFAPI_KEY>` — create one free (1,000 credits, no card): https://reefapi.com/signup
- **Response (every call):** `{ ok: boolean, data: ..., meta: { record_count, credits, ... }, error: { code, message } }` — branch on `ok`. Failed or blocked calls are free.
- **One key + one shared credit pool** across every ReefAPI API. Per-call credits are listed on each endpoint below.
- **Use it from an AI agent (MCP):** connect `https://api.reefapi.com/mcp` (remote streamable-http, `Authorization: Bearer <key>`) and your assistant can call these actions directly.

## Endpoints

### POST /app-store/v1/reviews — 1 credit
unified Apple + Play reviews for one or more apps

**Parameters:**
- `apps` (array, optional) — Apps to fetch reviews for: an array of objects with any of {name, apple/appleAppId, play/googlePlayPackage}, or plain name strings. Alternative to the single-app id params.
- `appleAppId` (string, optional) — Apple numeric app id (single-app shortcut).
- `googlePlayPackage` (string, optional) — Google Play package name (single-app shortcut).
- `appName` (string, optional) — App name to search per store when ids aren't supplied.
- `stores` (array, optional) — Which app stores to query (array). Aliases like ios/app_store and play/android/google are accepted; unknown names are ignored. Omit to query both. [one of: apple, google_play]
- `countries` (array, optional) — Storefront country codes (2-letter, lowercase), e.g. ['us','gb']. Use 'all' for the Apple aggregate set. Omit for the default.
- `maxReviews` (integer, optional, default 1000) — Maximum reviews to collect per app/store (clamped to 100000).

**Returns:** kind='reviews', results[] (store, profile{name,app_id,rating,...}, reviews[] {rating, title, text, date, reviewer, version}, scraped_count, status), summary (success_rate_pct, total_reviews, …)

**Example request body:**
```json
{
  "apps": [
    {
      "name": "WhatsApp",
      "apple": "310633997"
    }
  ],
  "stores": [
    "apple"
  ],
  "countries": [
    "us"
  ],
  "maxReviews": 100
}
```

### POST /app-store/v1/search — 1 credit
ranked app search results

**Parameters:**
- `query` (string, required) — App search keyword (name or term).
- `stores` (array, optional) — Which app stores to query (array). Aliases like ios/app_store and play/android/google are accepted; unknown names are ignored. Omit to query both. [one of: apple, google_play]
- `country` (string, optional, default "us") — Storefront country code (2-letter, lowercase), e.g. 'us'.
- `count` (integer, optional, default 50) — Maximum number of apps to return.

**Returns:** kind='discovery', results[]{store,query,apps[],count}, summary

### POST /app-store/v1/topCharts — 1 credit
ranked chart/category apps

**Parameters:**
- `chart` (enum, optional, default "topFree") — Which chart to pull. Apple supports top/new free/paid/grossing; Google Play maps to its equivalent top charts. [one of: topFree, topPaid, topGrossing, newFree, newPaid, new]
- `category` (string, optional) — Genre/category filter: an Apple genre id (e.g. 6014=Games) or a Play category (e.g. GAME, SOCIAL). See listCategories for valid values.
- `device` (enum, optional, default "iphone") — Apple-only: chart device variant (iPad has fewer chart feeds). [one of: iphone, ipad]
- `stores` (array, optional) — Which app stores to query (array). Aliases like ios/app_store and play/android/google are accepted; unknown names are ignored. Omit to query both. [one of: apple, google_play]
- `country` (string, optional, default "us") — Storefront country code (2-letter, lowercase), e.g. 'us'.
- `count` (integer, optional, default 50) — Maximum number of apps to return.

**Returns:** kind='discovery', results[]{store,chart,category,apps[],count,requested_count}, summary

### POST /app-store/v1/listCategories — 0 credits
static genre/category list

**Parameters:**
- `stores` (array, optional) — Which app stores to query (array). Aliases like ios/app_store and play/android/google are accepted; unknown names are ignored. Omit to query both. [one of: apple, google_play]

**Returns:** kind='discovery', results[]{store,categories[]{id,name},count}

### POST /app-store/v1/appDetails — 1 credit
full app profile

**Parameters:**
- `appId` (string, optional) — App id to look up: Apple numeric id OR Play package name (appleAppId / googlePlayPackage also accepted).
- `stores` (array, optional) — Which app stores to query (array). Aliases like ios/app_store and play/android/google are accepted; unknown names are ignored. Omit to query both. [one of: apple, google_play]
- `country` (string, optional, default "us") — Storefront country code (2-letter, lowercase), e.g. 'us'.
- `includeSimilarApps` (boolean, optional, default false) — Play-only: also return similar/related apps for the app.

**Returns:** kind='discovery', results[]{store,country,profile{...histogram},similar_apps[],status}

**Example request body:**
```json
{
  "stores": [
    "apple"
  ],
  "country": "us",
  "appId": "324684580"
}
```

### POST /app-store/v1/developerApps — 1 credit
every other app published by the same developer

**Parameters:**
- `appId` (string, optional) — App id to look up: Apple numeric id OR Play package name (appleAppId / googlePlayPackage also accepted).
- `stores` (array, optional) — Which app stores to query (array). Aliases like ios/app_store and play/android/google are accepted; unknown names are ignored. Omit to query both. [one of: apple, google_play]
- `country` (string, optional, default "us") — Storefront country code (2-letter, lowercase), e.g. 'us'.
- `count` (integer, optional, default 50) — Maximum number of apps to return.

**Returns:** kind='discovery', results[]{store,app_id,apps[],count,status}

### POST /app-store/v1/similarApps — 1 credit
related / similar apps for an app

**Parameters:**
- `appId` (string, optional) — App id to look up: Apple numeric id OR Play package name (appleAppId / googlePlayPackage also accepted).
- `stores` (array, optional) — Which app stores to query (array). Aliases like ios/app_store and play/android/google are accepted; unknown names are ignored. Omit to query both. [one of: apple, google_play]
- `country` (string, optional, default "us") — Storefront country code (2-letter, lowercase), e.g. 'us'.
- `count` (integer, optional, default 50) — Maximum number of apps to return.

**Returns:** kind='discovery', results[]{store,app_id,apps[],count,status} (Apple has no public similar feed — returns the developer's other apps)

## More
- Try it live, no code: https://reefapi.com/playground?engine=app-store
- Human docs page: https://reefapi.com/docs/app-store
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt