Billboard Music Charts Scraper

Export current and historical Billboard music charts as structured, dated datasets. Choose charts such as the Billboard Hot 100 or Billboard 200 and receive rank, title, artist, previous-week rank, peak rank, weeks on chart, artwork, and a canonical source URL for every entry.

The Actor is designed for recurring artist-performance analysis, music-market reporting, chart movement tracking, and spreadsheet or data-pipeline exports. It reads public Billboard chart pages and does not require a Billboard login.

What can Billboard Music Charts Scraper do?

• Extract the latest published edition of a Billboard chart.
• Select historical editions with an explicit YYYY-MM-DD date.
• Process several charts or dates in one run.
• Accept direct public Billboard /charts/ URLs.
• Stop at a global result limit for predictable runs.
• Return one normalized record per ranked chart entry.
• Preserve the edition date that Billboard reports on the page.
• Export JSON, CSV, Excel, XML, or RSS through Apify Dataset tools.

This Actor exports the public chart snapshot shown by Billboard. It does not calculate streaming totals, sales estimates, audience demographics, or proprietary Billboard methodology inputs.

Who is it for?

Music analysts

Build weekly snapshots of songs, albums, and artists and compare changes in rank, peak, and chart longevity.

Labels and artist teams

Track public chart placement for releases and prepare reproducible reporting datasets with dated source links.

Journalists and researchers

Collect a specific edition rather than manually copying chart rows from a web page.

Data and automation teams

Schedule recurring runs and deliver normalized results to Google Sheets, Airtable, a warehouse, or a webhook.

Why use this Actor?

Billboard chart pages are intended for reading, not bulk analysis. This Actor turns the visible ranking table into stable fields while retaining the chart identity and edition date on every row.

Compared with a one-off page copy, it provides:

1. a consistent schema across supported public chart pages;
2. current and dated URL support;
3. a global item limit across multi-chart inputs;
4. deduplication by chart, edition date, and rank;
5. bounded retry behavior for temporary network and upstream failures;
6. Apify scheduling, integrations, API access, and dataset exports.

What data does it extract?

Field	Type	Meaning
chartSlug	string	Billboard chart identifier, such as hot-100
chartName	string	Display name shown on the chart page
chartDate	string	Actual published edition date in YYYY-MM-DD format
rank	integer	Position in this chart edition
title	string	Song, album, artist, or other ranked entry title
artist	string	Artist or credited performer shown by Billboard
lastWeekRank	integer or null	Previous-edition rank when available
peakRank	integer or null	Best rank reached when available
weeksOnChart	integer or null	Reported number of weeks on the chart
imageUrl	string or null	Billboard-hosted artwork URL when present
sourceUrl	string	Canonical URL for the dated chart edition
scrapedAt	string	ISO 8601 processing timestamp

Movement metrics can be null when Billboard displays a dash or does not publish that metric for a particular entry or chart type.

How to get started

1. Open the Actor in Apify Console.
2. Keep hot-100 in Chart slugs, or add other slugs copied from Billboard /charts/ URLs.
3. Leave Chart edition dates empty for the latest edition, or add one or more dates.
4. Set Maximum chart entries to the number of rows you need.
5. Click Start.
6. Open the Dataset tab and export the results in your preferred format.

The prefilled input returns the latest 20 Billboard Hot 100 entries.

Input parameters

chartSlugs

An array of Billboard chart slugs. Copy the segment immediately after /charts/ in a public chart URL.

{
  "chartSlugs": ["hot-100", "billboard-200"]
}

If neither chart URLs nor chart slugs are supplied, the Actor defaults to hot-100.

dates

Optional edition dates in YYYY-MM-DD format. Each date is combined with every requested chart slug. Leave the array empty to request the latest published edition of each chart.

{
  "chartSlugs": ["hot-100"],
  "dates": ["2025-08-23", "2025-08-30"]
}

Billboard may map a date to its applicable weekly edition. The output always records the actual chartDate exposed by the returned page.

startUrls

Optional direct current or dated Billboard chart URLs. When this field contains at least one URL, it replaces chartSlugs and dates.

{
  "startUrls": [
    { "url": "https://www.billboard.com/charts/billboard-200/2025-08-30/" }
  ]
}

Only HTTPS URLs on billboard.com using the /charts/<slug>/ or /charts/<slug>/YYYY-MM-DD/ shape are accepted.

