API Overview

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 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):

{
  "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 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.

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.

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. 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:

{
  "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:

{
  "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:

{
  "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

Getting Started

Apps

My Data - Appeeky Web

Keywords

ASO Tools

AI Visibility

Search & Discovery

Market Intelligence

RevenueCat

App Store Connect

Google Play Console

Apple Search Ads

Growth Channels

Reference

Endpoints

Health & Auth

Apps

Screenshots

Keywords

Search & Discovery

Market Intelligence

Localization

Idea Validation

App Ad Creatives

RevenueCat (Your App Analytics)

App Store Connect (Your Apps)

Google Play Console (Your Apps)

Apple Search Ads

Response Format

Success

Error

Error Codes

Client Errors (4xx)

Server Errors (5xx)

Country Codes

Common Country Codes

HTTP Status Codes

Key Features

​Endpoints

​Health & Auth

​Apps

​Screenshots

​Keywords

​Search & Discovery

​Market Intelligence

​Localization

​Idea Validation

​App Ad Creatives

​RevenueCat (Your App Analytics)

​App Store Connect (Your Apps)

​Google Play Console (Your Apps)

​Apple Search Ads

​Response Format

​Success

​Error

​Error Codes

​Client Errors (4xx)

​Server Errors (5xx)

​Pagination

​Country Codes

​Common Country Codes

​HTTP Status Codes

​Key Features

Endpoints

Health & Auth

Apps

Screenshots

Keywords

Search & Discovery

Market Intelligence

Localization

Idea Validation

App Ad Creatives

RevenueCat (Your App Analytics)

App Store Connect (Your Apps)

Google Play Console (Your Apps)

Apple Search Ads

Response Format

Success

Error

Error Codes

Client Errors (4xx)

Server Errors (5xx)

Pagination

Country Codes

Common Country Codes

HTTP Status Codes

Key Features