# Google Play Top Charts, Collections & Events Tracker (`xyrelith-data/google-play-charts`) Actor

Track Google Play top free, grossing and paid charts by country, category and device, plus editorial collections and in-app live events. Returns ranks, app metadata, pricing, ratings, in-app purchase signals and rank movement between runs.

- **URL**: https://apify.com/xyrelith-data/google-play-charts.md
- **Developed by:** [Xyrelith Data](https://apify.com/xyrelith-data) (community)
- **Categories:** Automation, E-commerce, Other
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.49 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.
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

## Google Play Top Charts, Collections & Events Tracker

Track what is rising on Google Play: ranked top-chart entries, editorial placements and in-app live events. The actor reads public storefront pages and ranking data by country, language, section, device, chart and category, without a Google account, cookie or API key.

Use it for ASO research, launch monitoring, category analysis, competitive placement checks and a daily snapshot of rank movement.

### What this actor does

- **Charts** — returns ranked apps from Top free, Top grossing and Top paid charts for a chosen market and category. Rankings go up to 200 places.
- **Collections** — returns the editorial clusters shown on the Apps, Games and Kids pages: cluster title, subtitle, position, placement type and the ranked list of apps inside.
- **Events** — returns the public "Events & offers" entries on an app page: event title, description, type, start and end dates, image and app context.
- **Rank movement** — when you run the same chart twice, the second run adds the previous rank, the change and a movement label (`up`, `down`, `same`, `new`).
- **Device-aware browsing** — watch faces and watch apps have their own charts and collections; tablet, TV, Chromebook and car pages have device-specific editorial collections.

### Output

Every record includes `recordType`, `country`, `language`, `sourceUrl` and `scrapedAt` (UTC ISO). Empty fields are omitted instead of written as `null`.

#### Chart entries (`recordType: chartEntry`)

`chart`, `chartLabel`, `rank`, `appId`, `title`, `developer`, `developerId`, `developerUrl`, `icon`, `rating`, `ratingText`, `ratingCount`, `reviewCount`, `price`, `currency`, `priceText`, `free`, `originalPrice`, `discountText`, `genre`, `installs`, `minInstalls`, `maxInstalls`, `contentRating`, `containsAds`, `offersIAP`, `IAPRange`, `version`, `updated`, `androidVersion`, `released`, `summary`, `headerImage`, `section`, `device`, `category`, `categoryName`, `appUrl`, `chartUrl`, `previousRank`, `rankChange`, `rankMovement`.

`previousRank`, `rankChange` and `rankMovement` appear only after the same chart has been seen in an earlier run. `containsAds` and the app-page fields require **Enrich with app details**; without it, the chart row still carries the rank, title, developer, icon, rating, price, category and in-app purchase range.

#### Collections (`recordType: collection`)

`clusterTitle`, `clusterSubtitle`, `clusterType` (`curated`, `earlyAccess`, `events`, `new`, `popular`), `clusterPosition`, `appCount`, `apps[]`, `pageUrl`.

Each app inside `apps[]` has `position`, `appId`, `title`, `developer`, `icon`, `rating`, `genre`, `installs`, `contentRating`, `price`, `currency`, `priceText`, `free`, `offersIAP`, `IAPRange` and `appUrl`.

#### Events (`recordType: event`)

`appId`, `appTitle`, `developer`, `icon`, `eventId`, `eventTitle`, `eventDescription`, `eventType`, `startDate`, `endDate`, `imageUrl`, `appUrl`, `eventUrl`.

### Input

| Field | Default | What it does |
|---|---|---|
| `mode` | `charts` | `charts`, `collections` or `events`. |
| `country` | `us` | Storefront country. Changes ranks, prices, availability and which apps are shown. 57 markets are listed. |
| `language` | `en` | Language for titles, genres, descriptions and event text. 33 languages are listed. |
| `section` | `games` | `apps`, `games` or `kids`. It scopes the category list and the default all-content page. |
| `device` | `phone` | `phone`, `tablet`, `tv`, `chromebook`, `watch` or `car`. Watch uses watch-face/watch-app charts; the other devices are used for device-specific collections. |
| `chart` | `topFree` | `topFree`, `topGrossing` or `topPaid`. |
| `category` | `all` | All categories, or one of 60 app, game, kids and watch categories. |
| `maxRank` | `100` | Highest chart position to return, 1–200. |
| `includeDetails` | `true` | Adds app-page fields (rating count, install range, developer ID/contact, version, update date, ads flag, summary). One extra request per chart row. |
| `trackRankChanges` | `true` | Compares the chart with this actor's previous run for the same country, language, section, device, category and chart. |
| `maxClusters` | `20` | Maximum editorial collections to return (1–80). |
| `maxAppsPerCluster` | `20` | Maximum apps in each collection (1–60). |
| `appIds` | `[]` | Package names or Google Play app links for `events` mode. |
| `maxEventsPerApp` | `10` | Maximum events to return per app (1–50). |

#### Example: top free games in the United States

```json
{
  "mode": "charts",
  "country": "us",
  "language": "en",
  "section": "games",
  "chart": "topFree",
  "category": "all",
  "maxRank": 50
}
```

#### Example: paid puzzle apps in the United Kingdom

```json
{
  "mode": "charts",
  "country": "gb",
  "language": "en",
  "section": "games",
  "device": "phone",
  "chart": "topPaid",
  "category": "GAME_PUZZLE",
  "maxRank": 100,
  "includeDetails": true
}
```

#### Example: daily editorial placements for games

```json
{
  "mode": "collections",
  "country": "us",
  "language": "en",
  "section": "games",
  "maxClusters": 10,
  "maxAppsPerCluster": 20
}
```

#### Example: events on two games

```json
{
  "mode": "events",
  "country": "us",
  "language": "en",
  "appIds": ["com.supercell.clashofclans", "com.roblox.client"],
  "maxEventsPerApp": 10
}
```

### Use cases

- Watch which apps enter, leave or move inside a country's Top free or Top paid chart.
- Compare category strength before choosing an ASO keyword or launch market.
- Track whether an app holds an editorial placement on the Apps or Games page.
- Collect a publisher's chart footprint across markets and categories.
- Monitor live events and offers for games or seasonal campaigns.
- Build a daily ASO snapshot for dashboards, alerts or research notebooks.

### Data source

The actor reads the public Google Play web storefront (`play.google.com`) and the chart list that the storefront loads for a category. Rankings, prices, genres and dates are shown in the storefront's own country and language settings. Event pages are public. No login, cookie or Google API key is used, and no proxy is needed.

### Limitations

- Google publishes **one shared ranking** for phone, tablet, TV, Chromebook and car; only watch-related categories have separate rankings. The `device` value is still recorded, and device-specific **collections** are available for tablet, TV, Chromebook and car.
- Each chart is capped by Google at 200 entries. A category with fewer apps returns fewer rows.
- Google localises titles, genres, prices and event text by `country` and `language`; two locales can show different names for the same app.
- Rank movement needs the same chart configuration in a previous run. A first-ever run has no previous snapshot, so movement fields are omitted.
- Editorial collections are whatever Google currently publishes. Google changes, adds and removes clusters without notice, and some pages have no collections in a given market.
- Only apps with an "Events & offers" section return event rows. Many apps have none.
- `containsAds` is shown only when the app page displays an ads label. Apps with no label omit the field rather than guessing.

### FAQ

**Do I need a Google account or API key?**
No. The actor uses public storefront pages and needs no credentials.

**Can I track more than one country?**
Run the actor once per country with a schedule, or call it from your own workflow. Each run writes rows for the selected market.

**How do I get rank changes?**
Keep `trackRankChanges` on and run the same country, language, section, device, category and chart again. The actor stores the last snapshot in its key-value store and adds `previousRank`, `rankChange` and `rankMovement` to the new rows.

**Why did a chart return fewer than `maxRank` rows?**
Google's category chart can be shorter than 200 entries in smaller markets or narrow categories.

**Why are some fields missing on a chart row?**
Store cards do not carry every app-page field. Turn on **Enrich with app details** to fill rating count, install range, developer contact, version, update date, summary and the ads label. Fields Google does not publish for an app are omitted, never invented.

**Do collections include early access or pre-registration apps?**
When Google shows an open-beta, "Be the first to play" or pre-registration cluster, it is returned as a collection with `clusterType: "earlyAccess"`.

**Can I get events for apps that are not in a chart?**
Yes. `events` mode takes any package names or Play app links in `appIds`.

**Does this actor work for all Google Play markets?**
57 storefront countries and 33 languages are exposed. A market or category with no published chart for the selected combination returns an empty result with a status message.

**Is this affiliated with Google?**
No. This is an independent tool that reads public Google Play pages and is not affiliated with or endorsed by Google.

**Empty fields are omitted.** If Google does not provide a value for an app, the field is left out of that record instead of being filled with a placeholder.

# Actor input Schema

## `mode` (type: `string`):

What to collect: ranked charts, editorial collections, or in-app events.

## `country` (type: `string`):

Google Play storefront country. Affects chart rankings, prices and availability.

## `language` (type: `string`):

Language for app titles, genres and event text.

## `section` (type: `string`):

Apps, games or kid-friendly content. Category options are filtered by this section in the code.

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

Store surface. Watch charts use watch-face/watch-app categories; collections use the device-specific App Store home. Google publishes one shared ranking for phone, tablet, TV, Chromebook and car.

## `chart` (type: `string`):

Which top chart to read.

## `category` (type: `string`):

Category to read. "All categories" uses the section default: all apps, all games or kids.

## `maxRank` (type: `integer`):

Highest chart position to return (1-200). Google publishes up to 200 ranked entries per chart.

## `includeDetails` (type: `boolean`):

Fetch each app page for rating count, installs range, developer ID/contact, version, update date, ads flag and summary. Adds one request per chart row.

## `trackRankChanges` (type: `boolean`):

Compare this run with the actor's previous run for the same country, section, device, category and chart. Adds previousRank, rankChange and rankMovement.

## `maxClusters` (type: `integer`):

Maximum editorial collections to return in collections mode (1-80).

## `maxAppsPerCluster` (type: `integer`):

Maximum apps to include in each editorial collection (1-60).

## `appIds` (type: `array`):

Package names or Google Play app URLs to check for Events & offers (mode=events).

## `maxEventsPerApp` (type: `integer`):

Maximum Events & offers entries to return per app (1-50).

## Actor input object example

```json
{
  "mode": "charts",
  "country": "us",
  "language": "en",
  "section": "games",
  "device": "phone",
  "chart": "topFree",
  "category": "all",
  "maxRank": 1,
  "includeDetails": false,
  "trackRankChanges": true,
  "maxClusters": 3,
  "maxAppsPerCluster": 10,
  "appIds": [
    "com.supercell.clashofclans"
  ],
  "maxEventsPerApp": 3
}
```

# Actor output Schema

## `items` (type: `string`):

Dataset containing Google Play chart entries, collections and events.

# 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 = {
    "mode": "charts",
    "country": "us",
    "language": "en",
    "section": "games",
    "device": "phone",
    "chart": "topFree",
    "category": "all",
    "maxRank": 1,
    "includeDetails": false,
    "trackRankChanges": true,
    "maxClusters": 3,
    "maxAppsPerCluster": 10,
    "appIds": [
        "com.supercell.clashofclans"
    ],
    "maxEventsPerApp": 3
};

