# Kworb Music Charts Scraper — Spotify, Apple & YouTube (`crawloop/kworb-music-charts-scraper`) Actor

Scrape Kworb music charts: Spotify daily and weekly streams for 70+ countries, Apple Music, iTunes, YouTube, Shazam, and Deezer. One row is one chart entry with rank, streams, and movement. No login.

- **URL**: https://apify.com/crawloop/kworb-music-charts-scraper.md
- **Developed by:** [Andrej Kiva](https://apify.com/crawloop) (community)
- **Categories:** Social media, Videos, Developer tools
- **Stats:** 3 total users, 2 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.00 / 1,000 chart 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

## Kworb Music Charts Scraper

> **Disclaimer:** Unofficial tool — not affiliated with, sponsored by, or endorsed by Kworb or its affiliates. Data is read from publicly accessible chart pages only. No login. You are responsible for complying with applicable law (including GDPR where personal data appears) and the site’s terms. No warranty on accuracy or availability. Provided for informational and research use.

**Kworb scraper** for public music charts. One row is one chart entry: rank, artist, title, streams or points, and how the position moved. Pull a Spotify daily or weekly chart for one market or for many countries in the same run, or switch to Apple Music, iTunes, YouTube, Shazam, Deezer, US radio, or an artist’s song list. Use it as a **Kworb API alternative** from **Python**, **Node.js**, **cURL**, or **Apify MCP**, and export the dataset as JSON.

**Best for:** label research, playlist research, and a scheduled read of the same charts each day.

### When to use this Actor

- **Spotify streams by country** — Leave Chart on Spotify and set Countries to `global`, `us`, `gb`, or several codes together.
- **The full current chart** — Maximum rows per chart defaults to 200, which is a full daily or weekly list.
- **Apple Music, iTunes, or YouTube** — Switch Chart. Countries are ignored on those modes.
- **One artist’s catalog** — Chart “One artist's Spotify songs” and paste a 22-character Spotify artist ID.
- **Every Spotify market** — Set Countries to `all`. The run reads each market up to Maximum rows per chart and stops at 20,000 rows.

### When not to use this Actor

- **Your own Spotify account or playlists** — This Actor reads public chart pages only.
- **Lyrics, audio, or copyrighted media** — Rows are ranks and the numbers printed on the chart.
- **An unbounded totals dump** — The totals list is every track that has charted. Cap Maximum rows per chart (up to 5,000 per page).

### Key features

- **Spotify daily and weekly** — Rank, movement, days or weeks on chart, peak, streams, stream change, seven-day streams on daily charts, and total streams. Spotify artist and track IDs when the page links them.
- **Many countries in one run** — Pass a list of market codes, or `all` for every Spotify market.
- **Other public charts** — Apple Music worldwide songs, iTunes worldwide songs, YouTube most-viewed and trending, Shazam, Deezer, US radio audience, the all-time Spotify artist list, and the cross-platform artist ranking.
- **Direct HTTP** — Default **256 MB**. No browser and no login.

### Input

| Field | Required | Default | What it does |
| :--- | :--- | :--- | :--- |
| Chart | Yes | Spotify daily or weekly | Which chart to read |
| Countries | No | global | Spotify, Shazam, and Deezer markets. `all` expands to every Spotify market |
| Spotify period | No | Daily | Daily or weekly. Other charts ignore it |
| Spotify chart kind | No | Current chart | Current list, or the long totals list |
| YouTube chart | No | Global most-viewed | Used only for YouTube |
| Spotify artist IDs | No | — | Required for one artist’s songs |
| Maximum rows per chart | No | 200 | Cap per page. A run also stops at 20,000 rows |
| Parallel charts | No | 4 | Pages fetched at once |
| Delay between requests | No | 0.2 seconds | Pause between pages |

```json
{
  "mode": "spotifyChart",
  "countries": ["global", "us", "gb"],
  "period": "daily",
  "chartKind": "current",
  "maxItems": 200
}
```

### Output

| Field | Meaning |
| :--- | :--- |
| `rank` | Position. Totals lists use row order |
| `rankChange` | `+N`, `-N`, `=`, or `NEW` |
| `artist`, `title` | Primary artist and track or video |
| `streams`, `streamsChange` | Exact Spotify streams and the change |
| `sevenDayStreams` | Last seven days, on daily Spotify charts |
| `totalStreams` | Cumulative streams when the page prints them |
| `daysOnChart`, `weeksOnChart`, `peakPosition` | How long it has charted, and its peak |
| `points`, `views`, `likes`, `audience` | Apple Music / iTunes points, YouTube views and likes, or radio audience |
| `streamsMillions` | All-time artist list, in millions as printed |
| `spotifyArtistId`, `spotifyTrackId` | IDs when the chart links them |
| `country`, `period` | Market code and daily or weekly |
| `marketRanks` | Country positions beside a worldwide song |
| `sourceUrl` | Chart page for that row |
| `scrapedAt` | UTC time of the run |

```json
{
  "recordType": "chartEntry",
  "mode": "spotifyChart",
  "platform": "spotify",
  "country": "global",
  "countryName": "Global",
  "period": "daily",
  "chartKind": "current",
  "rank": 1,
  "rankChange": "=",
  "rankDelta": 0,
  "artist": "KAROL G",
  "title": "BbY WOW",
  "daysOnChart": 56,
  "peakPosition": 1,
  "weeksAtPeak": 37,
  "streams": 5057786,
  "streamsChange": 112220,
  "spotifyArtistId": "790FomKkXshlbRYZFtlgla",
  "spotifyTrackId": "3h5T5JypYU7huFiVYhv1dr",
  "sourceUrl": "https://kworb.net/spotify/country/global_daily.html",
  "scrapedAt": "2026-10-08T09:00:00Z"
}
```

### Use cases

- Read the global Spotify daily chart each morning and keep streams, seven-day streams, and peak.
- Compare the same song in `us`, `gb`, `de`, and `br` by passing those codes in one run.
- Pull the YouTube most-viewed list when you need views and likes next to the Spotify rank.
- Look up one artist’s song totals with a Spotify artist ID before a playlist meeting.

### Integration examples

Replace `APIFY_TOKEN`. The slug below is the Store name.

#### Node.js

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

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor("crawloop/kworb-music-charts-scraper").call({
  mode: "spotifyChart",
  countries: ["global", "us"],
  period: "daily",
  maxItems: 200,
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);
```

#### Python

```python
import os
from apify_client import ApifyClient

client = ApifyClient(os.environ["APIFY_TOKEN"])
run = client.actor("crawloop/kworb-music-charts-scraper").call(run_input={
    "mode": "spotifyChart",
    "countries": ["global"],
    "period": "weekly",
    "maxItems": 200,
})
items = client.dataset(run["defaultDatasetId"]).list_items().items
print(len(items))
```

#### cURL

```bash
curl -X POST "https://api.apify.com/v2/acts/crawloop~kworb-music-charts-scraper/runs?token=$APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"mode":"spotifyChart","countries":["gb"],"period":"daily","maxItems":50}'
```

### MCP and AI assistants

Use this Actor from AI tools via [Apify MCP](https://docs.apify.com/platform/integrations/mcp).
Connect your Apify account, then call this Actor by its Store name `crawloop/kworb-music-charts-scraper`.

Example prompts:

- "Run Kworb Music Charts Scraper for the global Spotify daily chart and return rank, artist, title, and streams as JSON"
- "Scrape Kworb Spotify weekly charts for us and gb and summarize the songs that rose"
- "Run Kworb Music Charts Scraper in YouTube mode and list the top videos with views"

### FAQ

**Does one run cover more than one country?**
Yes. Countries accepts a list. `all` reads every Spotify market. Each page is capped by Maximum rows per chart, and the run stops at 20,000 rows.

**Are the stream counts exact?**
On Spotify daily and weekly charts, `streams` is the exact count printed on the page. On the all-time artist list, `streamsMillions` is the figure in millions, as printed.

**What is the totals list?**
Set Spotify chart kind to Totals. That page lists tracks that have charted, not only today’s top 200. Raise Maximum rows per chart if you need more than 200 of them.

**Do I need a login or a proxy?**
No. The Actor reads public chart pages over HTTP.

**How do I export the rows?**
The run writes one chart entry per dataset row. Download JSON, CSV, or Excel from that dataset, or read it with the Node.js, Python, and cURL examples.

# Actor input Schema

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

Which public chart to read. Spotify can take several countries in one run.

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

Market codes for Spotify, Shazam, and Deezer. Examples: global, us, gb, de, jp, br. Use all for every Spotify market (70+). Shazam and Deezer treat global as worldwide. Ignored by Apple Music, iTunes, YouTube, radio, and artist modes.

## `period` (type: `string`):

Daily or weekly Spotify chart. Other modes ignore this.

## `chartKind` (type: `string`):

Current chart, or the long totals list (every track that has charted, capped by Maximum rows).

## `youtubeCategory` (type: `string`):

Used only when Chart is YouTube music videos.

## `artistIds` (type: `array`):

22-character Spotify artist IDs, or artist URLs, for One artist's Spotify songs. Example: 06HL4z0CvFAxyc27GXpf02.

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

Rows saved from each chart page. A current Spotify chart has about 200 rows. A run stops at 20,000 rows overall.

## `concurrency` (type: `integer`):

How many chart pages to fetch at once when several countries are set.

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

Pause between page fetches so a multi-country run stays gentle.

## Actor input object example

```json
{
  "mode": "spotifyChart",
  "countries": [
    "global"
  ],
  "period": "daily",
  "chartKind": "current",
  "youtubeCategory": "global",
  "artistIds": [],
  "maxItems": 200,
  "concurrency": 4,
  "requestDelaySecs": 0.2
}
```

# Actor output Schema

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

Default dataset items — one chart row per item.

# 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": "spotifyChart",
    "countries": [
        "global"
    ],
    "period": "daily",
    "chartKind": "current",
    "youtubeCategory": "global",
    "maxItems": 200
};

// Run the Actor and wait for it to finish
const run = await client.actor("crawloop/kworb-music-charts-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 = {
    "mode": "spotifyChart",
    "countries": ["global"],
    "period": "daily",
    "chartKind": "current",
    "youtubeCategory": "global",
    "maxItems": 200,
}

# Run the Actor and wait for it to finish
run = client.actor("crawloop/kworb-music-charts-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 '{
  "mode": "spotifyChart",
  "countries": [
    "global"
  ],
  "period": "daily",
  "chartKind": "current",
  "youtubeCategory": "global",
  "maxItems": 200
}' |
apify call crawloop/kworb-music-charts-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,crawloop/kworb-music-charts-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/xdU2paHOiBnun95qU/builds/ojkgE0QcmTtKrWT5P/openapi.json