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

# Keyword Trends

> Historical keyword rank trends for an app over time

```
GET /v1/apps/:id/keywords/trends
```

Returns historical rank data for a specific keyword and app over a configurable time window. Use this to track how your keyword rankings change over time and measure the impact of ASO optimizations.

***

## Path Parameters

| Name | Type   | Description                                                                              |
| ---- | ------ | ---------------------------------------------------------------------------------------- |
| id   | string | App ID — numeric for Apple (`1617391485`), package name for Google (`com.spotify.music`) |

## Query Parameters

| Name     | Type   | Required | Default  | Description                                                                      |
| -------- | ------ | -------- | -------- | -------------------------------------------------------------------------------- |
| keyword  | string | Yes      | —        | Search keyword (min 2 characters)                                                |
| platform | string | No       | `apple`  | `apple` (default) or `google` for Google Play — see [Platforms](/docs/platforms) |
| country  | string | No       | `us`     | ISO country code (e.g. `us`, `gb`, `de`, `jp`)                                   |
| device   | string | No       | `iphone` | `iphone` or `ipad` (Apple only)                                                  |
| days     | number | No       | `30`     | Number of days of history to return (7–90)                                       |

***

## Code Examples

<CodeGroup>
  ```bash curl theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl "https://api.appeeky.com/v1/apps/1617391485/keywords/trends?keyword=puzzle+game&country=us&days=30" \
    -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/apps/1617391485/keywords/trends?keyword=puzzle+game&country=us&days=30",
    { headers: { "X-API-Key": "YOUR_API_KEY" } }
  );
  const { data } = await res.json();
  console.log(`Keyword: ${data.keyword}`);
  console.log(`7-day change: ${data.rankChange7d}`);
  console.log(`30-day change: ${data.rankChange30d}`);
  console.log(`Trend: ${data.trend}`);
  data.history.forEach((point) => {
    console.log(`  ${point.date}: rank #${point.rank}`);
  });
  ```

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

  res = requests.get(
      "https://api.appeeky.com/v1/apps/1617391485/keywords/trends",
      params={"keyword": "puzzle game", "country": "us", "days": 30},
      headers={"X-API-Key": "YOUR_API_KEY"},
  )
  data = res.json()["data"]
  print(f"Keyword: {data['keyword']}")
  print(f"7-day change: {data['rankChange7d']}")
  print(f"30-day change: {data['rankChange30d']}")
  print(f"Trend: {data['trend']}")
  for point in data["history"]:
      print(f"  {point['date']}: rank #{point['rank']}")
  ```
</CodeGroup>

***

## Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": {
    "keyword": "puzzle game",
    "appId": "1617391485",
    "country": "us",
    "history": [
      { "date": "2026-01-18", "rank": 12 },
      { "date": "2026-01-19", "rank": 11 },
      { "date": "2026-01-20", "rank": 11 },
      { "date": "2026-01-21", "rank": 9 },
      { "date": "2026-01-22", "rank": 8 },
      { "date": "2026-01-23", "rank": 8 },
      { "date": "2026-01-24", "rank": 7 },
      { "date": "2026-01-25", "rank": 6 },
      { "date": "2026-01-26", "rank": 5 },
      { "date": "2026-01-27", "rank": 5 }
    ],
    "rankChange7d": 6,
    "rankChange30d": 7,
    "trend": "improving"
  }
}
```

***

## Response Fields

| Field         | Type   | Description                                                                     |
| ------------- | ------ | ------------------------------------------------------------------------------- |
| keyword       | string | The queried keyword                                                             |
| appId         | string | Apple App ID                                                                    |
| country       | string | ISO country code used                                                           |
| history       | array  | Array of daily rank data points (see History Object below)                      |
| rankChange7d  | number | Rank change over the last 7 days. Positive = improved (rank number decreased).  |
| rankChange30d | number | Rank change over the last 30 days. Positive = improved (rank number decreased). |
| trend         | string | Overall trend direction: `"improving"`, `"declining"`, or `"stable"`            |

### History Object

| Field | Type   | Description                             |
| ----- | ------ | --------------------------------------- |
| date  | string | Date in `YYYY-MM-DD` format             |
| rank  | number | App's rank for the keyword on this date |

***

## Understanding Rank Changes

Rank change values are calculated as the **improvement in position**, not the raw difference in rank number:

* **Positive value** = rank **improved** (e.g. moved from #12 to #5 → `rankChange7d: 7`)
* **Negative value** = rank **declined** (e.g. moved from #5 to #8 → `rankChange7d: -3`)
* **Zero** = rank stayed the same

<Note>
  Historical data points are only available for dates the keyword has been tracked. Add a keyword to your tracked set with `POST /v1/keywords/track` to start collecting history; trends become richer the longer a keyword has been tracked.
</Note>

<Tip>
  **Short-term vs long-term analysis**: Use `days=7` for quick feedback on recent ASO changes (metadata updates, new screenshots, keyword tweaks). Use `days=30` or `days=90` for measuring long-term keyword strategy effectiveness and seasonal trends.
</Tip>

***

## Errors

| Status | Code             | When                              |
| ------ | ---------------- | --------------------------------- |
| 400    | INVALID\_APP\_ID | Non-numeric or missing app ID     |
| 400    | INVALID\_KEYWORD | Keyword shorter than 2 characters |
| 400    | INVALID\_DAYS    | Days value outside 7–90 range     |
| 401    | UNAUTHORIZED     | Missing or invalid API key        |
| 429    | RATE\_LIMITED    | Too many requests — slow down     |
| 500    | INTERNAL\_ERROR  | Server error fetching trend data  |