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

Impressions and spend

Currency values are reported in each ad account’s configured Apple Search Ads currency.

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

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

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

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

​Impressions and spend

​Taps

​Cost efficiency

​App installs and downloads

​Campaign structure metadata

​Breakdowns

​Campaign structure

​Keyword targeting

​Audience and geography

​Time

​Overview and status

​Limitations

​API references

​See also

Introduction

Data refresh strategy

Architecture data

Reports data

Architecture levels

Date range limits

Metrics

Impressions and spend

Taps

Cost efficiency

App installs and downloads

Campaign structure metadata

Breakdowns

Campaign structure

Keyword targeting

Audience and geography

Time

Overview and status

Limitations

API references

See also