# Circle Chart Scraper — Korea's Official K-pop Music Charts (`kdatafactory/circlechart-scraper`) Actor

Scrape Circle Chart (circlechart.kr, ex-Gaon) — Korea's official music industry charts. Get weekly & monthly Album, Digital and Global K-pop rankings as clean JSON: rank, song/album title, artist, distributor, production company, album sales, rank change. For K-pop analytics and AI agents.

- **URL**: https://apify.com/kdatafactory/circlechart-scraper.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 $3.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

## Circle Chart (Gaon) Scraper 🎵

Scrape **Circle Chart** ([circlechart.kr](https://circlechart.kr)) — **Korea's official
music industry chart** (formerly the Gaon Chart), published by the Korea Music Content
Association. Get the weekly & monthly **Album**, **Digital** and **Global K-pop** charts as
clean, structured JSON, CSV, or Excel: rank, song/album title, artist, production &
distribution company, physical album sales, and week-over-week rank movement.

Circle Chart is the chart the K-pop industry itself runs on — album sales certifications,
year-end awards, and label reporting all trace back to it. This actor turns it into a
machine-readable feed.

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

***

### 🚀 What it does

Pick a **chart** and a **period** and it returns one full chart edition:

| Chart | What you get | Entries | Example input |
|-------|--------------|---------|---------------|
| `album` | Physical **album sales** ranking — with per-period and cumulative sales counts | 100 | `{ "chart": "album" }` |
| `digital` | The **Digital Chart** (streaming + downloads + BGM, the site's integrated "onoff" chart) | 200 | `{ "chart": "digital" }` |
| `global` | The **Global K-pop Chart** — K-pop consumption outside Korea | 200 | `{ "chart": "global" }` |

Choose `week` or `month` as the period, and optionally pin a specific edition with `date`
(leave it empty for the latest published edition).

***

### 📥 Input

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `chart` | string | `album` | `album`, `digital`, or `global`. |
| `period` | string | `week` | `week` or `month`. |
| `date` | string | *(latest)* | Weekly: any date inside the chart week as `YYYYMMDD` (weeks run Sunday–Saturday). Monthly: `YYYYMM` or `YYYYMMDD`. Empty = latest published edition. |
| `maxItems` | integer | `100` | Max chart entries to return (one edition has up to 100/200 entries). |
| `proxyConfiguration` | object | off | Optional Apify proxy. Not required — enable for IP diversity at scale. |

**Input example — this week's Digital Chart, full 200 entries:**

```json
{
  "chart": "digital",
  "period": "week",
  "maxItems": 200
}
```

***

### 📤 Output

Each chart entry is one dataset record in this shape (real samples from live runs):

```json
{
  "source": "circlechart",
  "chart_type": "album",
  "period": "week",
  "chart_period": "2026-W27",
  "rank": 1,
  "title": "V8",
  "artist": "V8 (SEVENTEEN)",
  "album": "V8",
  "production": null,
  "distributor": "YG PLUS",
  "album_sales": 558725,
  "album_sales_total": 558725,
  "rank_status": "new",
  "rank_change": null,
  "image_url": "https://circlechart.kr/uploadDir/aoaAlbumImg/thumb/20260629_FE1D1113E2AECB8778A8850670B3E769.jpg",
  "scraped_at": "2026-07-10T15:26:26.613+09:00"
}
```

```json
{
  "source": "circlechart",
  "chart_type": "digital",
  "period": "week",
  "chart_period": "2026-W27",
  "rank": 1,
  "title": "REDRED",
  "artist": "CORTIS (코르티스)",
  "album": "REDRED",
  "production": "BIGHIT MUSIC",
  "distributor": "YG PLUS",
  "album_sales": null,
  "album_sales_total": null,
  "rank_status": "same",
  "rank_change": 0,
  "image_url": "https://circlechart.kr/uploadDir/albumImg/thumb/20260423_E3EC3E2BF99B063A9FE9DF57CD2A4F31.jpg",
  "scraped_at": "2026-07-10T15:26:52.776+09:00"
}
```

**Field notes**

- `chart_period` — the chart edition: `2026-W27` (weekly, chart weeks run Sunday–Saturday)
  or `2026-06` (monthly).
- `title` — the charted song; on the **album chart** the charted work is the album itself,
  so `title` equals `album` there.
- `production` / `distributor` — the production company (label) and distribution company
  as published by the chart. The **album chart publishes only the distributor**, so
  `production` is `null` on album-chart rows (see Known limitations).
- `album_sales` / `album_sales_total` — **album chart only**: physical copies sold in the
  chart period, and cumulative. `null` on digital/global rows.
- `rank_status` / `rank_change` — movement vs the previous edition: `up`/`down`/`same`/
  `new`/`hot`, with `rank_change` as a signed step count (`+3` = climbed three spots;
  `null` for new entries).
- A 30-record real sample (10 per chart) lives in
  [`samples/sample-output.json`](samples/sample-output.json).

***

### 💡 Use cases

- **K-pop market research** — track which artists, albums, and labels dominate Korea's
  official charts, week by week, with real physical sales numbers.
- **Trend & breakout detection** — `new`/`hot` entries and big `rank_change` jumps on the
  official industry chart are the strongest early signal in Korean music.
- **Label / publisher analytics** — aggregate by `production` and `distributor` to measure
  label market share over time (HYBE vs SM vs JYP vs YG, distributor consolidation, etc.).
- **K-pop merch & commerce intelligence** — pair chart momentum with album/goods
  availability and photocard resale prices (see the companion actors below) to time
  inventory and pricing.
- **AI agents & LLM pipelines** — a clean, official, weekly-refreshing K-pop dataset for
  RAG, dashboards, or automated newsletters.

***

### 🌐 Data source

This actor reads Circle Chart's **public** chart API on `circlechart.kr` — the same POST
JSON endpoints the chart pages themselves call to render their tables (`/data/api/chart/album`,
`/data/api/chart/onoff`, `/data/api/chart/global`). No login, no private API. The endpoints
are datacenter-friendly, so **no proxy is required**; you can enable an Apify proxy for IP
diversity when running at scale.

Charts publish with a few days' lag (weekly editions typically go up mid-week for the
previous Sunday–Saturday week). When you leave `date` empty, the actor automatically finds
the **latest published edition**, stepping back past editions the site has not posted yet.

***

### ⚠️ Known limitations (honest notes)

- **`production` is `null` on the album chart.** The album chart publishes only the
  distribution company (`distributor`); production companies are published on the digital
  and global charts. This is how the source works, not a bug.
- **No play/stream counts.** The digital and global chart APIs return ranks and rank
  movement but no absolute play counts (the site displays none either). Only the album
  chart carries quantities (`album_sales`).
- **Week & month only.** The site also has day/half-year/year views for some charts;
  v0.1 covers the two editions that exist consistently across all three charts.
- **One edition per run.** A run returns one chart edition (up to 100/200 entries). For
  time series, schedule the actor or loop over `date` values.
- **Historical depth varies.** Recent years are verified; the global chart's own date list
  starts in late 2021. Very old editions may not resolve for every chart.

***

### ⚖️ Rate & legality note

- Only **public, aggregated industry data** is collected — the official chart tables anyone
  can see without logging in. **No personal data exists in this source**: artist, album,
  and production/distribution company names are public commercial attribution (like an
  author or publisher credit). No user comments, nicknames, or profiles are collected.
- Requests are **rate-limited** (a run makes a handful of requests at most, ≥500 ms apart)
  to stay light on the site.
- You are responsible for complying with circlechart.kr's Terms of Service and applicable
  law in your jurisdiction. Use the data for research, monitoring, and analytics — not to
  replicate the platform.

***

### ❓ FAQ

**Is it legal to scrape this data?**
This actor collects only public, aggregated industry chart data — the same tables any visitor sees on circlechart.kr. There is no personal data in this source; artist and company names are public commercial attribution. You are responsible for how you use the data; see the rate & legality note above.

**What does it cost in practice?**
$3.00 per 1,000 results (launch pricing) + a few cents of platform usage. Example: pulling the full 200-entry Digital Chart weekly costs about $0.60/week. Apify's free $5 monthly credit covers ~1,600 results.

**Do I need to configure proxies?**
No — the default settings work out of the box. Optionally, enable an Apify proxy for IP diversity when running at scale.

**How fresh is the data?**
Every run reads the live chart API at run time. Weekly editions publish a few days after the chart week ends; with `date` left empty you always get the latest published edition. Schedule the actor weekly for a continuous chart history.

**What is NOT included?**
Play/stream counts (the source publishes ranks, not volumes, outside album sales), production companies on the album chart (distributor only), the site's day/half/year views, and the niche retail/social charts. No personal data of any kind.

***

### 🤖 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/circlechart-scraper",
      "headers": { "Authorization": "Bearer <YOUR_APIFY_TOKEN>" }
    }
  }
}
```

Your agent can then pull Korea's official Circle Chart music rankings 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 — together
they form a **K-pop data suite** (official charts + albums & goods + photocard resale market):

- [ktown4u-scraper](https://apify.com/kdatafactory/ktown4u-scraper) — K-pop albums & goods store, product & price data.
- [pocamarket-scraper](https://apify.com/kdatafactory/pocamarket-scraper) — K-pop photocard marketplace listings & prices.
- [kpop-photocard-index](https://apify.com/kdatafactory/kpop-photocard-index) — aggregated photocard price index by artist & member.

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

***

### 🏃 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/circlechart-scraper) helps a solo maintainer a lot. Found an issue? Open it in the Issues tab — I respond fast.*

# Actor input Schema

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

'album' = physical album sales chart (with per-period sales counts). 'digital' = the Digital Chart (streaming + downloads + BGM, the site's onoff chart). 'global' = the Global K-pop Chart.

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

Chart aggregation period: weekly or monthly.

## `date` (type: `string`):

Which edition to pull. Weekly: any date inside the chart week as YYYYMMDD (weeks run Sunday-Saturday). Monthly: YYYYMM or YYYYMMDD. Leave empty for the latest published edition (recommended).

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

Maximum number of chart entries to return. One edition has up to 100 (album) or 200 (digital, global) entries.

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

Optional Apify proxy. The chart JSON API is not IP-blocked, so a proxy is not required; enable one for IP diversity at scale.

## Actor input object example

```json
{
  "chart": "album",
  "period": "week",
  "maxItems": 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 = {
    "chart": "album"
};

// Run the Actor and wait for it to finish
const run = await client.actor("kdatafactory/circlechart-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 = { "chart": "album" }

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

```

## MCP server setup

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

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/acts/duTsfwMb1235l8V6H/builds/Wyu2eU8DyUkCNTfb4/openapi.json