The integrations reports endpoints allow you to fetch different reports related to your integrations in AppTweak.
You can access App Store Connect metrics through 3 different endpoints:
- App Store Connect by Device returns metrics with a breakdown by device (iphone, ipad or other)
- App Store Connect by Acquistion Channel returns metrics with a breakdown by acquisition channel (search, browse, appref, webref)
- App Store Connect by In-App Event returns reporting analytics with a breakdown by In-App Event.
- App Store Connect Report is the deprecated version of the API endpoint that returns metrics with a breakdown by device or a breakdown by acquisition channel
Update frequency
Data from the App Store Connect integrations is fetched on a daily basis. However, Apple provides updates with up to 2-days delay. In other words, it's normal that the data that ends 2 days ago instead of today since thatโs also what users will see in their App Store Connect console. Every day we fetch the last 32 days of data. If Apple brings some changes to your data outside of that window it won't be replicated on our side.
Available history
When a user connects his App Store Connect for the first time, we fetch:
- 162 days of historical data
After a user has made an integration, we collect data every day to build up the historical data.
Data discrepancy with your console
If you're looking at aggregated data per week or month, you might observe a discrepancy between data from our API and your App Store Connect Console data. The reporting metrics are fetched for a number of unique active devices for each specific date and then aggregated over each day. Apple makes the aggregation over each day and takes into account if the same user was active on several days within a certain time period. On their side it will only count as one impression/page view/install in the total. Therefore AppTweak might overestimate reporting metrics when being aggregated over weeks/months.
Property parameters
You can query different type of metrics from your App Store Connect Console through a query parameter called property which is used across all the endpoints. In the following table you'll find the lists of all available metrics & a description for each of them.
| property | description |
|---|---|
| impressions-total-unique | The number of unique devices running iOS 8, tvOS 9, macOS 10.14.1, or later, that viewed the app's icon on the App Store. |
| page-view-unique | The number of unique devices running iOS 8, tvOS 9, macOS 10.14.1, or later, that viewed your app's product page on the App Store. |
| units | The number of first-time downloads (which includes paid and free apps) on devices with iOS, tvOS, or macOS. App updates, downloads from the same Apple ID onto other devices, and redownloads to the same device are not counted. Note: The Apple nomenclature changed from units to downloads. While we resolved this change internally, we are keeping the same naming (i.e. units). |
| redownloads | The number of redownloads on a device running iOS, tvOS, or macOS. Redownloads do not include auto-downloads, restores, or updates. |
| total-downloads | The number of first-time downloads and redownloads on devices with iOS, tvOS, or macOS. |
| iap | The number of in-app purchases on devices with iOS, tvOS, or macOS. |
| sales | The total amount billed to customers for purchasing apps, bundles, and in-app purchases. |
| paying-users | The number of unique users that paid for the app or an in-app purchase. |
| sessions | The number of times the app has been used for at least two seconds. If the app is in the background and is later used again, that counts as another session. Only includes data from users who have agreed to share their diagnostics and usage information with app developers. |
| active-devices | The total number of devices with at least one session during the selected period. Only includes data from users who have agreed to share their diagnostics and usage information with app developers. |
| rolling-active-devices | The total number of devices with at least one session within 30 days of the selected day. Only includes data from users who have agreed to share their diagnostics and usage information with app developers. |
| acquisition-channel | Only applies to App Store Connect Report endpoint The impressions, page views and first time downloads with a breakdown by source type. Only includes data from users who have agreed to share their diagnostics and usage information with app developers. |
App Store Connect by Device
You can fetch reporting data from your App Store Connect integration filtered either by iPhone, iPad or Other. The Other device represents all IOS devices except iPhone and iPad, the value will be the sum of all these remaining devices such as Desktop, AppleTV and iPod. This API doesn't provide specific data for those devices.
The reporting data provided is not filtered by any source type and therefore all existing sources are aggregated together (App Store Browse, App Store Search, App Referrer, Web Referrer, Unavailable, Institutional Purchase, Event Notification).
Input parameters
You can find all the required and optional query parameters in the "QUERY PARAMS" section of the definition of the endpoint, accessible here.
Response format
{
"result": {
"1449752690": { // app_id for which you're getting data
"be": { // country_code
"ipad": { // device name
"start_date": "2023-01-01",
"end_date": "2023-01-03",
"values": [
5, // value for the state_date
12,
7 // value for the end_date
]
},
"iphone": {
"start_date": "2023-01-01",
"end_date": "2023-01-03",
"values": [
192,
276,
189
]
}
},
"fr": {
"ipad": {
"start_date": "2023-01-01",
"end_date": "2023-01-03",
"values": [
32,
43,
38
]
},
"iphone": {
"start_date": "2023-01-01",
"end_date": "2023-01-03",
"values": [
1315,
1872,
1234
]
}
}
}
},
"metadata": {
"request": {
"path": "/api/public/integrations/accounts/ios/reports/devices",
"params": {
"start_date": "2023-01-01",
"end_date": "2023-01-03",
"id": "762bba71-6613-4680-a0da-c4e8de90368b", // corresponds to the api-account-id
"devices": [
"iphone",
"ipad"
],
"property": "units", // property for which you requested data for
"apps": [
"1449752690"
],
"countries": [
"fr",
"be"
]
},
"cost": 1,
"max_credit_cost": 1,
"status": 200
},
"response": null
}
}
App Store Connect by Channel
You can fetch reporting data from your App Store Connect integration filtered either by App Store Search,App Store Browse, App Referrer or Web Referrer. This API doesn't provide data for the source types Institutional Purchase, Event Notification or Unavailable.
The reporting data provided is not filtered by any device type and therefore all existing devices are aggregated together (iPhone, iPad, Desktop & iPod).
Input parameters
You can find all the required and optional query parameters in the "QUERY PARAMS" section of the definition of the endpoint, accessible here.
Regarding the channel query parameter you can find the property name and the equivalence with App Store Connect in the following table.
| channel | App Store Connect equivalent |
|---|---|
search | App Store Search |
browse | App Store Browse |
appref | App Referrer |
webref | Web Referrer |
Response format
{
"result": {
"284882215": {
"fr": {
"search": { // App Store Search
"start_date": "2023-01-01",
"end_date": "2023-01-03",
"values": [
16732, // value for the start_date,
15203,
14231, // value for the end_date,
]
},
"browse": { // App Store Browse
"start_date": "2023-01-01",
"end_date": "2023-01-03",
"values": [
2417,
2312,
1908,
]
},
"appref": { // App Referrer
"start_date": "2023-01-01",
"end_date": "2023-01-03",
"values": [
242,
123,
152
]
},
"webref": { // Web Referrer
"start_date": "2023-01-01",
"end_date": "2023-01-03",
"values": [
154,
121,
172,
]
}
}
}
},
"metadata": {
"request": {
"path": "/api/public/integrations/accounts/ios/reports/channels",
"params": {
"start_date": "2023-01-01",
"end_date": "2023-01-03",
"id": "762bba71-6613-4680-a0da-c4e8de90368b", // corresponds to the api-account-id
"channels": [
"search",
"browse",
"appref",
"webref"
],
"property": "impressions-total-unique", // property parameter for which data is returned
"apps": [
"1449752690"
],
"countries": [
"fr"
]
},
"cost": 1,
"max_credit_cost": 1,
"status": 200
},
"response": null
}
}
App Store Connect by In-App Event
You can fetch reporting data from your App Store Connect integration for the In-App Event you run in your app.
The reporting data provided is not filtered by any device type and therefore all existing devices are aggregated together (iPhone, iPad, Desktop & iPod).
You can use the In-App Events Metadata endpoint to retrieve the metadata of the event IDs you'll get in the response.
Input parameters
You can find all the required and optional query parameters in the "QUERY PARAMS" section of the definition of the endpoint, accessible here.
Response format
The results are grouped per app_id, country code and event id.
{
"result": {
"545519333": { // app_id
"us": { // country code
"6443741640": { // event ID
"start_date": "2024-01-24",
"end_date": "2024-02-07",
"values": [
200.0,
120.0,
187.0,
189.0,
300.0,
256.0,
270.0,
0.0,
0.0,
0.0,
0.0,
120.0,
0.0,
125.0,
0.0
]
},
"6444430656": {
"start_date": "2024-01-24",
"end_date": "2024-02-07",
"values": [
null,
null,
187.0,
189.0,
300.0,
256.0,
270.0,
0.0,
0.0,
0.0,
0.0,
120.0,
0.0,
125.0,
0.0
]
}
}
}
},
"metadata": {
"request": {
"path": "/api/public/integrations/accounts/ios/reports/in_app_events",
"params": {
"start_date": "2024-01-24",
"end_date": "2024-02-07",
"id": "aaa00bbb-0bba-ccdd-eeff-1234567890ab", // corresponds to the api-account-id
"in_app_events": [
"6443741640",
"6444430656"
],
"property": "event-impressions-unique", // property parameter for which data is returned
"apps": [
"545519333"
],
"countries": [
"us"
]
},
"cost": 1,
"max_credit_cost": 1,
"status": 200
},
"response": null
}
}
App Store Connect Report [deprecated]
Input parameters
You can find all the required and optional query parameters in the "QUERY PARAMS" section of the definition of the endpoint, accessible here.
The property acquisition-channel for App Store Connect Report endpoint will provide impressions, pageviews and first-time downloads data by channels. When the acquisition-channel property is queried the devices parameter will be ignored and the data will be aggregated for both.
In the table beneath you can find the equivalence between the AppTweak channel name and App Store Connect source name.
| channel | App Store Connect equivalent |
|---|---|
search | App Store Search |
other | App Store Browse |
appref | App Referrer |
webref | Web Referrer |
Response format
{
"result": {
"284882215": [
{
"fr": {
"ipad": {
"start_date": "2023-01-01",
"end_date": "2023-01-01",
"values": [
93
]
},
"iphone": {
"start_date": "2023-01-01",
"end_date": "2023-01-01",
"values": [
2651
]
}
}
}
]
},
"metadata": {
"request": {
"path": "/api/public/integrations/accounts/reports",
"params": {
"start_date": "2023-01-01",
"end_date": "2023-01-01",
"id": "api-account-id",
"devices": [
"iphone",
"ipad"
],
"property": "total-downloads",
"apps": [
"284882215"
],
"countries": [
"fr"
]
},
"cost": 1,
"max_credit_cost": 1,
"status": 200
},
"response": null
}
}
{
"result": {
"284882215": [
{
"fr": {
"search": {
"start_date": "2023-01-01",
"end_date": "2023-01-01",
"impressions_total_unique": [
16733 // Number of unique impressions resulting from App Store Search for both iphone & ipad
],
"page_view_unique": [
1021
],
"units": [
1112
]
},
"other": {
"start_date": "2023-01-01",
"end_date": "2023-01-01",
"impressions_total_unique": [
2417
],
"page_view_unique": [
219
],
"units": [
29
]
},
"appref": {
"start_date": "2023-01-01",
"end_date": "2023-01-01",
"impressions_total_unique": [
242
],
"page_view_unique": [
240
],
"units": [
46
]
},
"webref": {
"start_date": "2023-01-01",
"end_date": "2023-01-01",
"impressions_total_unique": [
154
],
"page_view_unique": [
154
],
"units": [
54
]
},
"unknown": {
"start_date": "2023-01-01",
"end_date": "2023-01-01",
"impressions_total_unique": [
2
],
"page_view_unique": [
2
],
"units": [
3
]
}
}
}
]
},
"metadata": {
"request": {
"path": "/api/public/integrations/accounts/reports",
"params": {
"start_date": "2023-01-01",
"end_date": "2023-01-01",
"id": "api-account-id",
"devices": [
"iphone",
"ipad"
],
"property": "acquisition-channel",
"apps": [
"284882215"
],
"countries": [
"fr"
]
},
"cost": 1,
"max_credit_cost": 1,
"status": 200
},
"response": null
}
}