> ## Documentation Index
> Fetch the complete documentation index at: https://docs.adriel.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Data reference

> Metrics, breakdowns, refresh cadence, and limits for the Apple Search Ads data source in Adriel.

## Introduction

Apple Search Ads is Apple's advertising platform for promoting apps in App Store search results across iPhone and iPad. Mobile app marketers use it to drive App Store impressions, taps, and installs, with CPT (cost per tap) and CPM payment models. Campaigns target the App Store search experience using keywords, search match, and demographic and device filters, and the connector imports the resulting structure and performance data through the Apple Search Ads Campaign Management API (v5).

As a marketing connector, metrics, breakdowns, and currencies are standardized so widgets can aggregate across sources without additional configuration.

To connect this data source, see [How to connect Apple Search Ads to Adriel](/data-sources/a-f/apple-search-ads/how-to-connect).

## Data refresh strategy

### Architecture data

Architecture covers ad accounts, campaigns, ad groups (ad sets), ads, and keywords. It refreshes twice daily, at **4:00 PM UTC** and **5:00 AM UTC**.

### Reports data

Reports include daily performance metrics for ad accounts, campaigns, ad groups, ads, and keywords.

**Real-time.** Report data is fetched from Apple Search Ads on demand when a dashboard loads, so the latest values are always visible. On top of that, scheduled cache refreshes keep historical data consistent across multiple time windows.

**Refresh schedule.** Reports refresh on three overlapping schedules:

* **5:00 PM UTC daily** — syncs the last **9 days** for ad account, campaign, ad group, and ad
* **11:40 PM and 6:40 AM UTC daily** — syncs the last **3 days** for ad account, campaign, ad group, and ad
* **7:30 AM UTC on the 1st and 15th of each month** — syncs the last **30 days** for ad account, campaign, ad group, and ad

## Architecture levels

Ad account → Campaign → Ad group (ad set) → Ad / Keyword

## Date range limits

| Breakdown | Max range |
| --------- | --------- |
| Daily     | 93 days   |
| Weekly    | 1 year    |
| Monthly   | 2 years   |

## Metrics

<Note>
  **How to read the columns**
  **Data type** uses this vocabulary: Number, Currency, Percentage, Ratio, Duration, Date, Text, URL, Array, Boolean.
  **API Key** in code style like `impressions` is the literal Apple Search Ads API field name. *Italic text* describes how a value is produced when it doesn't map cleanly to a single API field.
</Note>

### Impressions and spend

<Note>
  Currency values are reported in each ad account's configured Apple Search Ads currency.
</Note>

| Metric      | Description                                | Data type | API Key       |
| ----------- | ------------------------------------------ | --------- | ------------- |
| Impressions | Number of times ads were displayed.        | Number    | `impressions` |
| Spend       | Reported spend in the ad account currency. | Currency  | `localSpend`  |

### Taps

| Metric           | Description                  | Data type  | API Key |
| ---------------- | ---------------------------- | ---------- | ------- |
| Taps             | Number of taps on the ads.   | Number     | `taps`  |
| Tap-through rate | Taps divided by impressions. | Percentage | `ttr`   |

### Cost efficiency

| Metric      | Description                            | Data type | API Key       |
| ----------- | -------------------------------------- | --------- | ------------- |
| Average CPT | Average cost per tap.                  | Currency  | `avgCPT`      |
| Average CPM | Average cost per thousand impressions. | Currency  | `avgCPM`      |
| Average CPA | Average cost per install.              | Currency  | `totalAvgCPI` |

### App installs and downloads

| Metric          | Description                              | Data type  | API Key             |
| --------------- | ---------------------------------------- | ---------- | ------------------- |
| Installs        | App installs attributed to the campaign. | Number     | `totalInstalls`     |
| New downloads   | Net new downloads from first-time users. | Number     | `totalNewDownloads` |
| Redownloads     | Re-downloads by previous users.          | Number     | `totalRedownloads`  |
| Conversion rate | Installs as a share of taps.             | Percentage | `totalInstallRate`  |

### Campaign structure metadata

| Metric          | Description                                                   | Data type | API Key                          |
| --------------- | ------------------------------------------------------------- | --------- | -------------------------------- |
| Ad account name | Name of the ad account.                                       | Text      | `orgName`                        |
| Campaign name   | Campaign name.                                                | Text      | `name`                           |
| Ad group name   | Ad group (ad set) name.                                       | Text      | `name`                           |
| Ad name         | Ad (creative set) name.                                       | Text      | `name`                           |
| Keyword name    | Keyword text, available for Search campaigns only.            | Text      | *Resolved from keyword metadata* |
| Objective       | Campaign objective; always App installs for Apple Search Ads. | Text      | *Fixed to `APP_INSTALLS`*        |
| Status          | Campaign / ad group / ad status.                              | Text      | `status`                         |

