Data reference - Adriel Knowledge Base

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

How to read the columnsData type uses Adriel’s 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; italic marks a value Adriel computes or derives on its side rather than a single API field. Currency values are reported in each ad account’s configured Apple Search Ads currency.

Campaign Attributes

Metric	Description	Data type	API Key
Active Status	Whether the campaign, ad group, or ad is currently active.	Text	Adriel-side
Ad Account Name	Name of the Apple Ads account that owns the campaign data.	Text	`name`, `orgName`
Ad Name	Name of the Apple Ads ad represented by this connector.	Text	`name`, `adGroupName`
Ad Set Name	Name of the Apple Ads ad group.	Text	`name`, `adGroupName`
Ad Spend	Total spend in the organization currency during the reporting period.	Currency	`localSpend.amount`
Bid Cap	Maximum bid amount used for the ad group or keyword.	Currency	`defaultBidAmount.amount`, `bidAmount.amount`
Bid Strategy	Bid strategy configured for the campaign or ad group.	Text	`biddingStrategy`, `bidStrategy`
Budget	Configured campaign or ad group budget amount and currency.	Text	`lifetimeBudget`, `dailyBudget`, `lifetimeBudgetAmount.amount`, `lifetimeBudgetAmount.currency`, `dailyBudgetAmount.amount`, `dailyBudgetAmount.currency`
Campaign Name	Unique name of the Apple Ads campaign.	Text	`name`, `campaignName`
Creative Type	Creative format classification available for the promoted app creative.	Text	Adriel-derived
Creative URL	Creative image URLs associated with the promoted app.	Text	`app.artworkUrl512`, `app.screenshotUrls`, `app.artworkUrl100`
Daily Budget	Daily budget amount available to the campaign or ad group.	Currency	`dailyBudget`, `dailyBudgetAmount.amount`
Ends	Scheduled end date and time for the Apple Ads entity.	Date	`endTime`
Landing URL	Destination URLs used when people tap the ad.	Text	`app.trackViewUrl`
Lifetime Budget	Lifetime or total budget amount configured for the campaign or ad group.	Currency	`lifetimeBudget`, `lifetimeBudgetAmount.amount`
Objective	Campaign objective used by this connector. Apple Search Ads campaigns here are treated as app install campaigns.	Text	Fixed to `APP_INSTALLS`
Starts	Scheduled start date and time for the Apple Ads entity.	Date	`startTime`
Status (Text)	A human-readable label for the current delivery status.	Text	Adriel-side
Status (Toggle)	Current delivery status of the Apple Ads entity represented in this row.	Text	Adriel-side
UTM Campaign	UTM campaign values associated with the ad destination URL when available.	Text	Adriel-side
UTM Content	UTM content values associated with the ad destination URL when available.	Text	Adriel-side
UTM Medium	UTM medium values associated with the ad destination URL when available.	Text	Adriel-side
UTM Source	UTM source values associated with the ad destination URL when available.	Text	Adriel-side
UTM Term	UTM term values associated with the ad destination URL when available.	Text	Adriel-side

Campaign Structure

Metric	Description	Data type	API Key
Ad Account ID	Identifier of the Apple Ads account that owns the data.	Text	`id`, `orgId`
Ad ID	Identifier of the Apple Ads ad represented by this connector.	Text	`id`, `adGroupId`
Ad Set ID	Identifier of the Apple Ads ad group.	Text	`id`, `adGroupId`
Campaign ID	Identifier of the Apple Ads campaign.	Text	`id`, `campaignId`
Channel	Marketing channel classification applied for cross-connector rollup.	Text	Adriel-side
Keyword ID	Identifier of the Apple Ads keyword.	Text	`id`, `keywordId`
Keyword Name	Keyword text used in the Apple Ads ad group.	Text	`text`, `keyword`

Click Performance

