> ## Documentation Index
> Fetch the complete documentation index at: https://docs.appeeky.com/llms.txt
> Use this file to discover all available pages before exploring further.
# API Overview
> Complete endpoint reference, response format, error codes, pagination, and country codes
Base URL: `https://api.appeeky.com`
All endpoints are versioned under `/v1`. Authentication is required for all endpoints except `/v1/health`.
Most endpoints cover both the **Apple App Store** and **Google Play** via a `platform` parameter (`apple` by default, or `google`). Apple uses numeric App IDs (`1617391485`); Google Play uses package names (`com.spotify.music`). See [Platforms](/docs/platforms) for the full cross-platform list and identifier rules.
***
## Endpoints
### Health & Auth
| Method | Endpoint | Description | Credits |
| ------ | ---------------- | ----------------------- | ------- |
| GET | `/v1/health` | Service health check | 0 |
| GET | `/v1/auth/usage` | Check your credit usage | 0 |
### Apps
| Method | Endpoint | Description | Credits |
| ------ | ------------------------------- | -------------------------------------------------------- | ------- |
| GET | `/v1/apps/:id` | Full app metadata (iTunes Lookup) | 2 |
| GET | `/v1/apps/:id/intelligence` | Intelligence report: revenue, downloads, IAPs, sentiment | 5 |
| GET | `/v1/apps/:id/similar` | Similar and competing apps (3-layer matching) | 2 |
| GET | `/v1/apps/:id/reviews` | User reviews from Apple RSS (up to 500) | 2 |
| GET | `/v1/apps/:id/keywords` | All organic keyword rankings for an app | 3 |
| GET | `/v1/apps/:id/keywords/trends` | Historical rank trend for a keyword | 2 |
| GET | `/v1/apps/:id/country-rankings` | App's chart positions across countries | 3 |
### Screenshots
| Method | Endpoint | Description | Credits |
| ------ | ----------------------------------------- | --------------------------------------------------------- | ------- |
| GET | `/v1/apps/:id/screenshots` | All screenshots for an app, split by device (iPhone/iPad) | 2 |
| GET | `/v1/apps/:id/screenshots/competitors` | Compare screenshots between an app and its competitors | 3 |
| GET | `/v1/categories/:genreId/top/screenshots` | Screenshots for top apps in a category | 3 |
### Keywords
| Method | Endpoint | Description | Credits |
| ------ | ------------------------------ | ---------------------------------------------- | ------- |
| GET | `/v1/keywords/ranks` | Apps ranking for a specific keyword | 2 |
| GET | `/v1/keywords/suggestions` | Apple Search autocomplete suggestions | 1 |
| GET | `/v1/keywords/metrics` | Search volume and difficulty for a keyword | 2 |
| GET | `/v1/keywords/compare` | Competitor keyword overlap and gap analysis | 3 |
| GET | `/v1/keywords/compare-cluster` | Multi-competitor keyword lifecycle buckets | 4 |
| GET | `/v1/keywords/visibility` | App visibility score across tracked keywords | 3 |
| GET | `/v1/keywords/movers` | Per-app keyword rank gainers / losers | 3 |
| GET | `/v1/keywords/gap` | Top opportunity-ranked competitor keyword gaps | 4 |
| GET | `/v1/keywords/trending` | Keywords with fastest-growing reach | 2 |
| POST | `/v1/keywords/track` | Add keyword to your tracking list | 1 |
### Search & Discovery
| Method | Endpoint | Description | Credits |
| ------ | ------------------------------------- | ----------------------------------------------- | ------- |
| GET | `/v1/search` | Search apps by keyword or App ID | 1 |
| GET | `/v1/categories` | List all App Store categories | 1 |
| GET | `/v1/categories/:id/top` | Top Free / Top Paid / Top Grossing per category | 2 |
| GET | `/v1/categories/:id/downloads-to-top` | Estimated downloads to reach chart positions | 2 |
| GET | `/v1/featured` | Apps featured on the App Store Today tab | 3 |
| GET | `/v1/new-releases` | Recently released apps from Apple RSS | 2 |
| GET | `/v1/discover` | Trending and noteworthy apps | 2 |
| GET | `/v1/discover/new-number-1` | Apps that just reached #1 in their category | 2 |
### Market Intelligence
| Method | Endpoint | Description | Credits |
| ------ | --------------------- | ------------------------------------------------------- | ------- |
| GET | `/v1/market/movers` | Top gainers, losers, new entries, and exits from charts | 3 |
| GET | `/v1/market/activity` | Live feed of chart movements and rank changes | 2 |
### Localization
| Method | Endpoint | Description | Credits |
| ------ | ------------------------------- | ------------------------------------------------------------------------------------------------- | ---------- |
| POST | `/v1/localizations` | Translate store metadata into up to 10 languages (async); optionally publish to App Store Connect | 3 / locale |
| GET | `/v1/localizations/jobs/:jobId` | Poll status and per-locale results of a localization run | 0 |
### Idea Validation
Turn a plain-language app idea into real App Store evidence — direct competitors with revenue/download estimates, keyword demand vs difficulty, and pain points mined from competitor reviews — plus an AI verdict and a go-to-market / ASO starter pack. Runs async; the POST returns a `jobId` you poll.
| Method | Endpoint | Description | Credits |
| ------ | ------------------------------- | ------------------------------------------------------- | ------- |
| POST | `/v1/validate-idea` | Validate an app idea against the live App Store (async) | 12 |
| GET | `/v1/validate-idea/jobs/:jobId` | Poll status and the full validation result | 0 |
**Request body** (`POST /v1/validate-idea`):
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"idea": "An AI-powered personal budgeting app that auto-categorizes spending and nudges you before you overspend",
"country": "us"
}
```
| Field | Type | Default | Description |
| --------- | ------ | ------- | -------------------------------------------- |
| `idea` | string | — | The app idea in plain language (8–600 chars) |
| `country` | string | `us` | ISO 3166-1 alpha-2 storefront to research |
**Result** (`GET /v1/validate-idea/jobs/:jobId` once `status` is `completed`) includes: a refined `plan` (search queries, seed keywords, category), `competitors[]` (with `estimatedRevenue` / `estimatedDownloads`), `keywords[]` (`volumeScore` + `difficulty`), `painPoints[]` mined from competitor reviews, a `verdictScore` (0–100) and `verdict` (`build` | `validate` | `pivot` | `avoid`), and a `marketing` starter pack (suggested name, subtitle, keywords, positioning, go-to-market moves).
### App Ad Creatives
Generate a Meta-ready square ad creative and paste-ready ad copy from a real App Store or Google Play listing. Runs async; the POST returns a `jobId` you poll.
| Method | Endpoint | Description | Credits |
| ------ | ---------------------------------- | ------------------------------------------------------------------------- | --------------------- |
| POST | `/v1/app-ad-creatives/generate` | Analyze a listing, generate copy, and optionally create a square ad image | 1 API or 1-5 creative |
| GET | `/v1/app-ad-creatives/jobs/:jobId` | Poll status and retrieve the generated creative result | 0 |
**Credits:** `analyze` or `generateImage: false` costs 1 API credit. Platform-funded image generation or editing uses creative credits by quality: `low` = 1, `medium` = 2, `high` = 5. BYOK image jobs use 1 API credit and no creative credits.
### RevenueCat (Your App Analytics)
RevenueCat endpoints require an `X-RC-Key` header with your RevenueCat secret API key (`sk_xxx`). These proxy to the [RevenueCat Charts API](https://www.revenuecat.com/docs/api-v2#tag/Charts-and-Metrics) and require the Pro plan (free up to \$2,500 MTR).
| Method | Endpoint | Description | Credits |
| ------ | ------------------------------------------ | ---------------------------------------------------------------- | ------- |
| GET | `/v1/revenuecat/overview` | Subscription metrics snapshot: MRR, revenue, active subs, trials | 2 |
| GET | `/v1/revenuecat/charts/:chartName` | Time-series chart data (revenue, MRR, churn, trials, etc.) | 3 |
| GET | `/v1/revenuecat/charts/:chartName/options` | Available resolutions, segments, and filters for a chart | 1 |
### App Store Connect (Your Apps)
App Store Connect endpoints require `X-ASC-Issuer-Id`, `X-ASC-Key-Id`, and `X-ASC-Private-Key` headers with your [App Store Connect API key](https://appstoreconnect.apple.com/access/api).
| Method | Endpoint | Description | Credits |
| ------ | ------------------------------------------------------------- | ---------------------------------------------------- | ------- |
| GET | `/v1/connect/apps` | List your apps (filter by bundleId) | 2 |
| GET | `/v1/connect/apps/:appId` | Get app details | 2 |
| GET | `/v1/connect/apps/:appId/app-infos` | List App Info resources (for app-level localization) | 2 |
| GET | `/v1/connect/apps/:appId/versions` | List App Store versions | 3 |
| POST | `/v1/connect/apps/:appId/versions` | Create new version | 4 |
| PATCH | `/v1/connect/versions/:versionId` | Update version attributes | 4 |
| GET | `/v1/connect/app-infos/:appInfoId/localizations` | List App Information localizations (name, subtitle) | 2 |
| PATCH | `/v1/connect/app-info-localizations/:localizationId` | Update App Information localization (name, subtitle) | 3 |
| GET | `/v1/connect/versions/:versionId/localizations` | List metadata localizations | 2 |
| GET | `/v1/connect/localizations/:localizationId` | Get localization (description, keywords) | 2 |
| PATCH | `/v1/connect/localizations/:localizationId` | Update metadata (description, keywords, whatsNew) | 3 |
| GET | `/v1/connect/apps/:appId/analytics/report-requests` | List analytics report requests | 2 |
| POST | `/v1/connect/apps/:appId/analytics/report-requests` | Create analytics report request | 3 |
| GET | `/v1/connect/analytics/report-requests/:requestId/reports` | List reports for a request | 2 |
| GET | `/v1/connect/analytics/reports/:reportId/instances` | List instances for a report | 2 |
| GET | `/v1/connect/analytics/report-instances/:instanceId/segments` | List segments (download URLs) | 2 |
| GET | `/v1/connect/analytics/report-segments/:segmentId` | Get segment details | 1 |
| GET | `/v1/connect/sales-reports` | Download Sales and Trends report (gzip) | 3 |
### Google Play Console (Your Apps)
Google Play Console endpoints use a Google service account. Connect once with `POST /v1/connect/google-play/credentials`, or pass `X-GP-Service-Account-Json` / `X-GP-Client-Email` + `X-GP-Private-Key-B64` per request. Public Google Play ASO/keyword endpoints still use `platform=google`; these endpoints are for apps you own in Play Console.
| Method | Endpoint | Description | Credits |
| ------ | ------------------------------------------------------------------- | --------------------------------------------------------------------------- | ------- |
| POST | `/v1/connect/google-play/credentials` | Save & verify service account credentials | 0 |
| GET | `/v1/connect/google-play/credentials/status` | Connection status | 2 |
| DELETE | `/v1/connect/google-play/credentials` | Remove stored credentials | 0 |
| GET | `/v1/connect/google-play/apps` | List Play Console apps visible to the service account | 2 |
| GET | `/v1/connect/google-play/apps/:packageName/reviews` | List reviews | 2 |
| GET | `/v1/connect/google-play/apps/:packageName/reviews/:reviewId` | Get one review | 2 |
| POST | `/v1/connect/google-play/apps/:packageName/reviews/:reviewId/reply` | Reply to or update a review response | 2 |
| GET | `/v1/connect/google-play/apps/:packageName/vitals/:metricSet` | Vitals metric metadata/freshness | 2 |
| POST | `/v1/connect/google-play/apps/:packageName/vitals/:metricSet/query` | Query Android vitals metric data | 2 |
| GET | `/v1/connect/google-play/apps/:packageName/anomalies` | List vitals anomalies | 2 |
| GET | `/v1/connect/google-play/apps/:packageName/subscriptions` | List subscription products | 2 |
| GET | `/v1/connect/google-play/apps/:packageName/one-time-products` | List one-time products | 2 |
| GET | `/v1/connect/google-play/apps/:packageName/tracks` | List release tracks via a temporary edit | 2 |
| GET | `/v1/connect/google-play/apps/:packageName/tracks/:track` | Get a release track | 2 |
| GET | `/v1/connect/google-play/apps/:packageName/tracks/:track/releases` | List releases on a track | 2 |
| PATCH | `/v1/connect/google-play/apps/:packageName/tracks/:track` | Patch a release track; supports `validateOnly=true` | 2 |
| GET | `/v1/connect/google-play/apps/:packageName/listings` | List store listing localizations | 2 |
| GET | `/v1/connect/google-play/apps/:packageName/listings/:language` | Get localized store listing metadata | 2 |
| PATCH | `/v1/connect/google-play/apps/:packageName/listings/:language` | Patch title, short/full description, or video; supports `validateOnly=true` | 2 |
| GET | `/v1/connect/google-play/reports/objects` | List GCS report objects for sales, earnings, stats, store performance | 2 |
| GET | `/v1/connect/google-play/reports/object` | Get one report object metadata | 2 |
| GET | `/v1/connect/google-play/reports/download` | Download a report object | 2 |
| POST | `/v1/connect/google-play/analytics/import-report` | Import one GCS stats CSV report into analytics tables | 2 |
| POST | `/v1/connect/google-play/analytics/import-reports` | Bulk-import GCS stats reports by prefix | 2 |
| POST | `/v1/connect/google-play/apps/:packageName/analytics/vitals-sync` | Sync crash/ANR vitals into analytics tables | 2 |
| GET | `/v1/connect/google-play/analytics` | Google Play analytics overview across imported apps | 2 |
| GET | `/v1/connect/google-play/apps/:packageName/analytics` | Google Play analytics overview for one app | 2 |
| GET | `/v1/connect/google-play/apps/:packageName/analytics/sources` | Traffic source, country, and UTM breakdowns | 2 |
| GET | `/v1/connect/google-play/apps/:packageName/analytics/search-terms` | Play Console search-term visitors, acquisitions, and conversion | 2 |
### Apple Search Ads
Separate from App Store Connect. Connect with `POST /v1/connect/apple-ads/credentials` or pass `X-ASA-*` headers per request. Full guide: [Apple Search Ads](/docs/apple-search-ads).
**Credentials & account** (0 credits)
| Method | Endpoint | Description | Credits |
| ------ | ------------------------------------------ | -------------------------------- | ------- |
| POST | `/v1/connect/apple-ads/credentials` | Save & verify Search Ads API key | 0 |
| GET | `/v1/connect/apple-ads/credentials/status` | Connection status | 0 |
| DELETE | `/v1/connect/apple-ads/credentials` | Remove stored credentials | 0 |
| GET | `/v1/connect/apple-ads/me` | Current API user | 2 |
| GET | `/v1/connect/apple-ads/acls` | Accessible orgs | 2 |
**Campaigns & ad groups** (2 credits)
| Method | Endpoint | Description | Credits |
| ------ | ----------------------------------------------------------------- | --------------------------------- | ------- |
| GET | `/v1/connect/apple-ads/campaigns` | List campaigns | 2 |
| PUT | `/v1/connect/apple-ads/campaigns/:campaignId` | Update status, name, daily budget | 2 |
| GET | `/v1/connect/apple-ads/campaigns/:campaignId/adgroups` | List ad groups | 2 |
| PUT | `/v1/connect/apple-ads/campaigns/:campaignId/adgroups/:adGroupId` | Update status, name, default bid | 2 |
**Targeting keywords** (2 credits)
| Method | Endpoint | Description | Credits |
| ------ | -------------------------------------------------------------------- | --------------------- | ------- |
| GET | `.../adgroups/:adGroupId/targetingkeywords` | List keywords | 2 |
| GET | `.../targetingkeywords/:keywordId` | Get one keyword | 2 |
| POST | `/v1/connect/apple-ads/campaigns/:campaignId/targetingkeywords/find` | Find across ad groups | 2 |
| POST | `.../targetingkeywords/bulk` | Create keywords | 2 |
| PUT | `.../targetingkeywords/bulk` | Update bids / status | 2 |
| POST | `.../targetingkeywords/delete` | Delete keywords | 2 |
| POST | `.../targetingkeywords/recommendations` | Keyword suggestions | 2 |
| POST | `.../bid-recommendations` | Bid suggestions | 2 |
**Negative keywords** (2 credits) — campaign and ad group: list, find, create, update, delete. See [Apple Search Ads](/docs/apple-search-ads#negative-keywords).
**Reports** (2 credits)
| Method | Endpoint | Description | Credits |
| ------ | ----------------------------------------------------------------- | -------------------------- | ------- |
| POST | `/v1/connect/apple-ads/campaigns/:campaignId/reports/keywords` | Keyword performance report | 2 |
| POST | `/v1/connect/apple-ads/campaigns/:campaignId/reports/searchterms` | Search terms report | 2 |
***
## Response Format
### Success
All successful responses wrap data in a `data` envelope:
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"data": {
"trackId": 1617391485,
"trackName": "Block Blast!",
"sellerName": "Hungry Studio",
"primaryGenreName": "Games",
"averageUserRating": 4.7,
"price": 0
}
}
```
### Error
Errors return an `error` object containing a machine-readable `code` and a human-readable `message`:
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"error": {
"code": "INVALID_APP_ID",
"message": "App ID must be a positive integer"
}
}
```
***
## Error Codes
### Client Errors (4xx)
| Status | Code | Description |
| ------ | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| 400 | `INVALID_APP_ID` | App ID is invalid for the platform — a positive integer for `apple`, or a package name (e.g. `com.example.app`) for `google` |
| 400 | `INVALID_QUERY` | Search query is too short (min 2 characters) |
| 400 | `INVALID_KEYWORD` | Keyword is missing or too short (min 2 characters) |
| 400 | `INVALID_COUNTRY` | Country code is not a valid ISO 3166-1 alpha-2 code |
| 400 | `INVALID_GENRE_ID` | Genre ID is not valid |
| 400 | `INVALID_SORT` | Sort parameter is not one of the allowed values |
| 400 | `MISSING_PARAMETER` | A required parameter is missing |
| 401 | `MISSING_API_KEY` | No API key provided in request headers |
| 401 | `INVALID_API_KEY` | API key is invalid, inactive, or revoked |
| 404 | `APP_NOT_FOUND` | App does not exist or is unavailable in the specified country |
| 404 | `KEYWORD_NOT_FOUND` | No ranking data available for this keyword |
| 409 | `EMAIL_ALREADY_REGISTERED` | Email address already has an active API key |
| 429 | `RATE_LIMIT_EXCEEDED` | Monthly credit limit has been reached |
### Server Errors (5xx)
| Status | Code | Description |
| ------ | --------------------- | ----------------------------------------------- |
| 500 | `INTERNAL_ERROR` | Unexpected server error |
| 500 | `DB_ERROR` | Database operation failed |
| 502 | `UPSTREAM_ERROR` | Apple API or upstream service returned an error |
| 503 | `SERVICE_UNAVAILABLE` | Service temporarily unavailable (maintenance) |
| 504 | `UPSTREAM_TIMEOUT` | Apple API or upstream service timed out |
All error responses include the `error.code` field, which is stable and safe to use for programmatic error handling. The `error.message` field is human-readable and may change.
***
## Pagination
Endpoints that return lists support pagination via query parameters:
| Parameter | Type | Default | Description |
| --------- | ------- | ------- | ---------------------------------------------------- |
| `limit` | integer | 25 | Number of results to return (max varies by endpoint) |
| `offset` | integer | 0 | Number of results to skip |
**Example:**
```
GET /v1/apps/1617391485/reviews?country=us&limit=10&offset=20
```
Paginated responses include a `pagination` object when applicable:
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"data": {
"reviews": [ ... ],
"pagination": {
"limit": 10,
"offset": 20,
"total": 487,
"hasMore": true
}
}
}
```
| Field | Type | Description |
| --------- | ------- | --------------------------------------- |
| `limit` | integer | Number of results returned |
| `offset` | integer | Current offset |
| `total` | integer | Total number of results available |
| `hasMore` | boolean | Whether there are more results to fetch |
***
## Country Codes
Many endpoints accept a `country` query parameter using **ISO 3166-1 alpha-2** codes. If omitted, the default is `us`.
### Common Country Codes
| Code | Country | Code | Country |
| ---- | -------------- | ---- | ------------ |
| `us` | United States | `jp` | Japan |
| `gb` | United Kingdom | `kr` | South Korea |
| `de` | Germany | `cn` | China |
| `fr` | France | `br` | Brazil |
| `it` | Italy | `in` | India |
| `es` | Spain | `au` | Australia |
| `ca` | Canada | `mx` | Mexico |
| `nl` | Netherlands | `tr` | Turkey |
| `se` | Sweden | `sa` | Saudi Arabia |
| `ru` | Russia | `id` | Indonesia |
The full list includes all countries where the App Store and Google Play are available (175+ storefronts). Use the two-letter ISO 3166-1 alpha-2 country code in lowercase.
***
## HTTP Status Codes
| Status | Meaning | When |
| ------ | --------------------- | ---------------------------------------------------------- |
| `200` | OK | Request succeeded |
| `201` | Created | Resource successfully created (e.g., API key registration) |
| `400` | Bad Request | Invalid parameters, missing required fields |
| `401` | Unauthorized | Missing or invalid API key |
| `404` | Not Found | App, keyword, or resource not found |
| `409` | Conflict | Duplicate resource (e.g., email already registered) |
| `429` | Too Many Requests | Monthly credit limit exceeded |
| `500` | Internal Server Error | Unexpected server failure |
| `502` | Bad Gateway | Upstream service error |
| `503` | Service Unavailable | Temporary maintenance |
| `504` | Gateway Timeout | Upstream service timeout |
***
## Key Features
* **App Metadata** — Complete iTunes Lookup data including description, screenshots, version, size, languages, and age rating
* **In-App Purchases** — Subscription and IAP names with prices, sourced directly from the App Store product page
* **Market Intelligence** — Estimated downloads and revenue using power-law models with confidence levels and ranges
* **Similar Apps** — Competitors via 3-layer matching: keyword overlap, title search + genre filter, and same developer (dedicated endpoint)
* **Category Charts** — Top Free, Top Paid, and Top Grossing per category with genre filtering
* **Downloads to Top** — Estimated daily downloads needed to reach specific chart positions per category
* **Keyword Intelligence** — Volume scoring, difficulty analysis, competitor overlap, autocomplete suggestions, and rank trends
* **User Reviews** — Customer reviews from Apple RSS with sorting and pagination (up to 500 per country)
* **App Search** — Keyword search or direct App ID lookup via the iTunes Search API
* **Country Rankings** — Track an app's chart positions across multiple countries simultaneously
* **Featured Apps** — App of the Day, Game of the Day, and curated editorial collections from the App Store Today tab
* **Trending Keywords** — Keywords with the fastest-growing reach, ranked by growth percentage
* **Market Movers** — Top gainers, losers, new entries, and apps that dropped out of charts, powered by periodic chart snapshots
* **Discovery** — New releases, trending apps, and apps that just hit #1 in their category
* **RevenueCat Integration** — Your own app's subscription analytics: MRR, revenue, active subscriptions, churn, trials, and 20+ chart types via RevenueCat's API
* **App Store Connect Integration** — Manage your apps: list apps/versions, update metadata (description, keywords, what's new), download analytics reports (140+ types), and Sales and Trends reports