# Billboard Music Charts Scraper (`automation-lab/billboard-music-charts-scraper`) Actor

Export current and historical Billboard chart rankings with dates, artists, prior ranks, peak positions, weeks on chart, artwork, and source URLs.

- **URL**: https://apify.com/automation-lab/billboard-music-charts-scraper.md
- **Developed by:** [Stas Persiianenko](https://apify.com/automation-lab) (community)
- **Categories:** For creators
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.46 / 1,000 item extracteds

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?

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

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

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

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

```json
{
  "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

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

#### Historical Billboard 200 sample

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

#### Same-date song and album market snapshot

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

### Output example

A current run produces records in this shape:

```json
{
  "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

```bash
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

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

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

```bash
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:

```json
{
  "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](https://apify.com/automation-lab/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.

# Actor input Schema

## `chartSlugs` (type: `array`):

Billboard chart identifiers from /charts/ URLs. Defaults to hot-100. Examples: hot-100, billboard-200, artist-100.

## `dates` (type: `array`):

Optional Billboard chart edition dates in YYYY-MM-DD format. Leave empty for each chart's latest published edition.

## `startUrls` (type: `array`):

Optional direct Billboard /charts/ URLs. When supplied, these replace chartSlugs and dates. Current and dated chart URLs are supported.

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

Maximum number of ranked entries saved across all requested chart editions.

## Actor input object example

```json
{
  "chartSlugs": [
    "hot-100"
  ],
  "dates": [],
  "startUrls": [],
  "maxItems": 20
}
```

# Actor output Schema

## `dataset` (type: `string`):

All ranked entries extracted from the requested chart editions.

# 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 = {
    "chartSlugs": [
        "hot-100"
    ],
    "startUrls": [],
    "maxItems": 20
};

// Run the Actor and wait for it to finish
const run = await client.actor("automation-lab/billboard-music-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 '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "chartSlugs": ["hot-100"],
    "startUrls": [],
    "maxItems": 20,
}

# Run the Actor and wait for it to finish
run = client.actor("automation-lab/billboard-music-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 '{
  "chartSlugs": [
    "hot-100"
  ],
  "startUrls": [],
  "maxItems": 20
}' |
apify call automation-lab/billboard-music-charts-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,automation-lab/billboard-music-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 <APIFY_API_TOKEN>` 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/VcfxOAudYDqGpT1ao/builds/lPXSX2BqLSLQUbQza/openapi.json