Metric	Description	Data type	API Key
Clicks (All)	Number of ad taps during the reporting period.	Number	`taps`
CPC	Cost per tap — spend divided by taps.	Currency	Adriel-computed
CPM	Cost per thousand impressions.	Currency	Adriel-computed
CTR	Click-through rate — taps divided by impressions.	Percentage	Adriel-computed
Impressions	Number of times the ad appeared in App Store search results during the reporting period.	Number	`impressions`
Link Clicks	Number of times people tapped the ad during the reporting period.	Number	`taps`

Conversion Performance

Metric	Description	Data type	API Key
Result Indicator	The metric used to represent the result for the campaign’s objective.	Text	Adriel-derived
Results	Result summary reported for the campaign’s configured objective.	Text	Adriel-derived

Creative Attributes

Metric	Description	Data type	API Key
Creative Image	A reference to the ad’s creative image.	Text	Adriel-side

Apple Search Ads-specific

These metrics exist only for Apple Search Ads and aren’t part of any cross-connector category. Every group above is a standard category shared with other connectors.

Metric	Description	Data type	API Key
Ad Spend	Total spend in the organization currency during the reporting period.	Currency	Adriel-side
Avg CPM	Average amount paid per 1,000 impressions.	Currency	`avgCPM.amount`
Avg CPT	Average amount paid for each ad tap.	Currency	`avgCPT.amount`
Date	Date range label returned by Apple for the report row.	Text	`date`
Impressions	Number of times the ad appeared in App Store search results during the reporting period.	Number	`impressions`
Local Spend	Total spend amount in the organization currency during the reporting period.	Currency	`localSpend.amount`
Mobile: App Install	Tap-through installs attributed to the ad within Apple Ads attribution windows.	Number	`tapInstalls`
Mobile: App Install: CPA	Average advertising cost for each attributed tap-through install.	Currency	`tapInstallCPI.amount`
Mobile: App Install: CVR	Share of ad taps that resulted in attributed tap-through installs.	Percentage	`tapInstallRate`
Tap Install CPI	Average spend for each tap-through install during the reporting period.	Currency	`tapInstallCPI.amount`
Tap Install Rate	Tap-through installs divided by total taps during the reporting period.	Percentage	`tapInstallRate`
Tap Installs	New downloads and redownloads from people who tapped the ad within Apple’s 30-day attribution window.	Number	`tapInstalls`
Tap New Downloads	New downloads from people who tapped the ad within Apple’s 30-day attribution window.	Number	`tapNewDownloads`
Tap Pre Orders Placed	Pre-orders placed by users who tapped the ad within Apple’s attribution windows.	Number	`tapPreOrdersPlaced`
Tap Redownloads	Redownloads from people who tapped the ad within Apple’s 30-day attribution window.	Number	`tapRedownloads`
Taps	Number of times people tapped the ad during the reporting period.	Number	`taps`
Total Avg CPI	Average spend for each total install, including tap-through and view-through installs.	Currency	`totalAvgCPI.amount`
Total Install Rate	Total installs divided by total taps during the reporting period.	Percentage	`totalInstallRate`
Total Installs	Total tap-through and view-through installs during the reporting period.	Number	`totalInstalls`
Total New Downloads	Total tap-through and view-through new downloads during the reporting period.	Number	`totalNewDownloads`
Total Pre Orders Placed	Total pre-orders attributed to the ad during the reporting period.	Number	`totalPreOrdersPlaced`
Total Redownloads	Total tap-through and view-through redownloads during the reporting period.	Number	`totalRedownloads`
Ttr	Tap-through rate, calculated as taps divided by impressions.	Percentage	`ttr`
View Installs	Installs from people who viewed the ad but did not tap it within Apple’s 1-day attribution window.	Number	`viewInstalls`
View New Downloads	New downloads from people who viewed the ad but did not tap it within Apple’s 1-day attribution window.	Number	`viewNewDownloads`
View Pre Orders Placed	Pre-orders placed by users who viewed the ad but did not tap it within Apple’s attribution windows.	Number	`viewPreOrdersPlaced`
View Redownloads	Redownloads from people who viewed the ad but did not tap it within Apple’s 1-day attribution window.	Number	`viewRedownloads`

