What Is the Apple Ads Platform API?
The Apple Ads Platform API (api.ads.apple.com/v1) is Apple's unified API for managing Search Ads campaigns, pulling reports, and — for the first time — querying official search-term popularity data programmatically. It replaces the older Campaign Management API (v4 and v5, hosted at api.searchads.apple.com), which sunsets on January 26, 2027.
The migration deadline is real. If you have scripts, dashboards, or third-party integrations built against the old apple search ads api, they will stop working in five months. But the new API isn't just a forced migration — it adds a queryable, weekly/monthly search-term popularity dataset that the old endpoints never exposed.
This guide covers everything developers searching for apple search ads api documentation need: authentication, the popularity endpoint (the part ASO practitioners care about most), what the data actually contains, and what it doesn't. If you're already running Apple Search Ads and want the campaign-setup basics, see the complete Apple Search Ads guide for indie developers.
What Changed vs the Campaign Management API v4/v5
The apple search ads campaign management api at api.searchads.apple.com handled campaigns, ad groups, keywords, and reporting. The Platform API keeps all of that and adds three things worth knowing about.
1. Unified Apple Maps ("Brands") campaigns. The old API was App Store only. The Platform API manages both App Store and Apple Maps ad placements from a single base URL (source: Apple Ads Platform API documentation).
2. Official client libraries. Apple published first-party SDKs on GitHub on August 14, 2026: apple-ads-platform-api-python, apple-ads-platform-api-node, apple-ads-platform-api-java, and apple-ads-platform-api-swift (source: github.com/apple). As of this writing, all four repos have near-zero stars — adoption hasn't caught up yet.
3. The Insights endpoints. This is the centerpiece. The old API could return impression-share data (Apple announced that capability in January 2023), but the Platform API adds a fully queryable search-term popularity dataset with genre rankings, cross-genre popularity scores, and history back to October 2025 — precisely when Apple changed how Search Popularity data is reported. For background on that metric change, see the Apple Search Popularity score explainer.
One thing that did NOT change: OAuth 2.0 client-credentials authentication with the searchadsorg scope. Your existing credentials carry over. The token host is the same. If you've built anything against the apple ads api surface before, the auth flow will feel familiar.
Getting Access: Roles, OAuth, and the X-AP-Context Gotcha
Access requires an Apple Search Ads account with one of three API roles: API Account Manager, API Read Only, or Limited Access. Apple's setup help page walks through role assignment.
Authentication is standard OAuth 2.0 client-credentials. You generate a client ID and secret in the Apple Ads UI, request a bearer token with scope searchadsorg, and include the token in every subsequent call.
Here's where I burned an hour when integrating this into Sonar's pipeline: every API call requires an X-AP-Context header containing your ad account ID. The format is X-AP-Context: adAccountId={id}. You get the account ID from GET /v1/acls. Apple's documentation mentions this, but it's easy to miss — especially if you're used to APIs where the token itself identifies the account. If your first call returns a 403, check this header before anything else.
A minimal curl to verify your setup:
curl -X GET "https://api.ads.apple.com/v1/acls" \
-H "Authorization: Bearer $TOKEN" \
-H "X-AP-Context: adAccountId=$ACCOUNT_ID"For anyone building in Python, Apple's official apple-ads-platform-api-python library handles token refresh and the context header automatically (source: github.com/apple/apple-ads-platform-api-python). The Node, Java, and Swift libraries do the same.
The Search-Term Popularity Endpoint
The endpoint ASO practitioners have been waiting for is POST /v1/insights/apps/search-term-popularity/query. It returns Apple's official search-term rankings by country and genre, including the same Search Popularity score that Apple Search Ads surfaces in its UI (source: Apple Ads Platform API documentation).
Request Shape
You POST a JSON body specifying:
- Granularity:
WEEKLY_SUN_SAT(weeks run Sunday through Saturday, UTC) orMONTHLY - Country/region filter:
countryOrRegionwithEQUALSorINoperators - Genre filter:
genrewithEQUALS— one of 15 consumer genres (see below) - Page size: up to 5,000 results per page
History reaches back to October 2025, which is when Apple's Search Popularity metric change took effect.
Response Fields
Each record in the response includes:
| Field | What it means |
|---|---|
searchTerm | The keyword or phrase |
rankInGenre | Position within the specified genre (1 = most searched) |
searchPopularityInGenre | 1–100 popularity score within the genre |
searchPopularity1to100 | Cross-genre popularity on Apple's 1–100 scale |
searchPopularity1to5 | The old coarse 1–5 scale (legacy, still returned) |
The searchPopularity1to100 value is the one that maps directly to what ASO tools display as "Search Popularity." Sonar's analysis of Apple's search-term dataset (August 2026) confirmed that the searchPopularity1to100 values match Apple's keyword-level Search Popularity scale with a mean absolute error under 1 point — it's the real metric, not a new proxy.
The Undocumented searchTerm Filter
As of August 2026, you can filter by searchTerm using EQUALS, IN, or CONTAINS operators — even though this filter is not in Apple's official documentation. I've tested it and it works. But because it's undocumented, treat it as subject to change. Don't build critical pipelines around CONTAINS searches without a fallback to full-list ingestion.
The Fine Print: What the Popularity Data Actually Covers
This is where expectations need calibrating. The search-term popularity endpoint is a ranked-list dataset, not a lookup service. You cannot query the popularity of an arbitrary keyword — you get the top terms per genre, and anything outside that list simply isn't returned.
The Numbers
One US week of Apple's search-term popularity dataset contains exactly 7,500 distinct terms (top ~500 across 15 consumer genres). The SP cutoff at rank 500 ranges from 39 (Sports) to 57 (Games) — mid-popularity keywords in crowded genres don't make the list.
The 15 consumer genres covered are: Business, Education, Entertainment, Finance, Food & Drink, Games, Health & Fitness, Lifestyle, News/Publications, Photo & Video, Productivity & Utilities, Shopping, Social Networking, Sports, and Travel (source: Apple Ads Platform API documentation).
Coverage by Popularity Band
How much of the keyword landscape does this dataset capture? Sonar compared Apple's ranked lists against its own 160,000-keyword US corpus:
| Popularity band | Coverage in Apple's lists |
|---|---|
| 66+ | 100% |
| 56–65 | ~87% |
| 46–55 | ~33% |
| Below 46 | Under 1% |
Source: Sonar's analysis of Apple's search-term dataset, August 2026.
Real examples that fall outside their genre's top 500 despite meaningful popularity: "euchre" (SP 55), "obs" (SP 52), "sms" (SP 52). These keywords have real search demand, but they don't crack the list in their genre. If you need popularity for these mid-tail terms, you need a keyword-level tool.
79% Brand Queries
79% of the ranked terms are brand/navigational queries (13,807 of 17,436 US terms Sonar classified) — people typing "youtube" or "duolingo", not generic keywords. The generic minority is where the ASO signal lives. This means the dataset is excellent for competitive intelligence on brand searches but limited for discovering new generic keyword opportunities.
To put the generic/brand split in perspective: a keyword like "budget planner" (iOS difficulty 66, Apple-reported popularity 51) or "meditation" (iOS difficulty 79, popularity 54) represents the kind of generic term that does appear in the lists — but only because these terms are popular enough to crack the top 500 in their genres (source: Sonar /api/v1/keywords/search, queried 2026-08-16). Thousands of viable generic keywords with popularity in the 35–50 range do not.
Posting Lag
New weeks post with a delay — roughly within the following week. If you're building an automated pipeline, treat a not-yet-posted week as pending, not an error. Sonar ingests this dataset daily and it powers the Trends → Top search terms view (genre picker, week-over-week rank change, 26-week popularity sparklines).
What ASO Practitioners Can Do With This Data
The apple search ads reporting api and the popularity dataset serve different use cases. Here's what the Platform API is genuinely good for — and where you still need keyword-level tools.
Where the API Excels
- Head-term monitoring. Track the top 500 keywords per genre week over week. Spot when a competitor's brand climbs or a seasonal term surges.
- Trend detection. Weekly granularity with history back to October 2025 means you can see seasonality patterns: back-to-school surges (ParentSquare, Skyward, Schoology), fantasy football's August climb, game-launch spikes. Sonar surfaced all of these from the dataset before they showed up in other tools.
- Cross-genre popularity benchmarking. The
searchPopularity1to100field gives a consistent scale across genres, so you can compare "budget planner" in Finance against "meal planner" in Food & Drink on equal footing. - Brand monitoring at scale. With 79% of terms being brand queries, this is a weekly scoreboard of which apps dominate search in each category.
Where You Still Need Keyword-Level Tools
The API cannot answer "what is the popularity of my specific keyword?" unless that keyword happens to be in the top 500 for its genre. For the ASO APIs compared across the market, keyword-level popularity, difficulty scores, and download estimates come from tools like Sonar that maintain their own keyword-level popularity data (Apple's own 5–100 scale).
The positioning is straightforward: the apple ads api tells you the head of the market per genre. Keyword-level tools answer "what's the popularity of MY keyword" — a question the API's top-500 cutoff cannot.
Impression Share: The Other Insights Endpoint
POST /v1/insights/apps/impression-share/query returns daily (up to 30 days) or weekly (up to 4 weeks) impression-share data. It requires a promotedObjectId filter, meaning it only returns data for apps your ad account actively promotes (source: Apple Ads Platform API documentation).
This is advertiser tooling, not market research. You can see what share of impressions your promoted app captures for specific keywords, but you can't use it to research keywords you aren't already bidding on. If you're running Apple Search Ads campaigns, it's useful for budget allocation. For keyword discovery, look elsewhere.
Migration Checklist: Moving From v4/v5 to the Apple Ads API
The Campaign Management API v4/v5 at api.searchads.apple.com sunsets January 26, 2027 (source: 9to5Mac, April 2, 2026). Apple recommends migrating "as early as possible." Here is a practical checklist:
- Audit your current API calls. List every endpoint you hit on
api.searchads.apple.com. The Platform API's endpoint groups map closely: Campaigns, Ad Groups, Keywords, Ads, Reports all have direct equivalents. - Update the base URL. Change from
api.searchads.apple.com/api/v4(or v5) toapi.ads.apple.com/v1. - Add the X-AP-Context header. Every call needs
X-AP-Context: adAccountId={id}. Pull your account ID fromGET /v1/acls. - Switch to an official SDK if possible. The
apple-ads-platform-api-pythonandapple-ads-platform-api-nodelibraries handle auth, pagination, and the context header. If you're writing apple search ads api python scripts, these are the path of least resistance. - Update report field names. Some report fields have changed names. Test your reporting queries against the new API and verify the response schema matches your parsers.
- Add the Insights endpoints. While migrating, integrate
search-term-popularity/query— it's net-new data you weren't getting before. - Test rate limits. The Platform API's rate limits differ from v4/v5. Insights endpoints run at roughly 5 requests per second (observed, not documented). Build in backoff.
- Set a migration deadline with margin. Don't wait until January. API sunsets have a way of causing production fires at the last minute.
Frequently Asked Questions
Is the Apple Ads Platform API free to use?
Yes. The API itself has no usage fees — you need an Apple Search Ads account, but API access is included. You don't need active ad spend to call the Insights endpoints, though the impression-share endpoint only returns data for apps you're actively promoting (source: Apple Ads Platform API documentation).
Can I look up the search popularity of any keyword?
No. The search-term popularity endpoint returns ranked lists — the top ~500 terms per genre, per country, per week. If your keyword doesn't rank in a genre's top 500, it won't appear. Coverage vs Sonar's 160k-keyword US corpus: 100% of keywords with popularity 66+ appear in Apple's lists, ~87% at 56–65, ~33% at 46–55, under 1% below 46. For arbitrary keyword lookups, you need a keyword-level ASO tool.
What replaced the Apple Search Ads Campaign Management API?
The Apple Ads Platform API at api.ads.apple.com/v1 is the direct replacement. It covers all Campaign Management API v4/v5 functionality plus new Insights, Apple Maps campaign management, and official client libraries for Python, Node, Java, and Swift. The old API sunsets January 26, 2027 (source: 9to5Mac).
Does the API return real search volume numbers?
No. Apple does not disclose raw search counts. The API returns a 1-to-100 Search Popularity index — a relative score where higher values mean more searches. The scale is exponential, not linear, so SP 60 represents substantially more search volume than SP 50. For a deeper explanation of how to interpret these scores and estimate impressions from them, see the Apple Search Popularity score breakdown.
Is there an official Python or Node.js client library?
Yes. Apple published four official client libraries on August 14, 2026: apple-ads-platform-api-python, apple-ads-platform-api-node, apple-ads-platform-api-java, and apple-ads-platform-api-swift. All are available on github.com/apple. They handle OAuth token management, the X-AP-Context header, and pagination.
Want keyword-level popularity and difficulty data for the keywords Apple's ranked lists don't cover? Try Sonar free — it shows Apple's own Search Popularity score, difficulty, and competitor data for over 160,000 US keywords and counting.