Skip to main content
Without a key, App Store popularity is an estimate from public store signals. With one, asobeast reads Apple’s weekly search popularity for the terms Apple publishes and uses it instead. See Popularity, difficulty and opportunity for what changes in the scores. The key belongs to the instance, not to a workspace, and the data it reads is the same for every workspace on it.

​
Create the key

1

Generate a private key

Apple Ads accepts an elliptic curve key on the prime256v1 curve.
2

Upload the public key

In Apple Ads, open Account Settings, then API, and paste the contents of apple-ads-public.pem. Apple shows a client id, a team id and a key id. Keep all three.
3

Keep the private key out of the repository

Store apple-ads-private.pem next to your Compose files, readable only by the account that runs Docker, and never commit it.

​
Give the API the key

1

Mount the key read only

Add a docker-compose.override.yml beside docker-compose.yml:
2

Set the four variables

In apps/api/.env:
Set all four or none. A partial set refuses to boot and names the missing ones. APPLE_ADS_AD_ACCOUNT_ID is optional; see the configuration reference.
3

Recreate the API

​
Confirm the sync ran

The sync runs every Monday at 09:00 UTC by default, after Apple posts the week that ended on Saturday. To run it now, sign in as the owner, open /admin/queues, select the pipeline queue and promote the apple-popularity repeatable job. Then count what was stored per market and week:
A keyword Apple lists shows the source “Apple Ads search popularity” and high confidence once it is next scored. Score one from its row actions to see it at once. To see how the estimate compares with Apple’s number on your own keywords, run the calibration command from a source checkout whose apps/api/.env points at the same database:
Below ten keywords with both numbers it says there is not enough data yet.

​
Rotate the key

Generate and upload a new key as above, replace the mounted file and APPLE_ADS_KEY_ID, recreate the API, then revoke the old key in Apple Ads. Stored popularity stays valid, because it is Apple’s published data rather than anything tied to the key.

​
Disconnect

Remove the four variables and recreate the API. The weekly sync is unscheduled on the next start and scoring returns to the estimate. Stored weeks stay in the table but are no longer read.
Last modified on September 22, 2026