Returns metadata from an app that AppTweak has been able to gather from the App Store or the Google Play Store.
The applications' metadata are all the elements (title, subtitle, screenshots, etc.) that you can find on an app store page of an application. Each store displays different types of metadata. The metadata are store-specific (iOS vs Google Play) but they can also be device, country, and/or language specific. Make sure to specify the correct ones in the query parameters.
App Metadata are available through two endpoints:
- App Metadata - Current which returns the lates - most recent - metadata available
- App Metadata - History which returns the historical metadata changes
Missing metadata?Make sure to have entered the correct app ID. You can refer to our country codes to see the regions that AppTweak is currently covering.
Metadata Attributes
In the table below, you'll find the name of the metadata elements and a short explanation of each, sorted by device. The last column indicates whether those historical data is available.
| Attributes | iPhone/iPad | Android | Description | Historical Metadata available? |
|---|---|---|---|---|
| title | ✅ | ✅ | The App name as it appears on the App Store, in the chosen language | ✅ |
| subtitle | ✅ | ❌ | The subtitle explaining the purpose of the app (introduced in iOS 11) | ✅ |
| promotional_text | ✅ | ❌ | The promotional text should reflect the app’s new features, promotions, or highlighted content | ✅ |
| description | ✅ | ❌ | The app description as it appears on the App Store, in the chosen language | ✅ |
| short_description | ❌ | ✅ | The short description explaining the purpose of the app | ✅ |
| long_description | ❌ | ✅ | The app description as it appears on the Google Play Store, in the chosen language | ✅ |
| id | ✅ | ✅ | Store ID of the app | |
| genres | ✅ | ✅ | Category IDs as defined for Apple or Google Play | ✅ |
| icon | ✅ | ✅ | URL of the icon | ✅ |
| screenshots | ✅ | ✅ | App Store Preview Video: Key/value pair of the device and the screenshots URLs. Google Play Promotional Video: list of screenshot URLs | ✅ |
| videos | ✅ | ✅ | App Store: Key/value pair of the device and the video URLs. Google Play: list of video URLs | ✅ |
| feature_graphic | ❌ | ✅ | The graphic that appears before launching a video | ✅ |
| size | ✅ | ✅ | Size of the app in bytes | ✅ |
| rating | ✅ | ✅ | Average rating for an app | ➖ |
| developer | ✅ | ✅ | Key/value pairs describing the developer | ➖ |
| price | ✅ | ✅ | Price of the application as displayed in the target country | ✅ |
| versions | ✅ | ✅ | A list of version hash. Each version hash specifies the version number, the date on which it was released, and the release notes in the chosen language. | ✅ |
| release_date | ✅ | ✅ | The released date indicates when the app became available. Keep in mind that the release date of an app that has been removed from the store and then re-added will correspond to the last time the app was made available (i.e., the most recent re-upload date). | ➖ |
| similar_apps | ❌ | ✅ | A list of app IDs advertised as alternatives for this app in the section on the application page view | ➖ |
| customers_also_bought | ✅ | ❌ | A list of app IDs that Apple advertises as alternatives for this app in the You May Also Like section on the application page view on the App Store | ➖ |
| dna | ✅ | ✅ | The DNA of the App | ➖ |
| features | ✅ | ❌ | Key/boolean pairs describing if the App is compatible with passbook and the game center and if it has in app purchases. | ➖ |
| permissions | ❌ | ✅ | The list of permissions the app may try to access. Notably, the presence of the permission com.android.vending.BILLING indicates the presence of in-app purchases. | ➖ |
| in_app_purchases | ✅ | ❌ | The list of featured in-app purchases of the App. | ➖ |
A/B tests?A/B tests are available for Google Play apps in the App Metadata - History endpoints. For every change that is observed, it is indicated whether the change is related to an A/B test (True) or not (False).
In-App Purchases
The in_app_purchases attribute returns a list of promoted in-app purchases displayed on an iOS app's App Store product page. This field is only available for iOS apps.
NoteDevelopers can promote up to 20 in-app purchases on their App Store product page. The order (rank) is determined by the developer in App Store Connect, not by sales performance.
Example response
"in_app_purchases": [
{
"id": 6448311597,
"name": "ChatGPT Plus",
"description": "ChatGPT Plus",
"rank": 1,
"is_subscription": true,
"recurring_subscription_period": "P1M",
"subscription_family_name": "ChatGPT Plan",
"is_family_shareable": false,
"price": {
"value": "19.99",
"currency": "usd"
},
"artwork": null,
"discounts": null,
"is_merchandise_enabled": false,
"is_merchandise_visible": false
},
{
"id": 6657954405,
"name": "ChatGPT Pro",
"description": "ChatGPT Pro",
"rank": 2,
"is_subscription": true,
"recurring_subscription_period": "P1M",
"subscription_family_name": "ChatGPT Plan",
"is_family_shareable": false,
"price": {
"value": "200.00",
"currency": "usd"
},
"artwork": null,
"discounts": null,
"is_merchandise_enabled": false,
"is_merchandise_visible": false
}
]In-App Purchase Object
Each in-app purchase object contains the following attributes:
| Attribute | Type | Description |
|---|---|---|
id | integer | The unique identifier for the in-app purchase on the App Store |
name | string | The display name of the in-app purchase |
description | string | The description text shown to users on the App Store |
rank | integer | The display order on the product page (1 = first position). This order is set by the developer in App Store Connect |
is_subscription | boolean | true if this is a subscription, false for one-time purchases (consumables or non-consumables) |
recurring_subscription_period | string or null | The billing cycle for subscriptions, using ISO 8601 duration format. null for non-subscription purchases. See Subscription Period Codes section below. |
subscription_family_name | string or null | The subscription group name that this subscription belongs to. null for non-subscription purchases |
is_family_shareable | boolean | Whether the purchase can be shared with Family Sharing members |
price | object | The price object containing value (string) and currency (lowercase ISO currency code) |
artwork | object or null | Artwork/promotional image associated with the in-app purchase, if available |
discounts | array or null | Promotional offers or introductory prices, if available (see Discounts section below) |
is_merchandise_enabled | boolean | Whether merchandise features are enabled for this in-app purchase |
is_merchandise_visible | boolean | Whether merchandise is visible to users |
Subscription Period Codes
The recurring_subscription_period field uses ISO 8601 duration format:
| Code | Duration |
|---|---|
P7D | 7 days (weekly) |
P1M | 1 month |
P2M | 2 months |
P3M | 3 months (quarterly) |
P6M | 6 months (semi-annual) |
P1Y | 1 year (annual) |
Discounts Object
When promotional offers are available, each discount object contains:
| Attribute | Type | Description |
|---|---|---|
modeType | string | The type of offer: FreeTrial, PayAsYouGo, or PayUpFront |
numOfPeriods | integer | Number of billing periods the discount applies to |
price | number | The discounted price |
priceFormatted | string | The formatted price string for display |
priceString | string | Alternative formatted price string |
recurringSubscriptionPeriod | string | The billing period for the discount (e.g., P7D for a 7-day free trial) |
type | string | Additional discount type information |
FAQs
How do I fetch an app's store listing metadata (title, description, screenshots) via API?
You can fetch the full store listing for any app on the App Store or Google Play with AppTweak's App Store API, specifically the App Metadata - Current endpoint (GET /apps/metadata.json), which returns title, description, icon, screenshots, ratings, developer, version history, and category. Pass up to five app IDs in apps, plus optional country (default us), language, and device (iphone, ipad, android), and authenticate with the x-apptweak-key header. It covers any app, not just your own, and is refreshed daily.
How do I fetch the history of a competitor's app store listing changes and spot A/B tests?
You can pull a full history of any app's store-listing changes and flag A/B tests with AppTweak's App Store API, specifically the App Metadata - History endpoint (GET /apps/metadata/changes.json), which returns each change over a date range with its old and new values, a target (version, icon, screenshots, long_description, privacy_info, or size), a date, and an is_ab_test flag marking detected store-listing experiments. Set start_date and end_date (default: last 30 days) to monitor competitor creative and copy moves automatically.
How do I pull an app's screenshots, icon, and video previews via API?
You can pull any app's screenshots, icon, and video previews with AppTweak's App Store API, specifically the App Metadata - Current endpoint, which returns the icon field (icon URL), screenshots (image URLs grouped by device format, such as iphone_6_5 on iOS or a flat list on Android), and videos (preview video URLs where available). Set the device parameter (iphone, ipad, or android) to get the right asset set, since creatives differ by store and device. This is commonly used to build creative galleries or feed ad-creative intelligence tools.
Can I fetch app metadata for both iOS and Android apps from one API?
Yes — you can fetch app metadata for both the App Store and Google Play from one endpoint with AppTweak's App Store API, the App Metadata endpoint; set the device parameter to iphone, ipad, or android. The field structure differs slightly by store: iOS returns subtitle, promotional_text, and structured screenshots objects, while Android returns short_description, long_description, permissions, and similar_apps. App IDs also differ (numeric for iOS, a package name like com.example.app for Android). Query up to five apps per call, but keep each call to a single store and device.
What fields does an app store metadata API return?
AppTweak's App Metadata - Current endpoint returns an app's full store listing. Fields include:
title,subtitleorshort_description,descriptionorlong_description, andpromotional_texticon,screenshots(by device), andvideosrating(average),size,price, anddeveloper(id and name, plus email and website on Android)versionswith release notes and dates, and the overallrelease_datecategoriesand AppTweak DNA classificationin_app_purchaseson iOS orpermissionson Android
Exact fields vary between the App Store and Google Play.
What parameters does the app metadata endpoint accept?
AppTweak's App Metadata - Current endpoint accepts four parameters: apps, country, language, and device. apps (required) is a comma-separated list of app IDs, max five per call; country is a two-letter code (default us); language is a two-letter code that defaults to the country's default; and device is iphone, ipad, or android (default iphone). Authenticate with the x-apptweak-key header against https://public-api.apptweak.com/api/public/store. The History endpoint adds start_date and end_date (default: last 30 days).
How many credits does an app metadata API call cost?
A single-app App Metadata - Current call costs 11 credits in the documentation example, and App Metadata - History calls range from roughly 18 to 41 credits depending on the date range and number of changes. AppTweak's App Store API charges only for data actually returned, so cost scales with the number of apps queried and, for history, the length of the period. Check the metadata.request.cost field in any response for the exact amount.
How do I fetch competitor app version updates and release notes via API?
You can fetch when any app shipped an update and what changed with AppTweak's App Store API. App Metadata - Current returns the versions array (each entry has the version number, release_notes, and release_date) plus the app's overall release_date; for ongoing detection, poll App Metadata - History (GET /apps/metadata/changes.json), which returns each change with target set to version and the old and new release notes. Because data is refreshed daily, you can surface competitor releases automatically.
How do I fetch a competitor app's in-app purchases and subscription pricing via API?
On iOS, you can fetch any app's in-app purchases with AppTweak's App Store API, specifically the App Metadata - Current endpoint, which returns an in_app_purchases array where each entry includes the product name and description, price (value and currency), whether it is a subscription (is_subscription), the recurring_subscription_period (for example P1M or P1Y), is_family_shareable, and a rank. Poll it on a schedule to detect new tiers or price changes. Note this field is iOS-only; Google Play listings do not expose the same in-app purchase pricing here.
What's the difference between current app metadata and metadata history?
The difference is timing: Current returns an app's listing as it looks today, while History returns the log of changes to that listing over a date range. In AppTweak's App Store API, App Metadata - Current (GET /apps/metadata.json) gives a snapshot — title, description, screenshots, version, category — and App Metadata - History (GET /apps/metadata/changes.json) gives each change with old and new values, the affected target, and the is_ab_test flag for detected A/B tests. Use Current for the live state, History to see what changed and when. Both refresh daily across both stores.