# K-Music Charts Feed — Melon x Genie x Bugs (`kdatafactory/kmusic-charts-feed`) Actor

Korea's realtime music streaming charts in one run: Melon, Genie and Bugs Top 100 — clean JSON with source, rank, title, artist, album, rank change and cover image. For K-pop analytics, all-kill detection, label A\&R and AI agents.

- **URL**: https://apify.com/kdatafactory/kmusic-charts-feed.md
- **Developed by:** [Seok June Park](https://apify.com/kdatafactory) (community)
- **Categories:** E-commerce, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.00 / 1,000 results

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/platform/actors/running/actors-in-store#pay-per-event

## 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

## K-Music Charts Feed — Melon × Genie × Bugs 🎵

Snapshot Korea's **realtime music streaming charts** from [Melon](https://www.melon.com/chart/index.htm), [Genie](https://www.genie.co.kr/chart/top200) and [Bugs](https://music.bugs.co.kr/chart) — the three services that define what's charting in Korea — as one clean, unified JSON/CSV/Excel dataset. Get `source`, `rank`, `title`, `artist`, `album`, `rank_change`, and cover image for every song in one run.

Instead of scraping three sites and gluing schemas together, you get one call, one schema — perfect for **K-pop analytics, all-kill detection, and label A\&R**.

> **Try it free.** Apify's free plan includes $5 of monthly platform credit — at **$2.00 / 1,000 results** that's roughly **2,500 chart entries** from this actor, no credit card required. Set your input, click Start, and export JSON/CSV/Excel.

***

### What it does

This actor reads each service's own **public, server-rendered chart page** (the same page any visitor sees — no login, no private API, no headless browser) and parses it into a unified feed. One run collects the **realtime Top 100 from each requested source**:

| Source | Chart | Rows |
|--------|-------|------|
| `melon` | Melon (멜론) **실시간 차트** — Korea's #1 streaming service | Top 100 |
| `genie` | Genie (지니) **실시간 차트 TOP 200** (collected to Top 100) | Top 100 |
| `bugs` | Bugs (벅스) **실시간 차트** | Top 100 |

Cross-referencing the three is how analysts spot a **"perfect all-kill"** (a song sitting at #1 on every chart at once) and how they separate a real hit from a single-platform fan push.

***

### Input

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `source` | string | `all` | Which chart to snapshot: `all`, `melon`, `genie`, or `bugs`. |
| `topN` | integer | `100` | Top-ranked entries to collect from **each** source (max 100). |
| `proxyConfiguration` | object | off | Optional Apify proxy. Not required — the charts read fine on a direct connection. |

#### Input example

```json
{
  "source": "all",
  "topN": 100
}
```

```json
{
  "source": "melon",
  "topN": 50
}
```

***

### Output

Each chart entry is one dataset record (real samples from a live run):

```json
{
  "source": "melon",
  "chart_type": "realtime",
  "rank": 1,
  "title": "LOVE ATTACK",
  "artist": "RESCENE (리센느)",
  "album": "SCENEDROME",
  "rank_change": 0,
  "url": "https://www.melon.com/song/detail.htm?songId=37928381",
  "image_url": "https://cdnimg.melon.co.kr/cm2/album/images/115/75/849/11575849_20240826152240_500.jpg/melon/resize/120/quality/80/optimize",
  "scraped_at": "2026-07-14T14:43:16+09:00"
}
```

```json
{
  "source": "bugs",
  "chart_type": "realtime",
  "rank": 1,
  "title": "Ice Cream",
  "artist": "연준",
  "album": "NO LABELS: PART 02",
  "rank_change": 0,
  "url": "https://music.bugs.co.kr/track/6489217",
  "image_url": "https://image.bugsm.co.kr/album/images/50/41513/4151359.jpg?version=20260711005644",
  "scraped_at": "2026-07-14T14:43:16+09:00"
}
```

A full 30-record sample (10 per source) from a real run is in [`samples/sample-output.json`](samples/sample-output.json).

| Field | Meaning |
|-------|---------|
| `source` | Which chart the record came from: `melon`, `genie` or `bugs`. |
| `chart_type` | Always `"realtime"` — these are the live/realtime charts. |
| `rank` | The song's position on that source's own chart (1–100). Never re-numbered across sources. |
| `title` | Song title. |
| `artist` | Artist(s). Multiple credits are comma-joined (e.g. featured artists). |
| `album` | Album title, else `null`. |
| `rank_change` | Positions moved vs. the previous chart snapshot: positive = up, negative = down, `0` = unchanged. `null` for a brand-new entry the site marks with no numeric delta (see limitations). |
| `url` | Song/track detail page on the source. |
| `image_url` | Album-cover thumbnail as the source serves it. |
| `scraped_at` | ISO-8601 timestamp (KST, UTC+9). |

The critical fields — `source`, `rank`, `title`, `artist` — are populated on **30/30** records in the live test, and in that sample `album`, `rank_change`, `url` and `image_url` were populated on **30/30** as well. A row missing any critical field is dropped rather than emitted half-empty.

***

### Use cases

- **K-pop analytics** — track a song or artist across Melon, Genie and Bugs in one schedule and chart rank-over-time. Diff snapshots to catch risers before they peak (`rank_change` gives you the per-run delta for free).
- **All-kill / perfect all-kill detection** — join the three sources on `title` + `artist` and flag songs sitting at #1 (or in the top N) on every chart at once — the metric K-pop media reports on.
- **Label & A\&R monitoring** — watch where a roster's releases land across all three services at launch, at what rank, moving which direction. Compare a comeback's first-day charting against past releases.
- **AI agents & LLM pipelines** — a compact, unified JSON feed of Korea's music charts for a RAG index, a "what's charting in Korea right now" assistant, or a dashboard — no scraping code in your app.

***

### ❓ FAQ

**Is it legal to scrape this data?**
This actor collects only public, non-personal chart data — the same ranking lists any visitor sees without logging in. No personal data is collected; artist names are public commercial credits. You are responsible for how you use the data; see the rate & legality note below.

**What does it cost in practice?**
$2.00 per 1,000 results (launch pricing) + a few cents of platform usage. Example: a daily all-source snapshot at `topN: 100` (~300 results) costs about **$0.60/day**. Apify's free $5 monthly credit covers **~2,500 results**.

**Do I need to configure proxies?**
No — the default settings work out of the box. All three charts are server-rendered and read fine on a **direct connection**. If a run ever comes back empty, enable Apify Proxy and re-run.

**How fresh is the data?**
Every run scrapes the live realtime charts at run time. Schedule the actor for recurring snapshots — rank-over-time and `rank_change` are where the value is.

**Can I run just one chart?**
Yes — set `"source": "melon"` (or `genie` / `bugs`). Default `all` collects all three in one run.

**Why do Melon and Bugs stop at 100 while Genie has 200?**
Melon's and Bugs' realtime charts are Top 100. Genie publishes a Top 200, but this feed caps every source at 100 so the three line up for cross-chart comparison.

***

### 🤖 Use with AI agents (MCP)

Call this Actor as a tool from Claude or any MCP-compatible AI agent — no glue code. Point your MCP client at Apify's server, scoped to this Actor:

```json
{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com?tools=kdatafactory/kmusic-charts-feed",
      "headers": { "Authorization": "Bearer <YOUR_APIFY_TOKEN>" }
    }
  }
}
```

Your agent can then pull Korea's realtime music charts across Melon, Genie & Bugs on demand — no scraping code in your app. Grab a free token from [Apify → Integrations](https://console.apify.com/settings/integrations).

### 🇰🇷 More Korean data actors

This actor is part of a suite of Korean-platform scrapers by the same maintainer:

- [circlechart-scraper](https://apify.com/kdatafactory/circlechart-scraper) — Circle Chart (formerly Gaon), Korea's official national music chart (weekly/monthly, sales + streaming).
- [kpop-photocard-index](https://apify.com/kdatafactory/kpop-photocard-index) — K-pop photocard catalogue and resale-price index.
- [ktown4u-scraper](https://apify.com/kdatafactory/ktown4u-scraper) — K-pop album & merch listings and best-sellers from Ktown4u.

Browse all: [apify.com/kdatafactory](https://apify.com/kdatafactory)

***

### Rate limiting & legality

- The actor collects **only public, non-authenticated data** — the realtime chart lists anyone can see without logging in. It never logs in and never touches private endpoints.
- **No personal data** is collected. Artist names are public commercial credits, like a shop name.
- Requests are **rate-limited**: one page at a time with a ≥ 500 ms delay between requests (a full default run is about 4 light requests), to stay gentle on the sites' servers.
- You are responsible for using the data in line with each service's terms of service and applicable law. Use it for research, monitoring and analytics — not to replicate the services.

#### Known limitations (honesty note)

- **`rank_change` is best-effort.** It's the per-snapshot delta each site publishes next to the rank (up/down/unchanged). For a **brand-new entry** (신규진입) that the site marks without a numeric value, `rank_change` is `null` rather than a guessed number. It is the chart's own movement figure, not a diff this actor computes across your runs.
- **`album` can occasionally be `null`** if a chart row omits the album link. In the live test it was present on every record.
- **Top 100 per source.** Melon and Bugs realtime charts are Top 100; Genie's Top 200 is capped to 100 so the three sources align for comparison. `topN` above 100 is clamped to 100.
- **These are the realtime charts** (`chart_type` is always `"realtime"`). For official weekly/monthly national rankings, use [circlechart-scraper](https://apify.com/kdatafactory/circlechart-scraper).
- **Text is Korean.** Titles, artist and album names are returned exactly as each service labels them (Korean for domestic acts, Latin for others) — they are not transliterated or translated.

***

### 🏃 Run it

On Apify: set your input and click **Start**. Locally:

```bash
npm install
## put your input in storage/key_value_stores/default/INPUT.json
npm start
```

Results land in the default dataset (Apify) or `./storage/datasets/default` (local).

***

*If this actor saves you time, a rating on the [Store page](https://apify.com/kdatafactory/kmusic-charts-feed) helps a solo maintainer a lot. Found an issue? Open it in the Issues tab — I respond fast.*

# Actor input Schema

## `source` (type: `string`):

Which Korean music streaming chart to snapshot. Default 'all' collects the realtime Top 100 from Melon, Genie and Bugs in one run; pick a single service to collect just that one.

## `topN` (type: `integer`):

How many top-ranked entries to collect from EACH source (so 'all' at topN 100 = up to 300 records). Maximum 100 — the realtime charts on Melon and Bugs are Top 100.

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

Optional Apify proxy. All three charts are server-rendered and read fine from most IPs, so the default is a direct connection. If a run comes back empty, re-run with an Apify proxy. If a proxy tunnel fails, the actor retries the request directly.

## Actor input object example

```json
{
  "source": "all",
  "topN": 100,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# 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 = {
    "source": "all",
    "topN": 100
};

// Run the Actor and wait for it to finish
const run = await client.actor("kdatafactory/kmusic-charts-feed").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 = {
    "source": "all",
    "topN": 100,
}

# Run the Actor and wait for it to finish
run = client.actor("kdatafactory/kmusic-charts-feed").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "source": "all",
  "topN": 100
}' |
apify call kdatafactory/kmusic-charts-feed --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=kdatafactory/kmusic-charts-feed",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/acts/YbyuBTN4Otcaru85v/builds/5bRVHRFAP54Vt4gPi/openapi.json