Circle Chart (Gaon) Scraper 🎵

Scrape Circle Chart (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:

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

---

📤 Output

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

{
  "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"
}

{
  "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.

---

💡 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:

{
  "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.

🇰🇷 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 — K-pop albums & goods store, product & price data.
• pocamarket-scraper — K-pop photocard marketplace listings & prices.
• kpop-photocard-index — aggregated photocard price index by artist & member.

Browse all: apify.com/kdatafactory

---

🏃 Run it

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

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