Breakdowns

Campaign Structure

Channel, Platform, and Status groupings are provided by Adriel for cross-connector consistency rather than returned by Apple Search Ads.

Breakdown	Description	API Key
Ad	Apple Ads ad associated with the data.	`name`, `adGroupName`
Ad Account	Apple Ads account associated with the data.	`name`, `orgName`
Ad Name	Groups results by ad name.	Adriel-side
Ad Set	Apple Ads ad group associated with the data.	`name`, `adGroupName`
Ad Set Name	Groups results by ad set (ad group) name.	Adriel-side
Campaign	Apple Ads campaign associated with the data.	`name`, `campaignName`
Campaign Name	Groups results by campaign name.	Adriel-side
Channel	Marketing channel associated with the row.	Adriel-side
Keyword Match Type	Keyword match type used by the Apple Ads keyword.	`matchType`
Keyword Name	Keyword associated with the data row.	`text`, `keyword`
Platform	Groups results by advertising platform.	Adriel-side
Status (Toggle)	Current delivery status of the Apple Ads entity represented in this row.	Adriel-side

Creatives

Adriel post-processes ad creatives to generate these breakdowns.

Breakdown	Description	API Key
Ad Copy	Word extracted from the creative text.	Adriel-side
Color Clustering	Dominant color cluster detected in the creative.	Adriel-side
Creative Image	Perceptual hash of the ad image used for creative analysis and grouping.	Adriel-side
Emoji Analysis	Emoji detected in the creative text or image analysis.	Adriel-side

Date

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.

Breakdown	Description	API Key
Auto Time Breakdown	Automatically selected time bucket based on the requested date range.	Adriel-side
Daily Breakdown	Calendar day for the reported data.	Adriel-side
Monthly Breakdown	Calendar month for the reported data.	Adriel-side
Quarterly Breakdown	Calendar quarter for the reported data.	Adriel-side
Week Date Breakdown	Start date of the week bucket for the reported data.	Adriel-side
Week Number Breakdown (W#)	Week number in the year for the reported data.	Adriel-side
Weekly Breakdown (Start: Mon)	Calendar week for the reported data.	Adriel-side
Weekly Breakdown (Start: Sun)	Sunday-through-Saturday week bucket for the reported data.	Adriel-side
Yearly Breakdown	Calendar year for the reported data.	Adriel-side

Others

Breakdown	Description	API Key
No Grouping	Single combined bucket across the selected date range.	Adriel-side

Target

Breakdown	Description	API Key
Age	Age range segment returned by Apple Ads reporting.	`ageRange`
Country	Country code segment returned by Apple Ads reporting.	`countryCode`
Gender	Gender segment returned by Apple Ads reporting.	`gender`
Location	Location segment returned by Apple Ads reporting.	`countryOrRegion`

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 — v5, base URL https://api.searchads.apple.com/api/v5
Apple Search Ads reports — report request and metrics reference
OAuth token endpoint — https://appleid.apple.com/auth/oauth2/token (JWT client-credentials, ES256)

​Introduction

​Data refresh strategy

​Architecture data

​Reports data

​Architecture levels

​Date range limits

​Metrics

​Campaign Attributes

​Campaign Structure

​Click Performance

​Conversion Performance

​Creative Attributes

​Apple Search Ads-specific

​Breakdowns

​Campaign Structure

​Creatives

​Date

​Others

​Target

​Limitations

​API references

​See also

Introduction

Data refresh strategy

Architecture data

Reports data

Architecture levels

Date range limits

Metrics

Campaign Attributes

Campaign Structure

Click Performance

Conversion Performance

Creative Attributes

Apple Search Ads-specific

Breakdowns

Campaign Structure

Creatives

Date

Others

Target

Limitations

API references

See also