// Run the Actor and wait for it to finish
const run = await client.actor("xyrelith-data/google-play-charts").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 = {
    "mode": "charts",
    "country": "us",
    "language": "en",
    "section": "games",
    "device": "phone",
    "chart": "topFree",
    "category": "all",
    "maxRank": 1,
    "includeDetails": False,
    "trackRankChanges": True,
    "maxClusters": 3,
    "maxAppsPerCluster": 10,
    "appIds": ["com.supercell.clashofclans"],
    "maxEventsPerApp": 3,
}

# Run the Actor and wait for it to finish
run = client.actor("xyrelith-data/google-play-charts").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 '{
  "mode": "charts",
  "country": "us",
  "language": "en",
  "section": "games",
  "device": "phone",
  "chart": "topFree",
  "category": "all",
  "maxRank": 1,
  "includeDetails": false,
  "trackRankChanges": true,
  "maxClusters": 3,
  "maxAppsPerCluster": 10,
  "appIds": [
    "com.supercell.clashofclans"
  ],
  "maxEventsPerApp": 3
}' |
apify call xyrelith-data/google-play-charts --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,xyrelith-data/google-play-charts"
        }
    }
}
```

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/2bieGJmDSQHEkqcl9/builds/l7qfZ0H2LUJ6X0uMc/openapi.json
