Apple Ads Keyword Popularity (1–100): Country Insights vs. Suggestion Scores Explained

What a score of 5, 35, or 85 actually means for App Store Optimization

Apple’s `searchPopularity1to100` index is exponential, not linear. A keyword with a popularity of `80` does not have twice the search volume of a keyword with a popularity of `40`—it often represents 10× to 50× more daily searches. When selecting keywords for your iOS Title (30 chars), Subtitle (30 chars), and Keyword Field (100 bytes), breaking the 1–100 scale into four operational tiers prevents you from wasting metadata space:

Why Searchbop never mixes `countryPopularity` and `suggestions` without a label

When we built Searchbop’s ASO engine ([`apple-ads.ts`](file:///Users/tarik/Desktop/TengrX-SEO/packages/core/src/aso/apple-ads.ts) and [`apple-popularity-test.mjs`](file:///Users/tarik/Desktop/TengrX-SEO/scripts/aso-test/apple-popularity-test.mjs)), we tested both of Apple’s official popularity endpoints across head terms and 4-word long-tail phrases in multiple storefronts (`US`, `TR`, `GB`, `DE`). Here is the exact behavior observed on the wire:

Endpoint A: POST /v1/insights/apps/search-term-popularity/query
- Granularity:  WEEKLY_SUN_SAT (requires completed Sunday-Saturday UTC range)
- Filters:      countryOrRegion = "US", searchTerm IN [...]
- Coverage:     Lists only ~top 500 terms per genre (15 genres). Most 3-4 word
                long-tail phrases return 0 rows (absent from the table).
- Scale:        True country-specific popularity for that storefront and week.

Endpoint B: POST /v1/suggestions/keywords/query
- Filters:      promotedObjectId = [adamId], terms IN [seed], countriesOrRegions IN [country]
- Coverage:     Returns related keywords + exact match popularity for almost ANY term,
                including long-tail phrases absent from Endpoint A.
- Scale Caveat: Returns the exact same popularity integer across different countries,
                and its integer value for head terms differs from Endpoint A's country score.
- Ownership:    Apple only serves suggestions for an adamId that belongs to the connected
                Apple Ads account (returns 4xx refusal for third-party competitor app IDs).

Because of this behavior, Searchbop runs a strict two-step lookup in [`readPopularity()`](file:///Users/tarik/Desktop/TengrX-SEO/packages/core/src/aso/research.ts#L55-L80):

1. It first batches your keywords (50 terms per request) against Endpoint A (`countryPopularity`) using the newest published Sunday–Saturday week for that country and marks every match as source: "insight".
2. Only for terms missing from the country insight list, it queries Endpoint B (`suggestions`) using your app’s storeAppId and marks matches as source: "suggestion". If the app you are inspecting is a competitor’s app (not linked to your Apple Ads account), Searchbop catches Apple’s 4xx refusal gracefully and displays a clear notice explaining why only country-level insight scores are available.

Why querying “last week” in Apple Ads often returns empty rows on Monday

A common bug in custom ASO scripts is computing the most recently finished Sunday-to-Saturday UTC week and assuming Apple has already published its `searchPopularity1to100` rows on Sunday morning. In practice, Apple publishes each weekly batch several days after Saturday ends.

To prevent false “no data” results, Searchbop’s [`latestWeek()`](file:///Users/tarik/Desktop/TengrX-SEO/packages/core/src/aso/apple-ads.ts#L116-L123) probe generates the last 8 completed Sunday–Saturday UTC windows (`recentWeeks(8)`) from newest to oldest and tests each week with a lightweight 1-row check (`limit: 1` in `PRODUCTIVITY_UTILITIES`) until it finds the newest week that Apple has actually populated for that country.

Connecting Apple Ads safely with a local `prime256v1` key pair

Apple Ads uses OAuth 2.0 client credentials backed by an asymmetric ECDSA key pair (`ES256` on the `prime256v1` curve). Instead of making you run `openssl ecparam` commands in Terminal, Searchbop’s Connections screen generates the key pair locally on your machine using Node’s native `crypto.generateKeyPairSync("ec", { namedCurve: "prime256v1" })`:

• Your private key stays local: The `sec1` PEM private key is encrypted at rest inside your local database (`AES-256-GCM`) and is used only to sign short-lived (10-minute) client secrets sent directly to `https://appleid.apple.com/auth/oauth2/token`.
• Read-only role is enough: You copy the `spki` public key into your Apple Ads account settings for an API user with read-only access and paste back the `clientId`, `teamId`, and `keyId`.