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 requires daily scraping to be active for the keyword. Data points are only available for dates when the keyword was actively tracked and scraped. Use POST /v1/keywords/track or the auto-tracking from GET /v1/keywords/ranks to ensure a keyword is in the scraping pipeline.
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 |
