GET /v1/apps/:id/keywords/trends
Path Parameters
| Name | Type | Description |
|---|
| id | string | Apple App ID (numeric, e.g. 1617391485) |
Query Parameters
| Name | Type | Required | Default | Description |
|---|
| keyword | string | Yes | — | Search keyword (min 2 characters) |
| country | string | No | us | ISO country code (e.g. us, gb, de, jp) |
| device | string | No | iphone | iphone or ipad |
| days | number | No | 30 | Number of days of history to return (7–90) |
Code Examples
curl "https://api.appeeky.com/v1/apps/1617391485/keywords/trends?keyword=puzzle+game&country=us&days=30" \
-H "X-API-Key: YOUR_API_KEY"
Response
{
"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
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.
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.
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 |
