# Douban Music Scraper 豆瓣音乐: Top 250, Weekly Charts and Tag Lists (`getascraper/douban-music-rankings-scraper`) Actor

Scrape Douban Music 豆瓣音乐 rankings: the all-time Top 250, weekly new albums and musician singles charts, and any genre or artist tag list. Filter by rating, year and genre, add track lists and star splits, and track rank changes between runs. Export to JSON, CSV or Excel. 豆瓣音乐排行榜数据采集.

- **URL**: https://apify.com/getascraper/douban-music-rankings-scraper.md
- **Developed by:** [GetAScraper](https://apify.com/getascraper) (community)
- **Categories:** Other, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.00 / 1,000 album rows

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

## 🎵 Douban Music Scraper 豆瓣音乐: Top 250, Weekly Charts and Tag Lists

<table width="100%" style="width:100%;min-width:100%;border-collapse:collapse;table-layout:fixed;margin-bottom:0">
<tbody style="display:table;width:100%;min-width:100%;border-collapse:collapse;table-layout:fixed">
<tr style="width:100%">
<td colspan="3" style="padding:14px 18px;background:#F0F8F1;border-top:3px solid #2F963D;border-left:1px solid #D5EAD8;border-right:1px solid #D5EAD8;border-radius:8px 8px 0 0">
<span style="font-size:16px;font-weight:700;color:#1C1917">Douban rates albums, books and films. This suite reads all three.</span> <span style="font-size:15px;color:#57534E">Run the album charts here, then pull the book and film rankings with the same filters and change tracking.</span>
</td>
</tr>
<tr style="width:100%">
<td colspan="3" style="padding:10px 14px;background:#1F6B2B;border-left:1px solid #D5EAD8;border-right:1px solid #D5EAD8">
<span style="color:#FFFFFF;font-size:14px;font-weight:700;letter-spacing:0.5px">DOUBAN RANKINGS SUITE</span>
<span style="color:#FFFFFF;font-size:13px;opacity:0.85">&nbsp;&nbsp;&bull;&nbsp;&nbsp;Books, films and albums from Douban's public charts</span>
</td>
</tr>
<tr style="width:100%">
<td width="33%" style="width:33.333%;padding:10px 12px;border-left:1px solid #D5EAD8;border-bottom:1px solid #D5EAD8;vertical-align:top;background:#FFFFFF;border-radius:0 0 0 8px;">
<span style="overflow-wrap:break-word;word-break:break-word"><img src="https://apify-image-uploads-prod.s3.us-east-1.amazonaws.com/jNDbFabbVxMhnQNb4-actor-5B6iDxeDl5xf2s17t-rfmsGBx8He-images_%2858%29.jpeg" width="20" height="20" style="vertical-align:middle;border-radius:4px">&nbsp;<a href="https://apify.com/getascraper/douban-book-rankings-scraper" style="color:#1C1917;text-decoration:none;font-weight:700;font-size:13px">Douban&nbsp;Books</a></span><br><span style="color:#57534E;font-size:11px">Top 250, tags, new releases</span>
</td>
<td width="33%" style="width:33.333%;padding:10px 12px;border-left:1px solid #D5EAD8;border-bottom:1px solid #D5EAD8;vertical-align:top;background:#FFFFFF;">
<span style="overflow-wrap:break-word;word-break:break-word"><img src="https://apify-image-uploads-prod.s3.us-east-1.amazonaws.com/jNDbFabbVxMhnQNb4-actor-Brro3SbyNbOfOJJGq-95AsrlT8ct-images_%2858%29.jpeg" width="20" height="20" style="vertical-align:middle;border-radius:4px">&nbsp;<a href="https://apify.com/getascraper/douban-movie-rankings-scraper" style="color:#1C1917;text-decoration:none;font-weight:700;font-size:13px">Douban&nbsp;Movies</a></span><br><span style="color:#57534E;font-size:11px">10 charts and 28 genre charts</span>
</td>
<td width="33%" style="width:33.333%;padding:10px 12px;border-left:1px solid #D5EAD8;border-bottom:1px solid #D5EAD8;border-right:1px solid #D5EAD8;vertical-align:top;background:#F0F8F1;border-radius:0 0 8px 0;">
<span style="overflow-wrap:break-word;word-break:break-word"><img src="https://apify-image-uploads-prod.s3.us-east-1.amazonaws.com/jNDbFabbVxMhnQNb4-actor-mc0pxfceymXv6oYBc-CPg5KYovoc-images_%2858%29.jpeg" width="20" height="20" style="vertical-align:middle;border-radius:4px">&nbsp;<a href="https://apify.com/getascraper/douban-music-rankings-scraper" style="color:#1F6B2B;text-decoration:none;font-weight:700;font-size:13px">Douban&nbsp;Music</a></span><br><span style="color:#1F6B2B;font-size:11px;font-weight:700">&#10148; You are here</span>
</td>
</tr>
</tbody>
</table>
<table width="100%" style="margin-top:0;margin-bottom:0">
<tr>
<td style="padding:24px 28px;background:#F0F8F1;border:1px solid #D5EAD8;border-top:4px solid #2F963D;border-radius:12px">
<span style="font-size:23px;font-weight:800;color:#1C1917;line-height:1.3">Douban's album charts and tag lists, ready to rank and compare</span><br>
<span style="font-size:15px;color:#57534E;line-height:1.6">Collect the Top 250 albums, the weekly new albums and musician singles charts, and genre or artist tag lists, with rating and rating count on every row. Turn on change tracking to watch rankings move from run to run.</span>
</td>
</tr>
</table>
<table width="100%" style="margin-top:0">
<tr>
<td style="padding:14px 12px;width:25%;background:#FFFFFF;border:1px solid #D5EAD8;border-radius:10px 0 0 10px;vertical-align:top">
<span style="font-size:15px;font-weight:800;color:#1F6B2B">🏆 Charts and tag lists</span><br>
<span style="font-size:12px;color:#57534E">Top 250 albums, two weekly charts, and any genre, artist, region or era tag.</span>
</td>
<td style="padding:14px 12px;width:25%;background:#FFFFFF;border:1px solid #D5EAD8;border-left:none;vertical-align:top">
<span style="font-size:15px;font-weight:800;color:#1F6B2B">🎯 Filters that narrow fast</span><br>
<span style="font-size:12px;color:#57534E">Keep albums by rating, rating count, release year, genre, artist, release type or format.</span>
</td>
<td style="padding:14px 12px;width:25%;background:#FFFFFF;border:1px solid #D5EAD8;border-left:none;vertical-align:top">
<span style="font-size:15px;font-weight:800;color:#1F6B2B">🎼 Full album detail</span><br>
<span style="font-size:12px;color:#57534E">Optionally add track lists, star split, label, barcode, listener counts and related albums.</span>
</td>
<td style="padding:14px 12px;width:25%;background:#FFFFFF;border:1px solid #D5EAD8;border-left:none;border-radius:0 10px 10px 0;vertical-align:top">
<span style="font-size:15px;font-weight:800;color:#1F6B2B">📈 Rank movement</span><br>
<span style="font-size:12px;color:#57534E">Change tracking shows new entries, rank change and rating movement since your last run.</span>
</td>
</tr>
</table>

Point this Actor at 豆瓣音乐, Douban's music community, and get its album rankings as a clean dataset you can filter, sort and export to JSON, CSV or Excel. No login required.

### 🔍 What does Douban Music Scraper do?

This Actor reads Douban Music's public ranking pages and returns one tidy row per album or single. Choose the Top 250 albums, the weekly new albums chart, the weekly musician singles chart, or any Douban tag list, or paste specific album links or IDs.

- **Ranking sources:** the Top 250 albums, the weekly new albums chart, the weekly musician singles chart, plus any Douban tag list (a genre like 摇滚, an artist like 周杰伦, a region or an era).
- **Every row:** rank, title, alternate title, artist, release date and year, album type, medium, genre, rating, rating count, cover and album link.
- **Optional full album details:** track list with disc numbers, album summary, the 1 to 5 star rating split, label, barcode, ISRC, disc count, how many listeners heard it, are listening or want to hear it, other editions, and related albums with their ratings.
- **Optional change tracking:** rank change, new entries, rating movement and new ratings since your previous run.

No Douban account is needed. This Actor focuses on rankings and album data and does not collect listener reviews or comments.

### 💡 Why use it

- **I am an A\&R scout** looking at which albums in a genre like 民谣 score highest on Douban with enough ratings to trust, so I can spot artists that Chinese listeners rate highly.
- **I am a playlist curator** building a list from a Douban tag sorted by rating, while skipping albums that only have a handful of votes.
- **I am a record label analyst** running the weekly new albums chart on a schedule, so I can see what enters and what climbs without opening the page.
- **I am a music researcher** pulling every album under an artist tag such as 周杰伦 with release year and type, so I can compare how listeners rate each era.

### 🚀 How it works

<table width="100%">
<tr>
<td style="padding:16px 14px;width:33%;background:#F0F8F1;border:1px solid #D5EAD8;border-radius:10px 0 0 10px;vertical-align:top">
<span style="font-size:12px;font-weight:800;color:#1F6B2B;letter-spacing:1px">STEP 1</span><br>
<span style="font-size:14px;font-weight:700;color:#1C1917">Pick a list</span><br>
<span style="font-size:12px;color:#57534E">Choose a ranking list, add tags, or paste album links.</span>
</td>
<td style="padding:16px 14px;width:33%;background:#F0F8F1;border:1px solid #D5EAD8;border-left:none;vertical-align:top">
<span style="font-size:12px;font-weight:800;color:#1F6B2B;letter-spacing:1px">STEP 2</span><br>
<span style="font-size:14px;font-weight:700;color:#1C1917">Set filters and details</span><br>
<span style="font-size:12px;color:#57534E">Limit by rating, year, genre, artist or format, and add full album details if you need them.</span>
</td>
<td style="padding:16px 14px;width:33%;background:#F0F8F1;border:1px solid #D5EAD8;border-left:none;border-radius:0 10px 10px 0;vertical-align:top">
<span style="font-size:12px;font-weight:800;color:#1F6B2B;letter-spacing:1px">STEP 3</span><br>
<span style="font-size:14px;font-weight:700;color:#1C1917">Export or watch weekly</span><br>
<span style="font-size:12px;color:#57534E">Download JSON, CSV or Excel, or schedule runs with change tracking on.</span>
</td>
</tr>
</table>

### 📥 Input

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `rankingLists` | array of options | No | Which rankings to collect: Top 250, the weekly new albums chart, the weekly musician singles chart. Defaults to Top 250. Leave empty to use only your tags and album links. |
| `tags` | array of strings | No | Douban tags to read as their own rankings, for example a genre such as 摇滚 or jazz, an artist such as 周杰伦, or a region. A tag page link also works. |
| `tagSort` | enum | No | Order inside each tag: hot, best rated, newest or most saved. Best rated works well with a minimum rating count. |
| `subjectUrls` | array of strings | No | Specific album pages to collect in full, as Douban links or plain ID numbers such as 3040149. These always include the detail fields, and your filters still apply. |
| `minRating` | number | No | Keep only albums rated at or above this value on the 0 to 10 scale. Use 0 to switch off. |
| `minRatingCount` | integer | No | Keep only albums rated by at least this many listeners, which skips high scores from a handful of votes. Use 0 to switch off. |
| `releaseYearFrom` | integer | No | Keep only albums released in this year or later. Use 0 for no lower limit. |
| `releaseYearTo` | integer | No | Keep only albums released in this year or earlier. Use 0 for no upper limit. |
| `genres` | array of strings | No | Keep albums whose genre contains any of these words, as Douban shows them, for example 摇滚, 流行 or 民谣. |
| `artists` | array of strings | No | Keep albums by artists whose name contains any of these words. Matches Chinese and Latin names, ignoring case. |
| `albumTypes` | array of strings | No | Keep albums of these release types as Douban labels them, for example 专辑, 单曲, EP or Soundtrack. |
| `mediaTypes` | array of strings | No | Keep albums released on these formats, for example CD, Vinyl or 数字. |
| `titleKeywords` | array of strings | No | Keep albums whose title or alternate title contains any of these words. |
| `includeDetails` | boolean | No | Add track list, summary, star rating split, label, barcode, listener counts, other editions and related albums. Each album page is opened, so runs take longer. Off by default. |
| `trackChanges` | boolean | No | Compare each list with your previous run and show rank change, new entries and rating movement. The first run only saves the starting point. |
| `monitorScope` | string | No | A name for this watch. Use different names to keep independent watches on the same list. Only used when change tracking is on. |
| `onlyChanges` | boolean | No | After the first run, return only albums that are new, moved up or down, or changed rating. Only used when change tracking is on. |
| `maxItems` | integer | No | Maximum albums to collect from each list, tag or chart. Defaults to 25. The weekly charts are shorter than this. |
| `maxListPages` | integer | No | Page limit per tag list, useful when filters skip many albums. Tag pages hold 20 albums and Douban shows at most 50 pages. |
| `uniqueAlbums` | boolean | No | Output an album only for the first list that shows it, instead of once per list. Off by default. |
| `requestDelaySecs` | number | No | Pause in seconds between page views. The default of 1 keeps runs polite and reliable. |
| `proxyConfiguration` | object | No | Connection settings for Douban's public pages. Leave the default unless your account needs a custom route. |

The default input collects the first 25 albums of the Top 250 and finishes in well under a minute.

### 📊 Data table

| Field | Type | Description |
| --- | --- | --- |
| `list` | string | Which list the row came from: top250, newAlbumsChart, musicianSinglesChart, tag:<name> or subject. |
| `rank` | integer | Position in that list. |
| `subjectId` | string | Douban music identifier. |
| `title` | string | Album or single title. |
| `alternateTitle` | string | Subtitle or second title shown beside the title. |
| `artist` | string | Artist or artists as one text. |
| `artists` | array | Artists as a list. |
| `releaseDate` | string | Release date as Douban shows it, full date or year only. |
| `releaseYear` | integer | Release year. |
| `albumType` | string | Release type such as album, single, EP or soundtrack. |
| `media` | string | Medium such as CD, vinyl or digital. |
| `genre` | string | Genre label. |
| `publicationInfo` | string | The full descriptive line shown on the ranking page. |
| `rating` | number | Douban average rating out of 10. |
| `ratingCount` | integer | Number of Douban ratings. |
| `coverUrl` | string | Cover image link. |
| `url` | string | Douban album page. |
| `daysOnChart` | integer | Days on the weekly chart (charts only). |
| `playCount` | integer | Weekly plays (musician singles chart only). |
| `songId` | string | Douban identifier of the single (musician singles chart only). |
| `artistUrl` | string | Musician page (musician singles chart only). |
| `rankChange` | integer | Places moved up (positive) or down (negative) since the previous chart or run. |
| `previousRank` | integer | Rank in the previous run (change tracking). |
| `isNewEntry` | boolean | True when the album was not in the previous run's list (change tracking). |
| `previousRating` | number | Rating in the previous run (change tracking). |
| `ratingChange` | number | Rating movement since the previous run (change tracking). |
| `previousRatingCount` | integer | Rating count in the previous run (change tracking). |
| `ratingCountChange` | integer | New ratings since the previous run (change tracking). |
| `firstSeenAt` | string | When this run history first saw the album in the list (change tracking). |
| `aliases` | array | Other titles for the album (detail). |
| `performers` | array | Performers listed on the album page (detail). |
| `publisher` | string | Label or publisher (detail). |
| `discCount` | integer | Number of discs (detail). |
| `barcode` | string | Barcode (detail). |
| `isrc` | string | ISRC code (detail). |
| `summary` | string | Album description (detail). |
| `trackCount` | integer | Number of tracks (detail). |
| `tracks` | array | Track list with disc, number and title (detail). |
| `ratingDistribution` | object | Share of ratings by star, star5 to star1, in percent (detail). |
| `listenedCount` | integer | Listeners who marked the album as heard (detail). |
| `listeningCount` | integer | Listeners currently listening (detail). |
| `wishCount` | integer | Listeners who want to hear it (detail). |
| `coverUrlLarge` | string | Larger cover image link (detail). |
| `otherVersions` | array | Other editions of the album (detail). |
| `relatedAlbums` | array | Albums that listeners of this one also like, with ratings (detail). |
| `sourceUrl` | string | Page that supplied the row. |
| `retrievedAt` | string | Time the row was collected. |

Fields that Douban does not show are left out of the row, never filled with placeholders. You can download the dataset as JSON, CSV or Excel from the Output tab of any run.

### 📤 Sample output

```json
{
    "list": "top250",
    "rank": 1,
    "subjectId": "2995812",
    "title": "We Sing. We Dance. We Steal Things.",
    "artist": "Jason Mraz",
    "artists": [
        "Jason Mraz"
    ],
    "releaseDate": "2008-05-13",
    "releaseYear": 2008,
    "albumType": "Import",
    "media": "Audio CD",
    "genre": "民谣",
    "publicationInfo": "Jason Mraz / 2008-05-13 / Import / Audio CD / 民谣",
    "rating": 9.1,
    "ratingCount": 117126,
    "coverUrl": "https://img3.doubanio.com/view/subject/s/public/s2967252.jpg",
    "url": "https://music.douban.com/subject/2995812/",
    "sourceUrl": "https://music.douban.com/top250?start=0",
    "retrievedAt": "2026-10-11T09:26:42.216Z"
}
```

### 💰 Pricing

Pricing is pay per result, with no subscriptions. You pay for each album delivered to your dataset. Full album details are billed separately, and only for the albums that actually come back with the extra data. Empty runs cost nothing. If you set a maximum charge per run in Apify, it is respected: the run stops cleanly when the limit is reached and keeps everything already delivered. Your Apify plan sets the rate, and higher plans pay less.

### ⭐ Enjoying Douban Music Scraper?

<table width="100%" style="display:table;width:100%">
<tr>
<td style="padding:20px 24px 14px;background:#F0F8F1;border:1px solid #D5EAD8;border-left:5px solid #2F963D;border-radius:10px 10px 0 0">
<span style="font-size:20px;letter-spacing:4px;color:#1C1917">⭐ ⭐ ⭐ ⭐ ⭐</span><br>
<span style="font-size:17px;font-weight:800;color:#1C1917">One run turns Douban's album charts into a table you can rank, filter and compare.</span><br>
<span style="font-size:14px;color:#57534E">A 5-star rating takes 10 seconds and helps other A&R scouts, curators and music researchers find this actor. Your feedback also tells us what to build next.</span>
</td>
</tr>
<tr>
<td style="padding:0;background:#1F6B2B;border:1px solid #D5EAD8;border-top:none;border-radius:0 0 10px 10px;text-align:center">
<a href="https://apify.com/getascraper/douban-music-rankings-scraper/reviews" style="display:block;padding:13px 16px;color:#FFFFFF;text-decoration:none;font-weight:800;font-size:15px;letter-spacing:0.3px">★&nbsp;&nbsp;Rate this Actor on Apify</a>
</td>
</tr>
</table>

### ❓ FAQ

##### 豆瓣音乐 Top 250 怎么导出？

Run the Actor with its default settings and download the dataset as JSON, CSV or Excel from the Output tab. The default reads 25 albums, so raise the maximum albums per list to 250 to get the whole Top 250.

##### 豆瓣音乐 摇滚 专辑 评分 排行 怎么获取？

Add the tag 摇滚 (or jazz, or an artist such as 周杰伦), choose best rated order, and set a minimum rating count to skip albums with only a few votes. Each tag is returned as its own ranking.

##### How do I watch rankings over time?

Turn on change tracking and schedule the Actor weekly. The first run saves the starting point. Every later run adds rank change, new entry flags and rating movement, and can return only what changed.

##### Why do runs with full album details take longer?

Full details need one extra page visit per album, about three seconds each, so a run of 100 albums takes around five minutes. For large collections, split the work into several runs, for example one tag or list per run.

### 🔗 Other actors

- [Douban Book Scraper 豆瓣读书: Top 250, Tags, New Releases, Changes](https://apify.com/getascraper/douban-book-rankings-scraper) ↗ - Collects Douban's book Top 250, topic tag lists and new releases.
- [Douban Movie Top 250 Scraper 豆瓣电影: Hot Charts, Filters, Changes](https://apify.com/getascraper/douban-movie-rankings-scraper) ↗ - Collects Douban's film and TV charts and genre charts with filters and change tracking.
- [Migu Music Scraper: 咪咕音乐](https://apify.com/getascraper/migu-music-scraper) ↗ - Collects public music catalogue and chart records from Migu Music.
- [Kugou Music Scraper: 酷狗音乐 Catalog, Charts & Lyrics](https://apify.com/getascraper/kugou-music-scraper) ↗ - Collects the Kugou Music catalogue, charts and lyrics.
- [QQ Music Scraper: QQ音乐 Songs, Charts & Comments](https://apify.com/getascraper/qq-music-scraper) ↗ - Collects QQ Music songs, charts and comments.

# Changelog

This Actor's version history is a separate document: https://apify.com/getascraper/douban-music-rankings-scraper/changelog.md

# Actor input Schema

## `rankingLists` (type: `array`):

Which Douban Music rankings to collect. Top 250 is the all-time best-rated list. The new albums chart and the musician singles chart are Douban's weekly charts. Leave empty to use only the tags and album links below.

## `tags` (type: `array`):

Collect Douban's album list for each tag, for example a genre such as 摇滚 or jazz, an artist such as 周杰伦, or a region. A tag page link also works. Each tag is read as its own ranking.

## `tagSort` (type: `string`):

How Douban orders the albums inside each tag. Best rated puts the highest scores first, so combine it with a minimum rating count to skip albums with only a few votes.

## `subjectUrls` (type: `array`):

Specific Douban Music album pages to collect in full, for example https://music.douban.com/subject/3040149/ or just 3040149. These always include the detail fields. Filters below still apply to them.

## `minRating` (type: `number`):

Keep only albums with a Douban rating at or above this value (0 to 10). Use 0 to switch the filter off.

## `minRatingCount` (type: `integer`):

Keep only albums rated by at least this many Douban listeners. Useful to skip albums with a high score from only a handful of votes. Use 0 to switch the filter off.

## `releaseYearFrom` (type: `integer`):

Keep only albums released in this year or later. Use 0 for no lower limit.

## `releaseYearTo` (type: `integer`):

Keep only albums released in this year or earlier. Use 0 for no upper limit.

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

Keep albums whose genre contains any of these words, as Douban shows them (for example 摇滚, 流行, 民谣, 原声). Leave empty for all genres.

## `artists` (type: `array`):

Keep albums by artists whose name contains any of these words. Matches Chinese and Latin names, ignoring case. Leave empty for all artists.

## `albumTypes` (type: `array`):

Keep albums of these release types as Douban labels them, for example 专辑 (album), 单曲 (single), EP, Soundtrack or Live. Leave empty for all types.

## `mediaTypes` (type: `array`):

Keep albums released on these formats, for example CD, Vinyl, 黑胶 or 数字 (digital). Leave empty for all formats.

## `titleKeywords` (type: `array`):

Keep albums whose title or alternate title contains any of these words. Leave empty to keep all titles.

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

Open every album page to add the track list, summary, 1 to 5 star rating split, label, barcode, listener counts, other editions and related albums. This adds one page view per album, so runs take longer.

## `trackChanges` (type: `boolean`):

Remember each list after the run and compare it with the previous run. Rows then show rank change, new entries and rating movement. The first run only saves a baseline. Schedule the Actor weekly to build a history.

## `monitorScope` (type: `string`):

A label for this watch. Use different names to keep independent watches on the same list, for example one for your A\&R team and one for research. Only used when change tracking is on.

## `onlyChanges` (type: `boolean`):

After the baseline run, return only albums that are new in the list, moved up or down, or changed rating. Everything else is skipped. Only used when change tracking is on.

## `maxItems` (type: `integer`):

Maximum number of albums to collect from each ranking list, tag or chart, in the order Douban shows them. The weekly charts are shorter than this.

## `maxListPages` (type: `integer`):

Safety limit for how many ranking pages are read per tag when filters skip many albums. Tag pages hold 20 albums and Douban shows at most 50 pages.

## `uniqueAlbums` (type: `boolean`):

When an album appears in several lists, output it only for the first list instead of once per list.

## `requestDelaySecs` (type: `number`):

Pause in seconds between Douban page views. Keep the default for polite, reliable runs. Higher values are slower but gentler.

## `proxyConfiguration` (type: `object`):

Apify Proxy settings for the public Douban pages. Leave the default unless your account needs a custom route.

## Actor input object example

```json
{
  "rankingLists": [
    "top250"
  ],
  "tags": [],
  "tagSort": "heat",
  "subjectUrls": [],
  "minRating": 0,
  "minRatingCount": 0,
  "releaseYearFrom": 0,
  "releaseYearTo": 0,
  "genres": [],
  "artists": [],
  "albumTypes": [],
  "mediaTypes": [],
  "titleKeywords": [],
  "includeDetails": false,
  "trackChanges": false,
  "monitorScope": "default",
  "onlyChanges": false,
  "maxItems": 25,
  "maxListPages": 10,
  "uniqueAlbums": false,
  "requestDelaySecs": 1,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# Actor output Schema

## `results` (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 = {
    "rankingLists": [
        "top250"
    ],
    "tags": [],
    "tagSort": "heat",
    "subjectUrls": [],
    "minRating": 0,
    "minRatingCount": 0,
    "releaseYearFrom": 0,
    "releaseYearTo": 0,
    "genres": [],
    "artists": [],
    "albumTypes": [],
    "mediaTypes": [],
    "titleKeywords": [],
    "includeDetails": false,
    "trackChanges": false,
    "monitorScope": "default",
    "onlyChanges": false,
    "maxItems": 25,
    "maxListPages": 10,
    "uniqueAlbums": false,
    "requestDelaySecs": 1,
    "proxyConfiguration": {
        "useApifyProxy": true
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("getascraper/douban-music-rankings-scraper").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 = {
    "rankingLists": ["top250"],
    "tags": [],
    "tagSort": "heat",
    "subjectUrls": [],
    "minRating": 0,
    "minRatingCount": 0,
    "releaseYearFrom": 0,
    "releaseYearTo": 0,
    "genres": [],
    "artists": [],
    "albumTypes": [],
    "mediaTypes": [],
    "titleKeywords": [],
    "includeDetails": False,
    "trackChanges": False,
    "monitorScope": "default",
    "onlyChanges": False,
    "maxItems": 25,
    "maxListPages": 10,
    "uniqueAlbums": False,
    "requestDelaySecs": 1,
    "proxyConfiguration": { "useApifyProxy": True },
}

# Run the Actor and wait for it to finish
run = client.actor("getascraper/douban-music-rankings-scraper").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 '{
  "rankingLists": [
    "top250"
  ],
  "tags": [],
  "tagSort": "heat",
  "subjectUrls": [],
  "minRating": 0,
  "minRatingCount": 0,
  "releaseYearFrom": 0,
  "releaseYearTo": 0,
  "genres": [],
  "artists": [],
  "albumTypes": [],
  "mediaTypes": [],
  "titleKeywords": [],
  "includeDetails": false,
  "trackChanges": false,
  "monitorScope": "default",
  "onlyChanges": false,
  "maxItems": 25,
  "maxListPages": 10,
  "uniqueAlbums": false,
  "requestDelaySecs": 1,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}' |
apify call getascraper/douban-music-rankings-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,getascraper/douban-music-rankings-scraper"
        }
    }
}
```

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/mc0pxfceymXv6oYBc/builds/6pmCeJ5LW7LbKztB2/openapi.json