> ## 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.

# Trending Keywords

> Keywords with the fastest-growing reach in the App Store, ranked by growth percentage

```
GET /v1/keywords/trending
```

Returns keywords whose reach (measured by the top-ranking app's review count) has grown the most over a given period. Use this to identify rising search trends and high-momentum keywords for ASO.

## Query Parameters

| Name     | Type   | Default | Description                                                                      |
| -------- | ------ | ------- | -------------------------------------------------------------------------------- |
| platform | string | `apple` | `apple` (default) or `google` for Google Play — see [Platforms](/docs/platforms) |
| country  | string | `us`    | ISO country code (e.g. `us`, `gb`, `de`)                                         |
| days     | number | `7`     | Trend window in days (1-30)                                                      |
| limit    | number | `50`    | Max keywords to return (1-100)                                                   |

## Examples

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl "https://api.appeeky.com/v1/keywords/trending?country=us&days=7&limit=10" \
    -H "X-API-Key: YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const res = await fetch(
    "https://api.appeeky.com/v1/keywords/trending?country=us&days=7&limit=10",
    { headers: { "X-API-Key": "YOUR_API_KEY" } }
  );
  const { data } = await res.json();
  console.log(`${data.total} trending keywords in ${data.period}`);
  for (const kw of data.keywords) {
    console.log(`${kw.keyword}: +${kw.growthPercent}% growth`);
  }
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import requests

  res = requests.get(
      "https://api.appeeky.com/v1/keywords/trending",
      params={"country": "us", "days": 7, "limit": 10},
      headers={"X-API-Key": "YOUR_API_KEY"},
  )
  data = res.json()["data"]
  for kw in data["keywords"]:
      print(f"{kw['keyword']}: +{kw['growthPercent']}% (vol={kw['volumeScore']})")
  ```
</CodeGroup>

## Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": {
    "country": "us",
    "period": "7d",
    "keywords": [
      {
        "keyword": "xai",
        "growthPercent": 330.5,
        "maxReach": 10509533,
        "currentReach": 10509533,
        "volumeScore": 86,
        "resultCount": 42,
        "difficulty": 88
      },
      {
        "keyword": "meditation",
        "growthPercent": 145.2,
        "maxReach": 3814828,
        "currentReach": 3814828,
        "volumeScore": 72,
        "resultCount": 48,
        "difficulty": 65
      }
    ],
    "total": 77
  }
}
```

## Response Fields

### Top Level

| Field      | Type               | Description                                       |
| ---------- | ------------------ | ------------------------------------------------- |
| `country`  | string             | ISO country code                                  |
| `period`   | string             | Trend window (e.g. `7d`, `14d`, `30d`)            |
| `keywords` | TrendingKeyword\[] | Keywords sorted by growth percentage (descending) |
| `total`    | number             | Total trending keywords found (before limit)      |

### TrendingKeyword

| Field           | Type         | Description                                               |
| --------------- | ------------ | --------------------------------------------------------- |
| `keyword`       | string       | The keyword                                               |
| `growthPercent` | number       | Percentage growth in reach over the period                |
| `maxReach`      | number       | Maximum reach (top app review count) in current window    |
| `currentReach`  | number       | Most recent reach value                                   |
| `volumeScore`   | number\|null | Estimated search volume (0-100)                           |
| `resultCount`   | number       | Number of apps returned by iTunes Search for this keyword |
| `difficulty`    | number\|null | Ranking difficulty score (0-100)                          |

## How It Works

The trending algorithm compares keyword reach between two time windows:

1. **Current window**: Last `days` days
2. **Previous window**: The `days` before that

**Reach** is measured by `top_app_reviews` — the review count of the #1 ranking app for each keyword. This is a strong proxy for keyword popularity because high-traffic keywords attract apps with large user bases.

A keyword is "trending" when its max reach in the current window exceeds the previous window. The growth percentage is: `(current - previous) / previous × 100`.

<Note>
  Trending data is computed from the tracked keyword set. Add new keywords with [`POST /v1/keywords/track`](/docs/track-keyword) to expand coverage.
</Note>

## Errors

| Status | Code            | When                     |
| ------ | --------------- | ------------------------ |
| 500    | INTERNAL\_ERROR | Failed to compute trends |