# Personal Game Chart Monitor (`nullwave/personal-game-chart-monitor`) Actor

Monitor a Google Play or App Store game chart. The first run creates your baseline; later runs return newly observed chart entries.

- **URL**: https://apify.com/nullwave/personal-game-chart-monitor.md
- **Developed by:** [null wave](https://apify.com/nullwave) (community)
- **Categories:** Developer tools
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per usage

This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have.

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

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Personal Game Chart Monitor

Track Google Play and Apple App Store game rankings by country and discover apps that newly appear in a top chart. Personal Game Chart Monitor saves your first top-100 result as a private baseline, then compares each later run with the previous successful observation and returns only newly observed chart entries.

Use it as a lightweight Google Play ranking tracker, App Store chart monitor, game-discovery feed, or scheduled data source for your own integrations. No historical database is shared between users: each user builds a baseline from the charts they choose to monitor.

### What this Actor does

1. Downloads up to 100 apps from the selected store, country, category, and chart.
2. Validates the result before replacing the saved baseline.
3. On the first successful run, saves the baseline and returns zero new entries.
4. On later runs, returns apps whose app IDs were not present in the previous successful snapshot.
5. Saves the current validated snapshot for the next comparison.

An app that leaves the top 100 and later returns can therefore be reported as a new chart entry again. This Actor detects changes between observations; it does not claim to know an app's first-ever appearance in store history.

### Supported chart options

| Input | Supported values |
| --- | --- |
| `store` | `google-play`, `app-store` |
| `country` | Two-letter uppercase country code, such as `US`, `JP`, or `GB` |
| `category` | `GAME` by default; the App Store currently supports `GAME` only |
| `chart` | `top-free`, `top-paid`, `top-grossing` |

Google Play results are localized using the selected country. App Store results use Apple's country-specific game-chart feed. Availability and ordering are determined by the stores at the time of each run.

### Quick start

Run the Actor once with your desired scope:

```json
{
  "store": "google-play",
  "country": "US",
  "category": "GAME",
  "chart": "top-free"
}
```

The first run intentionally returns `isBaseline: true` and `newEntryCount: 0`. Run it again later with the same input, or save it as an Apify task and schedule it daily. Use a different input scope to maintain an independent baseline for another country, store, category, or chart.

### Output

Each run writes one summary object to the default Dataset and to the `OUTPUT` record in the default Key-Value Store:

```json
{
  "status": "ok",
  "scope": {
    "store": "google-play",
    "country": "US",
    "category": "GAME",
    "chart": "top-free"
  },
  "observedAt": "2026-08-26T13:38:23.764Z",
  "appCount": 100,
  "isBaseline": false,
  "newEntryCount": 1,
  "entries": [
    {
      "appId": "com.example.game",
      "rank": 42,
      "title": "Example Game",
      "developer": "Example Studio",
      "url": "https://play.google.com/store/apps/details?id=com.example.game",
      "event": "new_chart_entry",
      "firstObservedAt": "2026-08-26T13:38:23.764Z"
    }
  ]
}
```

`firstObservedAt` is when this monitor first observed the app as absent from the previous snapshot and present in the current one. It is not the app's release date and is not proof of its first-ever chart appearance. When store release-date data is available, an entry can also include `releaseDate` and `daysSinceRelease`.

### Schedule recurring checks

For continuous monitoring, save your configured input as an Apify task and attach a daily schedule. Keep the same scope on every run so the Actor compares the intended chart. The result can then be consumed from the Dataset, Key-Value Store, Apify API, webhook, or another integration.

For API use, run `nullwave/personal-game-chart-monitor` with the same JSON input through the Apify Actor API. Your first API run creates the baseline just like a Console run.

### Important limitations

- The Actor compares the current top 100 with the previous successful top-100 snapshot; it does not reconstruct earlier history.
- A first run cannot identify prior entries, so returning zero new entries is deliberate.
- Store charts can change between requests and may differ by country.
- Invalid or unexpectedly small snapshots are rejected instead of overwriting a valid baseline.
- Changing any scope field starts or resumes a separate baseline for that scope.

### FAQ

#### Why is my first result empty?

There is no earlier observation to compare with. The first run saves a baseline and still writes a non-empty summary row to the Dataset. Later runs can then identify newly present app IDs.

#### Does this return newly released games?

Not necessarily. It returns games newly observed in the selected chart since the previous successful run. A game can be old and still enter or re-enter a chart.

#### Can I monitor multiple countries?

Yes. Run or schedule the Actor separately for each country and chart combination. Each scope keeps an independent baseline.

# Actor input Schema

## `store` (type: `string`):

Mobile app store to monitor.

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

Two-letter country code, for example US or JP.

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

Game category to monitor. App Store currently supports GAME.

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

Ranking chart to compare.

## Actor input object example

```json
{
  "store": "google-play",
  "country": "US",
  "category": "GAME",
  "chart": "top-free"
}
```

# Actor output Schema

## `results` (type: `string`):

The default Dataset item for this run, including newEntryCount and entries.

## `summary` (type: `string`):

The same result as a single JSON object in the default Key-Value Store.

# 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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("nullwave/personal-game-chart-monitor").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 = {}

# Run the Actor and wait for it to finish
run = client.actor("nullwave/personal-game-chart-monitor").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 '{}' |
apify call nullwave/personal-game-chart-monitor --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,nullwave/personal-game-chart-monitor"
        }
    }
}

```

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/sfew7PK3TB1IOf0kr/builds/uKk52nk3OQ3jW2l2G/openapi.json