maxItems

Maximum number of records saved across the entire run. The allowed range is 1–5,000 and the default is 20.

A run can request at most 25 unique chart pages. The Actor processes them sequentially and stops as soon as maxItems is reached.

Example inputs

Latest Billboard Hot 100

{
  "chartSlugs": ["hot-100"],
  "maxItems": 100
}

Historical Billboard 200 sample

{
  "startUrls": [
    { "url": "https://www.billboard.com/charts/billboard-200/2025-08-30/" }
  ],
  "maxItems": 25
}

Same-date song and album market snapshot

{
  "chartSlugs": ["hot-100", "billboard-200"],
  "dates": ["2025-08-30"],
  "maxItems": 200
}

Output example

A current run produces records in this shape:

{
  "chartSlug": "hot-100",
  "chartName": "Billboard Hot 100™",
  "chartDate": "2025-08-30",
  "rank": 1,
  "title": "Golden",
  "artist": "HUNTR/X: EJAE, Audrey Nuna & REI AMI",
  "lastWeekRank": 2,
  "peakRank": 1,
  "weeksOnChart": 9,
  "imageUrl": "https://charts-static.billboard.com/img/...-180x180.jpg",
  "sourceUrl": "https://www.billboard.com/charts/hot-100/2025-08-30/",
  "scrapedAt": "2026-09-02T06:20:00.000Z"
}

Artwork paths and chart rankings change with the selected edition. Treat imageUrl as an optional source reference, not a permanent media asset.

How much does it cost to export Billboard chart rankings?

The Actor uses pay-per-event pricing:

• Start: $0.0001 once per run.
• Chart entry: tiered per saved dataset item.

The current entry tiers are:

Tier	Price per saved chart entry
FREE	$0.000874
BRONZE	$0.000760
SILVER	$0.0005928
GOLD	$0.000456
PLATINUM	$0.000304
DIAMOND	$0.0002128

At BRONZE rates, 25 records cost about $0.0191 including the run start, 100 records cost about $0.0761, and 200 records cost about $0.1521. Your applicable Apify tier determines the exact per-entry rate. Failed or rejected rows are not charged as items.

Scheduling recurring chart tracking

Billboard charts are dated snapshots, so scheduled runs are useful for longitudinal analysis:

1. configure the chart slugs you need;
2. leave dates empty to retrieve the latest available edition;
3. save the task;
4. add a weekly Apify schedule;
5. send each run dataset to your destination.

Each row includes chartSlug, chartDate, and rank, which together form a practical comparison key. Store datasets from successive runs in a warehouse or spreadsheet before calculating movement over time.

Integration ideas

• Google Sheets: append the newest chart edition for editorial reporting.
• Airtable: maintain an artist and release tracking base.
• BigQuery or Snowflake: build rank-history tables keyed by chart and date.
• Webhooks: notify an automation when a scheduled run finishes.
• Make or Zapier: route new datasets into no-code workflows.
• Python notebooks: analyze peak rank, longevity, entries, and exits.

The Actor reports source values; change detection and alert thresholds should be implemented in your downstream workflow.

Use the Apify API

Replace YOUR_TOKEN with an Apify API token. Keep tokens in environment variables or secret stores rather than source code.

cURL

curl -X POST \
  "https://api.apify.com/v2/acts/automation-lab~billboard-music-charts-scraper/runs?token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"chartSlugs":["hot-100"],"maxItems":100}'

JavaScript

import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('automation-lab/billboard-music-charts-scraper').call({
  chartSlugs: ['hot-100', 'billboard-200'],
  dates: ['2025-08-30'],
  maxItems: 200,
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);

Python

import os
from apify_client import ApifyClient

client = ApifyClient(os.environ["APIFY_TOKEN"])
run = client.actor("automation-lab/billboard-music-charts-scraper").call(
    run_input={"chartSlugs": ["hot-100"], "maxItems": 100}
)
items = client.dataset(run["defaultDatasetId"]).list_items().items
print(items)

For larger workflows, start the run asynchronously and poll its status or receive a completion webhook before reading the dataset.

Use with Apify MCP

Add the Actor to Claude Code:

claude mcp add --transport http apify \
  "https://mcp.apify.com?tools=automation-lab/billboard-music-charts-scraper"

Claude Desktop, Cursor, and VS Code setup

Use this equivalent JSON configuration in Claude Desktop, Cursor, or VS Code clients that support remote MCP servers:

{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com?tools=automation-lab/billboard-music-charts-scraper"
    }
  }
}

