> ## Documentation Index
> Fetch the complete documentation index at: https://docs.appeeky.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Apple Ads Insights & Popularity

> Official search term popularity, keyword suggestions, and impression share from Apple Ads Platform API v1

Apple Ads Platform API v1 adds first-class **search term popularity** and **keyword suggestions with popularity scores**. These are market demand signals, not campaign performance reports.

Campaign reports (what users typed that triggered *your* ads) stay on [Reports](/docs/apple-search-ads-reports). Use Insights when you want Apple's relative search volume for a genre, country, or app.

<Tip>
  Requires connected [Apple Search Ads credentials](/docs/apple-search-ads-credentials). Same OAuth keys as Campaign Management API v5. Appeeky calls `https://api.ads.apple.com/v1` with `X-AP-Context: adAccountId=…`.
</Tip>

***

## Endpoints

| Endpoint                                                     | Description                                                              |
| ------------------------------------------------------------ | ------------------------------------------------------------------------ |
| `POST /v1/connect/apple-ads/insights/search-term-popularity` | Ranked search terms for a country + genre, with 1–100 and 1–5 popularity |
| `POST /v1/connect/apple-ads/insights/impression-share`       | Your app's share of impressions, rank, and popularity for search terms   |
| `POST /v1/connect/apple-ads/suggestions/keywords`            | Keyword ideas for an app, each with a 0–100 popularity score             |
| `POST /v1/connect/apple-ads/suggestions/phrases`             | Phrase discovery (`SUGGESTION`) or lookup (`SEARCH`) with popularity     |

MCP tools: `asa_search_term_popularity`, `asa_impression_share`, `asa_keyword_suggestions`, `asa_phrase_popularity`.

***

## Search Term Popularity

Returns the highest-volume search terms in an App Store genre and country. Scores are Apple's official relative popularity, not estimated volume.

```bash curl theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST "https://api.appeeky.com/v1/connect/apple-ads/insights/search-term-popularity" \
  -H "X-API-Key: YOUR_APPEEKY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "genre": "PRODUCTIVITY",
    "countries": ["US"],
    "granularity": "WEEKLY_SUN_SAT",
    "limit": 50
  }'
```

| Field         | Description                                                                                                                                     |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `genre`       | Required. App Store genre token, e.g. `PRODUCTIVITY`, `TRAVEL`, `GAMES`, `HEALTH_FITNESS`. iTunes names like `Health & Fitness` are normalized. |
| `countries`   | ISO codes. Default `["US"]`.                                                                                                                    |
| `terms`       | Optional. Look up specific search terms instead of the full genre ranking.                                                                      |
| `from` / `to` | `YYYY-MM-DD`. Default is the last complete Sun–Sat week (UTC).                                                                                  |
| `granularity` | `WEEKLY_SUN_SAT` (default) or `MONTHLY`.                                                                                                        |
| `limit`       | Max rows, 1–5000. Default 50.                                                                                                                   |

Each row includes:

| Field                     | Meaning                                      |
| ------------------------- | -------------------------------------------- |
| `searchTerm`              | The query                                    |
| `rankInGenre`             | Volume rank inside the genre (`1` = highest) |
| `searchPopularityInGenre` | 1–100 inside the genre                       |
| `searchPopularity1to100`  | 1–100 across all genres in that country      |
| `searchPopularity1to5`    | Coarse tier, `5` = most popular              |

Weekly windows must start on a Sunday. Monthly windows use calendar months. Timezone is UTC.

### Look up specific keywords

Pass `terms` to score known App Store queries instead of the full genre ranking. The term must appear in that country + genre that week; otherwise the row is omitted.

```bash curl theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST "https://api.appeeky.com/v1/connect/apple-ads/insights/search-term-popularity" \
  -H "X-API-Key: YOUR_APPEEKY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "genre": "PRODUCTIVITY",
    "countries": ["US"],
    "terms": ["chatgpt", "vpn"]
  }'
```

This is the App Store keyword-popularity path. Phrase SEARCH below is a different catalog (brand / business names).

***

## Keyword Suggestions

Apple-suggested keywords for an advertised app, sorted by popularity. `adamId` must be an app in your Apple Ads account.

```bash curl theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST "https://api.appeeky.com/v1/connect/apple-ads/suggestions/keywords" \
  -H "X-API-Key: YOUR_APPEEKY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "adamId": "123456789",
    "countries": ["US", "GB"],
    "terms": ["task manager"],
    "limit": 20
  }'
```

`adamId` is required. Optional `terms` seed related suggestions. Each result is `{ text, popularity }` on a 0–100 scale.

***

## Phrase Popularity

`SEARCH` looks up Apple's brand/business phrase catalog (not App Store search terms). A single phrase uses `LIKE` (`%chat%` → Chatime, Chatr Mobile). Multiple phrases use exact `IN`. `SUGGESTION` needs an advertised `adamId`.

```bash curl theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST "https://api.appeeky.com/v1/connect/apple-ads/suggestions/phrases" \
  -H "X-API-Key: YOUR_APPEEKY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "queryType": "SEARCH",
    "phrases": ["chat"]
  }'
```

***

## Impression Share

How often your ads appeared for a search term, out of all searches on that term in the same country. Requires an `adamId` you advertise.

```bash curl theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST "https://api.appeeky.com/v1/connect/apple-ads/insights/impression-share" \
  -H "X-API-Key: YOUR_APPEEKY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "adamId": "123456789",
    "countries": ["US"],
    "reportType": "ALL_SLOTS",
    "limit": 50
  }'
```

Share is exact from 1–90%. Above 90% Apple returns the 91–100% bucket. Each row also includes `rank` (`1` = highest share) and `searchPopularity1to5`.

Daily windows are capped at 30 days. Default is the last 14 complete UTC days.

***

## What this is not

* Not exact search volume (impression counts). Scores are relative.
* Not organic rank or difficulty. Pair with [Keyword Metrics](/docs/keyword-metrics) and [Keyword Rankings](/docs/get-keyword-ranks).
* Not a public keyword database. You still need an Apple Ads account.
* Not a replacement for [search terms reports](/docs/apple-search-ads-reports), which show queries that actually triggered *your* ads.

Campaign Management API v5 remains in use for campaigns, keywords, and reports until Apple retires it on **26 January 2027**.