Apple Search Ads scripts have until January 26, 2027 to move to the new Platform API

The source here is a developer's guide published on dev.to, which cites Apple's Platform API documentation and Apple's GitHub repositories ^[19]. Going by that guide, moving an existing client takes three steps, in order:

1. Request a bearer token as before: OAuth 2.0 client credentials, scope `searchadsorg`, same token host ^[7]. 2. Call `GET /v1/acls` to find the ad account ID ^[9]. 3. Send `X-AP-Context: adAccountId={id}` on every request to `api.ads.apple.com/v1` ^[9][1].

Step three is where the guide's author lost time. "Here's where I burned an hour when integrating this into Sonar's pipeline," the author wrote ^[11]. The token alone does not tell the API which account a request is for. The header does ^[9]. The guide advises checking that header first whenever an initial call returns a 403, which is a terse way for the API to ask which account you meant ^[10]. The credentials also need one of three API roles on the account: API Account Manager, API Read Only or Limited Access ^[8].

Apple's client libraries take step three off the list of things that can go wrong. According to the guide, the Python, Node, Java and Swift libraries refresh tokens and set the context header themselves ^[12]. They went up on August 14, 2026, 165 days before the old API's sunset ^[5][1]. When the guide was written, all four repositories had close to zero stars ^[6]. For a new integration I would take the SDK anyway. The header bug is the one most likely to cost time, and the library handles it. For an existing client that already refreshes tokens, I think the smaller change is to patch the base URL and add one header. That also keeps a four-month-old dependency out of the build.

The popularity endpoint is where the new data is. `POST /v1/insights/apps/search-term-popularity/query` returns Apple's search-term rankings by country and genre. It carries the same Search Popularity score that the Apple Search Ads UI shows ^[13]. The request body sets granularity to `WEEKLY_SUN_SAT` or `MONTHLY`, and weekly buckets run Sunday through Saturday in UTC ^[14]. A dashboard that groups by Monday-start weeks in local time will not join to these rows cleanly. The country filter accepts EQUALS or IN, so one request can cover several markets. The genre filter accepts only EQUALS, across 15 consumer genres, with up to 5,000 results per page ^[15]. Getting per-genre rankings for every genre therefore takes at least 15 queries per period, before any pagination ^[2].

History starts in October 2025, the month Apple changed how Search Popularity is reported ^[16]. By the January 2027 sunset that will be about 15 months of data on one consistent basis ^[3]. The old endpoints could return impression-share data, a capability Apple announced in January 2023, but they never exposed a queryable popularity dataset ^[17][1].