# App Store Top Charts Tracker — Free, Paid & Grossing (`northbell/app-store-top-charts-tracker`) Actor

Apple App Store top charts for any country, genre and device: top free, top paid and top grossing, up to 100 apps per chart. Run it again or on a schedule to get rank changes, new entries and apps that dropped out since the last run. No login.

- **URL**: https://apify.com/northbell/app-store-top-charts-tracker.md
- **Developed by:** [Northbell](https://apify.com/northbell) (community)
- **Categories:** Marketing, Developer tools
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.40 / 1,000 chart entries

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## App Store Top Charts Tracker — Free, Paid & Grossing

Give it countries, charts and (optionally) genres — and get one clean row per app in the Apple App Store **top free, top paid or top grossing** chart: **rank, app name, developer, price, category, release date, link and icon**, for iPhone or iPad, up to 100 apps per chart. **$0.50 per 1,000 apps**, no login, no API key.

**Try it now — the input is already filled in.** Press **Start**: the US iPhone top-free chart on the App Store, 100 apps in about 6 seconds, for about $0.06.

| `rank` | `name` | `developer` | `category` | `releasedAt` |
| --- | --- | --- | --- | --- |
| 4 | ChatGPT | OpenAI OpCo, LLC | Productivity | 2023-05-18 |
| 7 | Netflix Game Controller | Netflix, Inc. | Entertainment | 2023-08-07 |
| 8 | Twitch: Live Streaming | Twitch Interactive, Inc. | Photo & Video | 2011-10-26 |

Run it again and every row says how the app moved (`previousRank`, `rankChange`, `isNewInChart`), with a free summary row per chart. On our account, 9 hours after the previous read, Netflix Game Controller had risen from 48 to 7, Twitch from 47 to 8, and 8 apps were new in the top 100. Pick top paid or top grossing, genres, iPad, or several countries in one run.

Run it again — or put it on a daily schedule — and every row also tells you **what moved since the last run**: the previous rank, how many places the app rose or fell, and whether it is a **new entry**. Each chart also gets a free summary row with the new entries, the apps that **dropped out**, and the five biggest risers and fallers. Apple only shows you today's chart; this keeps yesterday's.

### What you get

Two kinds of rows, told apart by `type`. A `chart-entry` row is one app in one chart (charged); a `chart-summary` row is one per chart (free).

| Field | What it is |
|---|---|
| `country`, `device`, `chart`, `genre`, `genreId` | which chart: country code, `iphone` or `ipad`, `top-free` / `top-paid` / `top-grossing`, and the genre (`All apps` and `genreId` `null` for the overall chart) |
| `rank` | position in the chart, 1 = top |
| `previousRank`, `rankChange`, `isNewInChart`, `previousRunAt` | the change since your previous run of the same chart. `rankChange` is positive when the app moved **up**. `null` on the first run |
| `appId`, `name`, `developer`, `developerId`, `bundleId` | the app and who makes it |
| `price`, `currency` | price in the store's own currency (`0` = free). For top grossing this is the app's own price, not its revenue |
| `category`, `categoryId`, `releasedAt` | the app's own primary category and its release date (UTC) |
| `url`, `iconUrl` | the App Store page (no tracking parameters) and the app icon at 512 px |
| `feedUpdatedAt`, `observedAt` | when Apple generated the copy of the chart this run received (it caches charts for a few minutes), and when the run started |

`chart-summary` rows add `entries` (apps read), `hasBaseline`, `previousRunAt`, `newEntryCount`, `droppedOutCount`, `newEntries` (`rank`, `appId`, `name`), `droppedOut` (`previousRank`, `appId`, `name`), `biggestRisers` and `biggestFallers` (top 5 by `rankChange`, with `rank`, `previousRank`, `rankChange`) and a `note`. On the first run of a chart `hasBaseline` is `false`, `previousRunAt`, `newEntryCount`, `droppedOutCount`, `newEntries`, `droppedOut`, `biggestRisers` and `biggestFallers` are `null`, and `note` says to run it again.

### Use it for

- **Competitor and market watching** — see which apps break into the top charts of your genre or country, and which ones fall out
- **Launch and campaign tracking** — schedule it daily for a country and see if a release or a marketing push moved a rank
- **Trend research** — compare the same genre across countries, or free against grossing, to find what pays where

### Input

```json
{ "countries": ["us", "gb", "jp"], "charts": ["top-free", "top-grossing"], "genres": ["Health & Fitness", "Games"], "limit": 100, "device": "iphone" }
```

Genres can be names (`Health & Fitness`, `Games`, `Productivity`, `Finance`, `Education`, `Games: Puzzle` …, case does not matter) or App Store genre ids (6000–6027, 7001–7019). Leave `genres` empty for the overall chart. Every combination of country × chart × genre is read as its own chart.

The previous ranks are remembered per country, chart, genre and device in a named key-value store in your Apify account, so the second run of the same Actor already shows movement. Schedule it (Apify → Schedules) at the same time every day for a clean history.

### Pricing

**$0.50 per 1,000 apps** (one chart of 100 apps = $0.05), plus $0.01 per run. Summary rows and error rows (a country or chart that could not be read) are free. The $0.01 run-start fee is the one charge every run pays, even one that returns nothing. For example, 10 countries × 3 charts × 100 apps = 3,000 apps = $1.50 + $0.01.

### Notes

- Public data only: the same top-chart lists Apple publishes for the App Store. No login. `developer` is the seller name Apple publishes with each app; nothing else about people is read.
- Apple returns **at most 100 apps per chart**, so `limit` stops at 100, and some charts, mostly top paid, come back with a few fewer (97–99 seen). Rank is the position in Apple's list.
- Top grossing ranks apps by revenue but Apple does not publish the amounts. You get the order, not the money.
- iPhone and iPad have separate charts; the iPad charts list apps that are popular on iPad.
- Genre names are checked against the list of genres Apple really has a chart for. Apple would silently return the overall chart for an id it does not know, so unknown ids are rejected. Catalogs and Stickers have no chart. `Games: Puzzle`, `Games: Action` and the other games subgenres are charts of games; their `category` is `Games`. The `Magazines & Newspapers` chart mixes in apps from News, Books and other categories, so there `category` often differs from `genre`.
- Countries are two-letter App Store codes (`us`, `gb`, `jp`, `de`, `kr`, `br` …; `uk` is accepted as `gb`). A country Apple has no store for returns a free error row.
- `previousRank`, `rankChange`, `isNewInChart` and `previousRunAt` are `null` on the first run of a chart, and `genreId` is `null` for the overall chart. `previousRank` and `rankChange` are also `null` for an app that was not in the chart last time. If you read **more** apps per chart than last time, `isNewInChart` is `null` for the ranks below your previous depth, because there is no way to tell whether they are new. Reading fewer never reports drop-outs below the new depth.
- Charts move through the day, and Apple serves a cached copy for a few minutes (`feedUpdatedAt` is when that copy was made), so run it at about the same time of day and do not expect movement between two runs a few minutes apart.
- A run reads one chart every second or two. If Apple refuses several charts in a row, the run stops, adds one error row with `skippedCharts` (how many were left) and tells you to run it again later.
- In the Apify Console the two views (Chart entries, Chart summaries) each list every row and only fill the columns that row type has. To see only summaries, filter on `type` = `chart-summary`.

To track **where your own app ranks for keywords** and its rating over time, see [App Store Rank & Review Watch](https://apify.com/northbell/app-store-rank-and-review-watch). To **search apps and read app details**, see [App Store Scraper](https://apify.com/northbell/app-store-scraper).

### For AI agents

`{"countries": ["us"], "charts": ["top-free"], "genres": ["Health & Fitness"], "limit": 10}` returns one `chart-summary` row and 10 `chart-entry` rows with the rank, app, developer, price and category. Rows have `type`: `chart-entry`, `chart-summary` or `error`. Run the same input again later to get `previousRank`, `rankChange` (positive = moved up) and `isNewInChart` on every entry.

# Actor input Schema

## `countries` (type: `array`):

One App Store country per line, as a two-letter code: us, gb, jp, de, fr, kr, br, in … (the United Kingdom is gb). Every country is a separate chart.

## `charts` (type: `array`):

Which charts to read: top free, top paid and/or top grossing. Each one is read for every country and genre you give.

## `genres` (type: `array`):

Optional. One genre per line, by name (Health & Fitness, Games, Productivity, Finance, Education, Games: Puzzle …) or App Store genre id (6000-6027, 7001-7019). Leave empty for the overall chart of all apps.

## `limit` (type: `integer`):

How many apps to read from the top of each chart. Apple returns at most 100 per chart, so 100 is the maximum.

## `device` (type: `string`):

Read the iPhone charts or the separate iPad charts.

## Actor input object example

```json
{
  "countries": [
    "us"
  ],
  "charts": [
    "top-free"
  ],
  "limit": 100,
  "device": "iphone"
}
```

# Actor output Schema

## `entries` (type: `string`):

Every app in every chart with its rank, the rank at your last run, price, developer and category.

## `summaries` (type: `string`):

Per chart: new entries, apps that dropped out, biggest risers and fallers since your last run.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "countries": [
        "us"
    ],
    "charts": [
        "top-free"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("northbell/app-store-top-charts-tracker").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "countries": ["us"],
    "charts": ["top-free"],
}

# Run the Actor and wait for it to finish
run = client.actor("northbell/app-store-top-charts-tracker").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "countries": [
    "us"
  ],
  "charts": [
    "top-free"
  ]
}' |
apify call northbell/app-store-top-charts-tracker --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,northbell/app-store-top-charts-tracker"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/dd0U8zhnuFzQHGQNw/builds/tz80C6Y8WdQkJtLb5/openapi.json