GET /v1/discover/new-number-1
Query Parameters
| Name | Type | Default | Description |
|---|
| country | string | us | ISO country code (e.g. us, gb, de, jp) |
Code Examples
curl -X GET "https://api.appeeky.com/v1/discover/new-number-1?country=us" \
-H "X-API-Key: YOUR_API_KEY"
Response
{
"data": {
"country": "us",
"apps": [
{
"category": "Sports",
"appId": "6449023896",
"title": "Olympic Games™",
"icon": "https://is1-ssl.mzstatic.com/image/thumb/Purple211/v4/a1/b2/c3/a1b2c3d4-icon/AppIcon-0-0-1x_U007emarketing-0-7-0-85-220.png/512x512bb.jpg",
"reachedAt": null
},
{
"category": "Weather",
"appId": "300048137",
"title": "AccuWeather: Weather Alerts",
"icon": "https://is1-ssl.mzstatic.com/image/thumb/Purple211/v4/d4/e5/f6/d4e5f6a7-icon/AppIcon-0-0-1x_U007emarketing-0-7-0-85-220.png/512x512bb.jpg",
"reachedAt": null
},
{
"category": "Photo & Video",
"appId": "1642763440",
"title": "Lensa: Photo Editor",
"icon": "https://is1-ssl.mzstatic.com/image/thumb/Purple211/v4/b8/c9/da/b8c9da01-icon/AppIcon-0-0-1x_U007emarketing-0-7-0-85-220.png/512x512bb.jpg",
"reachedAt": null
},
{
"category": "Social Networking",
"appId": "835599320",
"title": "Threads",
"icon": "https://is1-ssl.mzstatic.com/image/thumb/Purple211/v4/e2/f3/04/e2f30415-icon/AppIcon-0-0-1x_U007emarketing-0-7-0-85-220.png/512x512bb.jpg",
"reachedAt": null
},
{
"category": "Entertainment",
"appId": "1446075923",
"title": "Tubi: Movies & Live TV",
"icon": "https://is1-ssl.mzstatic.com/image/thumb/Purple211/v4/f5/06/17/f5061728-icon/AppIcon-0-0-1x_U007emarketing-0-7-0-85-220.png/512x512bb.jpg",
"reachedAt": null
}
]
}
}
App Object
| Field | Type | Description |
|---|
| category | string | App Store category name (e.g. Sports, Weather) |
| appId | string | Apple App ID |
| title | string | App name |
| icon | string | App icon URL (512px) |
| reachedAt | string | null | ISO timestamp of when the app first reached #1 (see note below) |
How It Works
- Fetches the Top Free overall chart from Apple RSS for the specified country (up to 200 apps).
- Each app’s primary genre is determined from its iTunes metadata.
- Apps are grouped by genre, and the highest-ranked app in each group becomes the category’s #1.
- Results are returned as a flat list — one app per category.
reachedAt is always null currently. Determining when an app first reached #1 would require storing historical chart snapshots and comparing them over time. This feature is planned for a future release once daily chart tracking is implemented.
Use this endpoint to monitor category leaders and spot emerging trends. If a new or unexpected app appears as #1 in a category, it may indicate a viral moment, seasonal trend, or major marketing push.
Caching: Responses are cached for 30 minutes per country. The underlying Apple RSS chart data is cached for 15 minutes. Cold start requests typically take 2–4 seconds.
Errors
| Status | Code | When |
|---|
| 400 | INVALID_PARAMS | Invalid country value |
| 401 | MISSING_API_KEY | No API key in the request |
| 401 | INVALID_API_KEY | Invalid or expired API key |
| 500 | FETCH_FAILED | Failed to fetch Apple RSS chart data |
