# Billboard Charts History Scraper (`maximedupre/billboard`) Actor

Collect current or historical entries from public Billboard chart pages. Choose song, album, artist, or genre charts and get ranks, titles, artists, chart weeks, performance fields, and source links.

- **URL**: https://apify.com/maximedupre/billboard.md
- **Developed by:** [Maxime Dupré](https://apify.com/maximedupre) (community)
- **Categories:** Business, Developer tools, News
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$0.90 / 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.

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

### 🎵 Billboard chart history for music research

Billboard researchers, music analysts, journalists, and developers can collect current or historical entries from public Billboard chart pages. Each dataset row gives the chart, title, artist, chart week, rank, performance context, entry status, and source page when Billboard shows those values. This makes it easier to compare chart movement, build music research datasets, and review a specific week.

- Review a full current or historical **[Billboard Hot 100](https://apify.com/maximedupre/billboard/examples/billboard-hot-100)** chart.
- Check the latest weekly entries with **[Billboard Hot 100 This Week](https://apify.com/maximedupre/billboard/examples/billboard-hot-100-this-week)**.
- Collect album ranks and artist names with **[Billboard 200 Albums](https://apify.com/maximedupre/billboard/examples/billboard-200-albums)**.
- Collect another album ranking with **[Billboard Top Albums](https://apify.com/maximedupre/billboard/examples/billboard-top-albums)**.
- Read the first ten song ranks with **[Top 10 Songs This Week](https://apify.com/maximedupre/billboard/examples/top-10-songs-this-week)**.

#### 📊 Billboard chart entries

The Actor saves one row for each chart entry it receives. Rows include chart identity, song or album title, artist, chart week, rank, prior position, peak position, weeks on chart, entry status, and a source page link when those values are available. Current-week rows omit `requestedDate`. Historical rows also show the date used to request the page. If Billboard does not show a value, the row keeps it as `null` instead of guessing.

#### ▶️ Run Billboard charts by week

Choose Current chart week for the latest available weekly entries or Historical chart range for weekly entries between two dates. Add one or more public Billboard chart page URLs. Billboard uses a weekly cadence; for historical runs, `chartWeek` shows the actual chart week returned when the source adjusts a requested date.

**Run steps**

1. Add one or more public Billboard chart page URLs.
2. Choose Current chart week or Historical chart range.
3. For a historical run, add the start and end dates. Leave Maximum entries empty to return all available results until the source is exhausted.
4. Start the run and open the returned dataset URL.

#### ⚙️ Input

The fields below are the public inputs. Date fields apply only to Historical chart range and are ignored for Current chart week. Leaving `maxItems` empty returns all available results until the source is exhausted.

**Input fields**

| Field | Type | What it does |
| --- | --- | --- |
| `target` | string | Chooses `current` for the latest entries or `historical` for weekly entries between two dates. |
| `startDate` | string | First date to request for a historical range, in `YYYY-MM-DD` format. Billboard's weekly chart page determines the returned `chartWeek`. |
| `endDate` | string | Last date to request for a historical range, in `YYYY-MM-DD` format. |
| `charts` | array of objects | One or more public Billboard chart page URLs. Each object has a `url`; major, song, album, artist, and genre charts are supported. |
| `maxItems` | integer | Stops after this many chart entries across the selected charts and weeks. Leaving it empty returns all available results until the source is exhausted. |

**Example input**

```json
{
  "target": "current",
  "charts": [
    {
      "url": "https://www.billboard.com/charts/hot-100/"
    }
  ]
}
```

#### 🧾 Output

The run output includes a link to the entries saved in the default dataset. The dataset rows use the shapes below.

**Run output**

| Field | Type | What it does |
| --- | --- | --- |
| `datasetUrl` | string | Links to the chart entries saved in this run's default dataset. |

**Current-week rows**

Current-week rows contain the fields below and do not include `requestedDate`.

| Field | Type | What it does |
| --- | --- | --- |
| `chart` | object | Identifies the public Billboard chart for the entry. |
| `chart.name` | string | Billboard chart name, such as `Billboard Hot 100`. |
| `chart.slug` | string | Stable slug that identifies the chart. |
| `title` | string | Song or album title shown for the entry. |
| `artist` | string | Artist shown for the entry. |
| `chartWeek` | date string | Billboard chart week returned for the entry. |
| `rank` | integer | Entry position for the returned chart week. |
| `previousRank` | integer or null | Position in the prior chart week, or `null` when Billboard does not show one. |
| `peakRank` | integer or null | Best position on this chart, or `null` when Billboard does not show one. |
| `weeksOnChart` | integer or null | Number of weeks the entry has appeared on the chart, or `null` when Billboard does not show it. |
| `isNewEntry` | boolean or null | Whether the entry is new for the returned chart week, or `null` when Billboard does not show this status. |
| `isReEntry` | boolean or null | Whether the entry returned after being absent, or `null` when Billboard does not show this status. |
| `sourceUrl` | URL string | Link to the Billboard chart page for the entry. |

**Example current row**

```json
{
  "chart": {
    "name": "Billboard Hot 100",
    "slug": "hot-100"
  },
  "title": "Choosin' Texas",
  "artist": "Ella Langley",
  "chartWeek": "2026-08-08",
  "rank": 1,
  "previousRank": 1,
  "peakRank": 1,
  "weeksOnChart": 41,
  "isNewEntry": null,
  "isReEntry": null,
  "sourceUrl": "https://www.billboard.com/charts/hot-100/"
}
```

**Historical rows**

Historical rows contain the same fields plus `requestedDate`, which keeps the date used to request the historical page.

| Field | Type | What it does |
| --- | --- | --- |
| `chart` | object | Identifies the public Billboard chart for the entry. |
| `chart.name` | string | Billboard chart name, such as `Billboard Hot 100`. |
| `chart.slug` | string | Stable slug that identifies the chart. |
| `title` | string | Song or album title shown for the entry. |
| `artist` | string | Artist shown for the entry. |
| `chartWeek` | date string | Billboard chart week returned for the entry. |
| `requestedDate` | date string | Date used to request the historical chart page. |
| `rank` | integer | Entry position for the returned chart week. |
| `previousRank` | integer or null | Position in the prior chart week, or `null` when Billboard does not show one. |
| `peakRank` | integer or null | Best position on this chart, or `null` when Billboard does not show one. |
| `weeksOnChart` | integer or null | Number of weeks the entry has appeared on the chart, or `null` when Billboard does not show it. |
| `isNewEntry` | boolean or null | Whether the entry is new for the returned chart week, or `null` when Billboard does not show this status. |
| `isReEntry` | boolean or null | Whether the entry returned after being absent, or `null` when Billboard does not show this status. |
| `sourceUrl` | URL string | Link to the Billboard chart page for the entry. |

**Example historical row**

```json
{
  "chart": {
    "name": "Billboard Hot 100",
    "slug": "hot-100"
  },
  "title": "All I Want For Christmas Is You",
  "artist": "Mariah Carey",
  "chartWeek": "2025-01-04",
  "requestedDate": "2025-01-04",
  "rank": 1,
  "previousRank": 1,
  "peakRank": 1,
  "weeksOnChart": 71,
  "isNewEntry": null,
  "isReEntry": null,
  "sourceUrl": "https://www.billboard.com/charts/hot-100/2025-01-04/"
}
```

#### 💳 Pricing

This Actor uses pay-per-event pricing. The current primary event is **Chart entry** at `$0.0009` for each entry saved from a selected public chart. The price is tied to the saved chart-entry event; no separate setup or diagnostic event is listed here.

#### 🔌 Integrations

The Actor saves rows to the default dataset and returns a dataset URL. You can read the dataset with Apify exports or the Apify API.

Watch an Apify integrations walkthrough:

https://www.youtube.com/watch?v=bNACk1\_S\_6w\&list=PLObrtcm1Kw6MUrlLNDbK9QRg8VDJg0gOW\&index=4

#### ❓ FAQ

##### Which Billboard chart pages can I submit?

Submit one or more public Billboard chart page URLs. Major, song, album, artist, and genre chart pages are supported when the public source provides them.

##### What is the difference between current and historical runs?

Current chart week returns the latest available weekly entries. Historical chart range requests weekly pages between the dates you provide and adds `requestedDate` to each historical row.

##### What happens when a date does not match a Billboard chart week?

Billboard uses weekly chart pages. The historical row keeps your `requestedDate`, while `chartWeek` shows the actual week returned by Billboard if the source adjusts the requested date.

##### What happens if I leave Maximum entries empty?

The Actor returns all available results until the source is exhausted. Set a positive number when you want the run to stop after a chosen number of entries across the selected charts and weeks.

##### Why are some output values null?

Billboard does not show every field for every entry. The Actor keeps missing source values as `null` and does not infer them.

##### Can one run use more than one chart?

Yes. Add one or more chart page URLs. They use the same current or historical target and the same historical date range in that run; the Actor does not set separate date ranges for individual charts.

##### Does the Actor return article text, streaming totals, or sales data?

No. It returns public chart entries and the fields shown in the Output section. Article bodies, reviews, streaming totals, sales data, and unrelated music metadata are outside this Actor's scope.

### 📝 Changelog

**0.0: Initial release**

### 🆘 Support

For issues, questions, or feature requests, [file a ticket](https://console.apify.com/actors/maximedupre~billboard/issues) and I'll fix or implement it in less than 24h 🫡

### 🔗 Related Actors

- [YouTube Music Scraper](https://apify.com/maximedupre/youtube-music-scraper) — Collect public songs, albums, artists, and playlists from YouTube Music.
- [YouTube Trending Videos Scraper](https://apify.com/maximedupre/youtube-trending-videos-scraper) — Collect ranked YouTube Music charts and category videos by region.
- [SoundCloud Scraper](https://apify.com/maximedupre/soundcloud-scraper) — Collect public tracks, artists, albums, playlists, and comments from SoundCloud.
- [Billboard Charts History Scraper](https://apify.com/jungle_synthesizer/billboard-charts-history-scraper) — Pull historical Billboard chart ranks and performance fields for a comparable workflow.
- [Official Charts UK Singles & Albums Chart Scraper](https://apify.com/jungle_synthesizer/officialcharts-uk-singles-albums-chart-scraper) — Collect weekly UK singles, albums, and genre chart positions as another chart source.

**Made with ❤️ by Maxime Dupré**

# Actor input Schema

## `target` (type: `string`):

Choose Current chart week for the latest entries or Historical chart range for weekly entries between two dates.

## `startDate` (type: `string`):

First date to request for Historical chart range. Use YYYY-MM-DD. Billboard uses weekly charts, so the Actor follows the chart week returned by Billboard.

## `endDate` (type: `string`):

Last date to request for Historical chart range. Use YYYY-MM-DD. The output shows the actual Billboard chart week.

## `charts` (type: `array`):

Add one or more public Billboard chart page URLs. Major, song, album, artist, and genre charts are supported. Add one object per chart, for example \[{"url":"https://www.billboard.com/charts/hot-100/"}].

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

Stop after this many chart entries across all selected charts and weeks. Leave it empty to return all available results until the source is exhausted.

## Actor input object example

```json
{
  "target": "current",
  "charts": [
    {
      "url": "https://www.billboard.com/charts/hot-100/"
    }
  ]
}
```

# Actor output Schema

## `datasetUrl` (type: `string`):

Link to the chart entries saved in this run's default dataset.

# 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 = {
    "target": "current",
    "charts": [
        {
            "url": "https://www.billboard.com/charts/hot-100/"
        }
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("maximedupre/billboard").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 = {
    "target": "current",
    "charts": [{ "url": "https://www.billboard.com/charts/hot-100/" }],
}

# Run the Actor and wait for it to finish
run = client.actor("maximedupre/billboard").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 '{
  "target": "current",
  "charts": [
    {
      "url": "https://www.billboard.com/charts/hot-100/"
    }
  ]
}' |
apify call maximedupre/billboard --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,maximedupre/billboard"
        }
    }
}

```

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/I4VejdPagB9nC9kUh/builds/p10pMIkARlADCZ9r9/openapi.json