# TapTap Scraper — Games, Rankings & Reviews (`dimweaker/taptap-china-game-reviews-export`) Actor

Search TapTap China games, export Android and iOS rankings, game profiles and rating statistics, and collect player reviews with date, star and keyword filters. Download structured JSON and CSV.

- **URL**: https://apify.com/dimweaker/taptap-china-game-reviews-export.md
- **Developed by:** [Dam Dim](https://apify.com/dimweaker) (community)
- **Categories:** Social media
- **Security:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 1 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.00 / 1,000 result exporteds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

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

## TapTap Scraper — Games, Rankings & Reviews

Discover games on TapTap China and export structured game profiles, rankings, rating statistics and player reviews to JSON or CSV.

Use it to research competitors, find new games, compare player feedback, build game catalogs and connect TapTap records with your existing app database.

### Pricing

**$2 per 1,000 exported results ($0.002 each), plus $0.00005 per run.**

A result is one game in Search, Rankings or Game details mode, or one review in Reviews mode. Only rows delivered to the Dataset count. Game summaries included with reviews, game discovery used as an input, and JSON/CSV copies carry no additional charge. There is no separate platform usage fee.

For example, 100 exported reviews cost **$0.20005**, including startup. A run with no result rows incurs only the startup fee. Set a maximum spending budget in Apify to control each run's cost; collection stops when the remaining budget cannot cover another result.

### Choose your workflow

| Mode | Output |
|---|---|
| `search` | Keyword search results with game identifiers, tags, developers and rating metrics. |
| `charts` | Ranked game cards with chart name, platform, position and game metrics. |
| `games` | Enriched game profiles, company information and rating statistics. |
| `reviews` | Player reviews with feedback dimensions, plus a separate game summary table. |

For `games` and `reviews`, select games by ID/URL, keyword search or chart. Games are deduplicated by TapTap ID; chart results retain the first occurrence of each game.

#### Search for games

```json
{
  "mode": "search",
  "searchQuery": "策略",
  "maxGames": 20
}
```

#### Export a ranking

```json
{
  "mode": "charts",
  "chart": "reserve",
  "chartPlatform": "android",
  "maxGames": 20
}
```

Choose from 24 charts: popular, pre-registration, most played, new releases, best sellers, new versions, exclusive, action, strategy, idle, single-player, casual, sandbox survival, simulation, puzzle, shooter, multiplayer, anime, rhythm, story, wuxia, female-oriented, independent and roguelike. The ranking platform selector offers Android and iOS.

#### Collect reviews from games on a chart

```json
{
  "mode": "reviews",
  "gameSource": "chart",
  "chart": "strategy",
  "maxGames": 3,
  "sort": "new",
  "maxReviewsPerGame": 25,
  "maxPagesPerGame": 3
}
```

#### Enrich games found by keyword

```json
{
  "mode": "games",
  "gameSource": "search",
  "searchQuery": "原神",
  "maxGames": 3
}
```

For known games, use `"gameSource": "ids"` (the default) and `"games": ["168332", "https://www.taptap.cn/app/224347"]`.

### Input options

| Input | Description | Default |
|---|---|---|
| `mode` | `search`, `charts`, `games` or `reviews`. | `reviews` |
| `gameSource` | Game selection for `games` and `reviews`: `ids`, `search` or `chart`. | `ids` |
| `games` | TapTap China game IDs or URLs. | — |
| `searchQuery` | Game name or search keyword. | — |
| `chart` | Chart identifier, e.g. `hot`, `reserve`, `new`, `strategy`. | `hot` |
| `chartPlatform` | Ranking platform: `android` or `ios`. | `android` |
| `maxGames` | Number of unique games to select, 1–100. | 10 |
| `maxDiscoveryPages` | Search/chart pages to scan; 10 requested entries per page. | 10 |
| `sort` | Review order: `new` for latest activity, `hot` for popular. | `new` |
| `maxReviewsPerGame` | Matching reviews to export per game, 1–1,000. | 100 |
| `maxPagesPerGame` | Review pages to scan per game; 10 requested reviews per page. | 20 |
| `since` | Inclusive review activity timestamp, e.g. `2026-10-01T00:00:00Z`. | — |
| `ratings` | Review stars to select, e.g. `[1, 2]`. | All |
| `keywords` | Match any listed word in review text, case-insensitively. | All |

Review filters combine using AND and apply before the result limit. `activityAt` is the latest creation, publication or edit timestamp. Three seconds are paced between source requests; configure the run timeout to match your selected batch size.

### Data fields

#### Game profiles

- **Identity:** `gameId`, `gameTitle`, `gameUrl`, Android `packageName`, `appStoreId`, `appStoreUrl`, `supportedPlatforms`.
- **Companies:** `developers` with IDs, roles, profile URLs and websites; `supplier`, `companyRegistrationNumber`, `officialWebsite`.
- **Product information:** tags, description, developer note, supported languages, in-app purchase label, age rating, system requirements, version, version notes and dates.
- **Store data:** followers, pre-registrations, price, icons, screenshot URLs, awards and editor recommendation.
- **Discovery:** `searchQuery`, `chart`, `chartLabel`, `chartPlatform`, `rank`, `discoveryPosition`. New-version charts also include `chartEvent`.

`games` mode enriches game cards with detailed product information and review categories. Each record includes `fetchedAt` in UTC.

#### Rating statistics

| Field | Meaning |
|---|---|
| `statisticsRating` | Aggregate score from the rating statistics response, on a 10-point scale. |
| `recentRating`, `versionRating` | TapTap's recent and current-version scores. |
| `recentReviewCount`, `versionReviewCount` | Corresponding review counts. |
| `star1Count` … `star5Count` | Number of votes at each star level. |
| `starRatedCount` | Sum of the five star counts. |
| `lowStarShare` | Fraction of rated votes with 1–2 stars, from 0 to 1. |
| `reviewCategories` | Source category names, mappings and counts, such as long-form reviews. |

`reportedReviewCount` comes from the game card; `statisticsReviewCount` comes from the statistics response. `sourceHitsTotal` retains TapTap's `hits_total` counter.

#### Player reviews

Each review includes game/review IDs and URLs, stars (1–5), plain text, author display name, creation/publication/edit/activity timestamps, supports, reply count and play-stage label.

`dimensions` records the player's structured feedback, for example:

```json
[
  {"key": "gameplay", "label": "可玩性", "recommendation": "up"},
  {"key": "operation", "label": "运营服务", "recommendation": "down"}
]
```

Use `(gameId, reviewId)` as the review key and `gameId` to join reviews to the game summary table.

### Export files

| Data | Local CLI | Apify |
|---|---|---|
| Selected mode's records | `results.json`, `results.csv` | Default Dataset, `RESULTS.csv` |
| Games and rating statistics | `games.json`, `games.csv` | `GAMES.json`, `GAMES.csv` |
| Run statistics | `summary.json` | `RUN_SUMMARY` |
| Source information | `SOURCE_NOTICE.txt` | `SOURCE_NOTICE.txt` |

Review mode keeps review records and game summaries in separate tables. The run summary provides request counts, pagination counters, selection limits and any source errors. CSV files use UTF-8 with BOM; nested objects and arrays are JSON-encoded within cells.

### Run locally

Requires Python 3.11+ and [uv](https://docs.astral.sh/uv/).

```bash
cd actors/taptap
uv sync --frozen
uv run --frozen taptap-export --input examples/charts.json --output-dir outputs/charts
```

Additional inputs are available in `examples/`: search, game details, reviews, filtered reviews and discovery-to-export workflows. Use `python -m taptap_actor` for the Apify SDK entry point.

**Source:** [TapTap China](https://www.taptap.cn/). Records retain source links and public author display names; HTML is converted to plain text and timestamps to UTC.

# Actor input Schema

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

Search and Charts export game cards. Game details exports enriched game profiles. Reviews exports player reviews plus a separate game summary file.

## `gameSource` (type: `string`):

For Reviews and Game details, choose how to select games. Search and Rankings modes select their own source.

## `games` (type: `array`):

Game IDs or https://www.taptap.cn/app/ID URLs. Used when Game selection is Game IDs / URLs. Duplicate games are processed once.

## `searchQuery` (type: `string`):

Game name or keyword, for example 原神 or 策略. Required for Search mode or keyword-based game selection.

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

Choose an overall or genre-specific ranking. Used for Rankings mode and chart-based game selection.

## `chartPlatform` (type: `string`):

Platform used for the selected chart.

## `maxGames` (type: `integer`):

Maximum unique games selected per run, in input or source order.

## `maxDiscoveryPages` (type: `integer`):

Number of discovery pages to scan. Each request asks for 10 entries.

## `sort` (type: `string`):

Review order: latest activity or popular.

## `maxReviewsPerGame` (type: `integer`):

Number of reviews to export per game after filtering and deduplication.

## `maxPagesPerGame` (type: `integer`):

Number of review pages to scan per game. Each request asks for 10 reviews.

## `since` (type: `string`):

Inclusive ISO 8601 timestamp with timezone, e.g. 2026-10-01T00:00:00Z. Uses the most recent creation, publication or edit timestamp.

## `ratings` (type: `array`):

Select stars from 1 to 5, e.g. \[1, 2]. Empty selects all ratings.

## `keywords` (type: `array`):

Match any listed word, case-insensitively. Combines with rating and date filters. Empty selects all text.

## Actor input object example

```json
{
  "mode": "reviews",
  "gameSource": "ids",
  "games": [
    "https://www.taptap.cn/app/168332"
  ],
  "chart": "hot",
  "chartPlatform": "android",
  "maxGames": 10,
  "maxDiscoveryPages": 10,
  "sort": "new",
  "maxReviewsPerGame": 3,
  "maxPagesPerGame": 1,
  "ratings": [],
  "keywords": []
}
```

# Actor output Schema

## `records` (type: `string`):

No description

## `csv` (type: `string`):

No description

## `games` (type: `string`):

No description

## `gamesCsv` (type: `string`):

No description

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

No description

## `sourceNotice` (type: `string`):

No description

# 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 = {
    "games": [
        "https://www.taptap.cn/app/168332"
    ],
    "maxReviewsPerGame": 3,
    "maxPagesPerGame": 1
};

// Run the Actor and wait for it to finish
const run = await client.actor("dimweaker/taptap-china-game-reviews-export").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 = {
    "games": ["https://www.taptap.cn/app/168332"],
    "maxReviewsPerGame": 3,
    "maxPagesPerGame": 1,
}

# Run the Actor and wait for it to finish
run = client.actor("dimweaker/taptap-china-game-reviews-export").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 '{
  "games": [
    "https://www.taptap.cn/app/168332"
  ],
  "maxReviewsPerGame": 3,
  "maxPagesPerGame": 1
}' |
apify call dimweaker/taptap-china-game-reviews-export --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,dimweaker/taptap-china-game-reviews-export"
        }
    }
}
```

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/jtoSnLkJZs6Wytrvo/builds/hlfjGZy6JrEUcMRXH/openapi.json