App Store Connect

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:

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.

Available history

When a user connects his App Store Connect for the first time, we fetch up to:

  • 162 days for App Store Connect by Device
  • 32 days App Store Connect by Acquisition Channel

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.

propertydescription
impressions-total-uniqueThe 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-uniqueThe 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.
unitsThe 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).
redownloadsThe number of redownloads on a device running iOS, tvOS, or macOS. Redownloads do not include auto-downloads, restores, or updates.
total-downloadsThe number of first-time downloads and redownloads on devices with iOS, tvOS, or macOS.
iapThe number of in-app purchases on devices with iOS, tvOS, or macOS.
salesThe total amount billed to customers for purchasing apps, bundles, and in-app purchases.
paying-usersThe number of unique users that paid for the app or an in-app purchase.
sessionsThe 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-devicesThe 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-devicesThe 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-channelOnly 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 or iPad. This API doesn't provide data for devices such as Desktop or iPod.

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.

channelApp Store Connect equivalent
searchApp Store Search
browseApp Store Browse
apprefApp Referrer
webrefWeb 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 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.

channelApp Store Connect equivalent
searchApp Store Search
otherApp Store Browse
apprefApp Referrer
webrefWeb 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
  }
}