# Billboard Charts Scraper: Hot 100 & History (`punkrecordsdata/billboard-charts-scraper`) Actor
Scrape Billboard charts as data: Hot 100, Billboard 200, Global 200 and 12 more, current or any historical week back to 1958, with rank, peak and weeks on chart. Export CSV, Excel, JSON, XML.
- **URL**: https://apify.com/punkrecordsdata/billboard-charts-scraper.md
- **Developed by:** [PunkRecordsData](https://apify.com/punkrecordsdata) (community)
- **Categories:** News, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet
## Pricing
from $1.00 / 1,000 chart entries
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
## 🎵 Billboard Charts Scraper - Hot 100 & Chart History - PunkRecordsData
> 🚀 **Export Billboard charts as data in seconds.** The Hot 100, Billboard 200, Global 200 and 12 more charts, for the current week or any historical week back to 1958, as structured rows: rank, title, artist, last week, peak position, weeks on chart, new-entry and re-entry flags, plus cover art. The June 13, 2020 Hot 100 comes back with Rockstar at #1 (up from #3, week 7). Export to CSV, Excel, JSON or XML.
The Billboard Charts Scraper turns the industry's reference music rankings into datasets. Pick charts and week dates and every position becomes a row; an optional summary row per chart week adds the #1, entry counts and re-entries for fast trend tables.
| 🎯 Target Audience | 💡 Primary Use Cases |
|---|---|
| Music industry analysts and labels | Chart performance tracking across weeks and markets |
| Journalists and playlist curators | Instant historical chart tables for stories |
| Data scientists | 65+ years of Hot 100 history as tidy panel data |
| Marketing teams | Sync campaigns to chart movements automatically |
### 📋 What the Billboard Charts Scraper does
- **Chart entries**: rank, title, artist, last-week position, peak, weeks on chart, NEW and RE-ENTRY flags and the cover image, for every position you request (top-10 to full chart).
- **15 charts**: Hot 100, Billboard 200, Artist 100, Global 200, Global excl. US, Streaming, Radio, Digital Sales, Country, R\&B/Hip-Hop, Rock, Pop Airplay, Latin, Dance/Electronic and Christian.
- **Any week since 1958**: pass dates (YYYY-MM-DD) and each resolves to its Billboard week.
- **Chart-week summaries** (optional): #1 title/artist, total entries, new entries and re-entries per chart week.
> 💡 **Why it matters:** chart positions drive playlisting, booking and marketing decisions, but the site shows one week at a time. Here a decade of Hot 100 history is one input list.
### 📊 Output of the Billboard chart search
Real sample from a live run:
```json
{
"recordType": "chart-entry",
"imageUrl": "https://charts-static.billboard.com/img/2020/04/dababy-xbz-rockstar-w4d-180x180.jpg",
"chart": "hot-100",
"chartDate": "2020-06-13",
"rank": 1,
"title": "Rockstar",
"artist": "DaBaby Featuring Roddy Ricch",
"lastWeek": 3,
"peakPosition": 1,
"weeksOnChart": 7,
"isNew": "No",
"isReEntry": "No",
"error": null
}
```
### ✨ Why choose this Billboard scraper
- **15 charts and full history** through one input, not one actor per chart.
- **Movement fields included** (last week, peak, weeks, new/re-entry), verified against known historical weeks.
- **Cover art as an image column**, presentation-ready.
- **Chart-week summary rows** for instant week-over-week trend tables, a separate switchable event.
- **Position cap control**: pay for a top-10 sweep, not 100 rows you don't need.
### 📈 How this Billboard scraper compares to alternatives
Measured against the Billboard actors on the Apify Store (September 2026):
| | This actor | Closest alternative |
|---|---|---|
| Billable data events | 2 (entries + week summaries) | 1 |
| Charts covered | 15 | Fewer, often Hot 100 only |
| Historical weeks | Back to 1958 by date list | Varies |
| Movement stats verified | Yes (LW/peak/weeks) | Partial |
| Price per 1,000 entries | $1.20 | $1.00 |
### 🚀 How to use the Billboard Charts Scraper
1. Create a free Apify account (with $5 of credit) at console.apify.com.
2. Open this actor's page and click **Try for free**.
3. Pick charts, add week dates (or leave empty for the current week), set positions per chart.
4. Click **Start** and download CSV, Excel, JSON or XML.
### 💼 Business use cases
#### A\&R and label analytics
Track your roster's chart runs across all 15 charts weekly, with peaks and week counts as columns.
#### Music journalism
"Every #1 of the 1990s" is a list of 520 dates in the input, one run, one table.
#### Playlist and radio strategy
Movement flags (new, re-entry, climbing) as data for programming decisions.
#### Longitudinal research
Decades of chart panel data for genre and industry studies.
### 🔌 Automating the Billboard Charts Scraper
Connect to **Make**, **Zapier**, **Slack**, **Airbyte**, **GitHub** or **Google Drive**: a Tuesday chart-refresh schedule, #1-change alerts to Slack, or warehouse syncs of the full history.
### 🌟 Beyond business use cases
- **Research:** music-industry studies with reproducible chart panels.
- **Personal:** your favorite artist's complete chart history.
- **Non-profit:** music-history archives and educational datasets.
- **Experimentation:** clean data for viz portfolios (chart race videos love this).
### 🤖 Ask an AI assistant about this scraper
> "I need the Billboard Hot 100 for every week of 2023 with rank, artist, peak and weeks-on-chart as CSV. Would the Billboard Charts Scraper on Apify (apify.com/punkrecordsdata/billboard-charts-scraper) handle it?"
### ❓ Frequently Asked Questions
#### 🎵 How do I export the Billboard Hot 100 to CSV or Excel?
Select hot-100, click Start, and download from the Storage tab. Add week dates for history.
#### 📅 How far back can I go?
The Hot 100 reaches back to its first week, August 4, 1958; other charts to their own launch dates.
#### 📊 Which charts are included?
15: Hot 100, Billboard 200, Artist 100, both Global charts, Streaming, Radio, Digital Sales and seven genre charts.
#### 🔢 Can I get just the top 10?
Yes, set positions per chart to 10 and each week bills only 10 entries.
#### 🆕 How are debuts and re-entries marked?
`isNew` and `isReEntry` flags per row, with `lastWeek` shown as N/A for them.
#### 🖼 Does it include cover art?
Yes, the image URL per entry renders as a thumbnail column in the dataset view.
#### 💵 What does the summary row add?
Per chart week: the #1 title/artist, total entries, debut count and re-entry count, billed as its own small event.
#### 📦 How many rows can one run return?
Up to 1,000,000 on paid plans (a full year of Hot 100 is 5,200 rows). Free users get a 10-row preview.
#### ⚙️ Does it need an API key?
No. It reads the public chart pages politely with built-in pacing.
#### 🕒 When do new charts appear?
Billboard publishes new charts on Tuesdays; schedule the actor Tuesday evening for the freshest week.
#### 📆 What if my date is not a chart Saturday?
Nearby dates resolve to that week's chart automatically, exactly like the site does.
### 🔌 Integrate with any app
Datasets are available via the Apify API in JSON, CSV, Excel or XML, with webhooks on completion, ready for Python, Sheets or BI tools.
### 🔗 Recommended Actors
- [TikTok Scraper](https://apify.com/punkrecordsdata/tiktok-scraper) - where chart hits are born
- [Pinterest Scraper](https://apify.com/punkrecordsdata/pinterest-scraper) - visual trends around music culture
- [Discord Scraper](https://apify.com/punkrecordsdata/discord-scraper) - fan-community signals
- [F1 Racing Results Scraper](https://apify.com/punkrecordsdata/f1-racing-results-scraper) - another history-deep ranking dataset
> 💡 **Pro Tip:** browse the complete [PunkRecordsData collection](https://apify.com/punkrecordsdata) for more data tools.
**🆘 Need Help?** contact.punkrecordsdata@gmail.com
> **⚠️ Disclaimer:** independent tool, not affiliated with Billboard; only publicly available data.
# Actor input Schema
## `charts` (type: `array`):
Which Billboard charts to scrape.
## `weeks` (type: `array`):
Chart dates as YYYY-MM-DD (Billboard weeks are Saturdays; nearby dates resolve to that week). Leave empty for the current week. Hot 100 history reaches back to 1958-08-04.
## `maxItems` (type: `integer`):
Free users: Limited to 10 items (preview). Paid users: Optional, max 1,000,000
## `positionsPerChart` (type: `integer`):
How many positions to keep from each chart week (e.g. 10 for a top-10).
## `includeChartSummary` (type: `boolean`):
One extra row per chart week: number 1 title/artist, biggest gainer and counts of new entries and re-entries. Billed as its own event.
## Actor input object example
```json
{
"charts": [
"hot-100"
],
"weeks": [],
"maxItems": 10,
"positionsPerChart": 100,
"includeChartSummary": false
}
```
# Actor output Schema
## `overview` (type: `string`):
Key fields per entry
## `fullData` (type: `string`):
Complete dataset with all fields
# 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 '' with your token
const client = new ApifyClient({
token: '',
});
// Prepare Actor input
const input = {
"weeks": [],
"maxItems": 10
};
// Run the Actor and wait for it to finish
const run = await client.actor("punkrecordsdata/billboard-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 '' with your token.
client = ApifyClient("")
# Prepare the Actor input
run_input = {
"weeks": [],
"maxItems": 10,
}
# Run the Actor and wait for it to finish
run = client.actor("punkrecordsdata/billboard-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 '{
"weeks": [],
"maxItems": 10
}' |
apify call punkrecordsdata/billboard-charts-scraper --silent --output-dataset
```
## MCP server setup
```json
{
"mcpServers": {
"apify": {
"type": "http",
"url": "https://mcp.apify.com/?tools=fetch-actor-details,punkrecordsdata/billboard-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 ` 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/GBwh8jKcfdad76DDe/builds/k193lwY1lBMvfMR0b/openapi.json