## Breakdowns

### Campaign structure

| Breakdown | Description                 | API Key      |
| --------- | --------------------------- | ------------ |
| Campaign  | Group by campaign.          | `campaignId` |
| Ad group  | Group by ad group (ad set). | `adGroupId`  |
| Ad        | Group by ad (creative set). | `adId`       |

### Keyword targeting

| Breakdown         | Description                                  | API Key     |
| ----------------- | -------------------------------------------- | ----------- |
| Keyword           | Group by keyword; Search campaigns only.     | `keywordId` |
| Search match type | Group by exact, broad, or search-match type. | `matchType` |

### Audience and geography

| Breakdown        | Description                                         | API Key           |
| ---------------- | --------------------------------------------------- | ----------------- |
| Country / region | Country or region of the impression.                | `countryOrRegion` |
| Country          | Two-letter country code.                            | `countryCode`     |
| Locality         | City-level location of the impression.              | `locality`        |
| Admin area       | State or administrative region of the impression.   | `adminArea`       |
| Device           | Device class the ad was served on (iPhone or iPad). | `deviceClass`     |
| Age              | Audience age range.                                 | `ageRange`        |
| Gender           | Audience gender.                                    | `gender`          |

### Time

<Note>
  Apple Search Ads returns daily records; Adriel groups them into these views, so all time breakdowns are Adriel-side aggregations of the same underlying daily data.
</Note>

| Breakdown                  | Description                                                  |
| -------------------------- | ------------------------------------------------------------ |
| Auto Time Breakdown        | Automatically picks the best granularity for the date range. |
| Daily                      | Split reports by day.                                        |
| Weekly (Start: Mon)        | Split reports by week, starting Monday.                      |
| Weekly (Start: Sun)        | Split reports by week, starting Sunday.                      |
| Week Date Breakdown        | Group by the day of the week the impression occurred.        |
| Week Number Breakdown (W#) | Split by week number in the year.                            |
| Monthly                    | Split reports by calendar month.                             |
| Quarterly                  | Split reports by calendar quarter.                           |
| Yearly                     | Split reports by calendar year.                              |

### Overview and status

<Note>
  These groupings are provided by Adriel for cross-connector consistency rather than returned by Apple Search Ads.
</Note>

| Breakdown   | Description                                                 |
| ----------- | ----------------------------------------------------------- |
| Channel     | Constant grouping label used for cross-connector rollup.    |
| Platform    | Group results by the platform where the ads were broadcast. |
| No Grouping | Do not break down; return one aggregated row.               |
| Objective   | Group by campaign objective.                                |
| Status      | Group by campaign / ad group / ad status.                   |

## Limitations

* **Ad account level not available for reports** — report data is served at the campaign, ad group, ad, and keyword levels; campaign is substituted where an ad-account-level report row would otherwise appear.
* **Objective is always App installs** — Apple Search Ads campaigns map to a fixed `APP_INSTALLS` objective, so objective is not a differentiating breakdown.
* **Keyword breakdowns apply to Search campaigns only** — keyword and search-match-type groupings return no rows for non-search campaign types.
* **Wide queries may be slower** — report queries are split by campaign ID and by 60-day windows before fetching and then concatenated, so long-range or many-campaign queries take longer than other connectors.
* **Two-phase pending setup** — a new connection stays pending until the Client ID, Team ID, and Key ID are supplied. If Apple's signing credentials become invalid, the connection returns to a pending state until the credentials are re-supplied.

## API references

* [Apple Search Ads Campaign Management API](https://developer.apple.com/documentation/apple_search_ads) — v5, base URL `https://api.searchads.apple.com/api/v5`
* [Apple Search Ads reports](https://developer.apple.com/documentation/apple_search_ads/reports) — report request and metrics reference
* OAuth token endpoint — `https://appleid.apple.com/auth/oauth2/token` (JWT client-credentials, ES256)

## See also

* [How to connect Apple Search Ads to Adriel](/data-sources/a-f/apple-search-ads/how-to-connect) (paired how-to)
* [Google Ads data reference](/data-sources/g-n/google-ads/data-reference) — for cross-platform App campaign comparison