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

# New

> Apps currently ranked

```
GET /v1/discover/new-number-1
```

Returns apps that are currently ranked **#1** in their primary App Store category. The endpoint fetches the overall Top Free chart from Apple RSS, groups apps by their primary genre, and picks the top-ranked app for each category.

## Query Parameters

| Name    | Type   | Default | Description                                    |
| ------- | ------ | ------- | ---------------------------------------------- |
| country | string | `us`    | ISO country code (e.g. `us`, `gb`, `de`, `jp`) |

## Code Examples

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X GET "https://api.appeeky.com/v1/discover/new-number-1?country=us" \
    -H "X-API-Key: YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await fetch(
    "https://api.appeeky.com/v1/discover/new-number-1?country=us",
    {
      headers: {
        "X-API-Key": "YOUR_API_KEY",
      },
    }
  );

  const { data } = await response.json();
  data.apps.forEach((app) => {
    console.log(`#1 in ${app.category}: ${app.title}`);
  });
  ```

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

  response = requests.get(
      "https://api.appeeky.com/v1/discover/new-number-1",
      params={"country": "us"},
      headers={"X-API-Key": "YOUR_API_KEY"},
  )

  data = response.json()["data"]
  for app in data["apps"]:
      print(f"#1 in {app['category']}: {app['title']}")
  ```
</CodeGroup>

## Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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

1. Fetches the **Top Free** overall chart from Apple RSS for the specified country (up to 200 apps).
2. Each app's **primary genre** is determined from its iTunes metadata.
3. Apps are grouped by genre, and the **highest-ranked** app in each group becomes the category's #1.
4. Results are returned as a flat list — one app per category.

<Note>
  **`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.
</Note>

<Tip>
  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.
</Tip>

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