Example prompts:

• “Run the Billboard Music Charts Scraper for the latest Hot 100 and return the top 20 entries.”
• “Export the Billboard 200 edition dated 2025-08-30 as a dataset.”
• “Collect Hot 100 and Billboard 200 entries for the same date so I can compare song and album market movement.”

Reliability and retry behavior

The Actor uses public server-rendered Billboard chart pages. It does not use a browser, login, or paid proxy fallback.

Network resets, timeouts, HTTP 429 responses, and temporary server errors are retried up to three attempts with bounded exponential backoff. Stable invalid URLs, 404 pages, unsupported content types, and pages without recognizable chart rows fail the run instead of returning a misleading empty dataset.

If Billboard changes its public markup, a run can fail until the parser is updated. Inspect the run log and source URL before retrying.

Limits and data interpretation

• Output reflects the public chart page available when the run executes.
• A requested calendar date may resolve to Billboard's applicable weekly edition.
• Not every chart uses identical metric labels or supplies every movement value.
• artist contains the displayed credit; the Actor does not split collaborators into separate entities.
• The Actor does not enrich entries with Spotify, Apple Music, YouTube, ISRC, label, genre, sales, or streaming data.
• The Actor does not provide future chart editions or non-public Billboard data.
• Historical coverage depends on what Billboard exposes publicly at the requested URL.
• The maximum is 25 chart pages and 5,000 saved entries per run.

Responsible use and legality

Billboard owns its site content and trademarks. This Actor is an independent extraction tool and is not affiliated with or endorsed by Billboard.

Use the data responsibly and only for lawful purposes. Review Billboard's terms, applicable database and copyright rules, and your downstream publication rights. Avoid republishing protected artwork or presenting extracted rankings as your own proprietary measurement. Do not use the Actor to overload the source or circumvent access controls.

The Actor processes public chart pages and does not request private accounts or personal user data.

Troubleshooting

Why did my dated URL return a different chartDate?

Billboard publishes weekly editions. A calendar date can redirect or map to the applicable chart week. The Actor records the actual date exposed by Billboard so your dataset remains reproducible.

Why is a movement metric null?

Billboard can show a dash or omit a metric for a new entry or chart type. Null means the source did not expose a numeric value.

Why did the run fail instead of returning zero rows?

A public chart page should contain ranking rows. Empty or unrecognized HTML usually indicates an upstream change or temporary delivery problem, so the Actor fails closed rather than producing a false empty chart.

Why was my URL rejected?

Only public HTTPS Billboard URLs matching /charts/<chart-slug>/ or /charts/<chart-slug>/YYYY-MM-DD/ are supported. Article, artist, search, and non-Billboard URLs are outside this Actor's scope.

How can I reduce run cost?

Set maxItems to the smallest useful result count and avoid requesting chart/date combinations you do not need. One multi-chart run pays the start event once.

FAQ

Does it support Billboard Hot 100 and Billboard 200?

Yes. Use hot-100 and billboard-200. Other public chart slugs using the same Billboard chart-page structure can also work.

Can I scrape a historical Billboard chart?

Yes. Supply a dated chart URL or combine a chart slug with one or more YYYY-MM-DD dates.

Does it track changes automatically?

The Actor exports dated snapshots. Save recurring datasets and compare them in your spreadsheet, database, notebook, or automation. It does not maintain a hidden cross-run history table.

Does it require a proxy or Billboard account?

No. The supported implementation uses direct public HTML and has no automatic proxy or authenticated mode.

Can I export CSV or Excel?

Yes. Open the run dataset and choose CSV, Excel, JSON, XML, or another supported Apify export format.

Are rows charged if parsing rejects them?

No. The item event is charged only for normalized rows accepted for dataset output.

Related Automation Lab Actors

For a complementary source-specific view, use Spotify Public Weekly Charts Scraper to export public Spotify weekly ranking datasets. The Spotify Actor is a separate source with different chart definitions; do not treat its ranks as Billboard equivalents.

Use Apify schedules and integrations to combine outputs only when your analysis explicitly accounts for source and methodology differences.