Billboard Charts History Scraper

Scrape historical and current Billboard chart data — Hot 100, Billboard 200, Artist 100, genre charts, and more. Specify a date range to collect full chart-run timelines, or omit dates to get the current week across all major charts.

What you get

Each record contains:

Field	Type	Description
chart	string	Chart slug (e.g. hot-100, billboard-200)
chart_date	string	Week-ending date in YYYY-MM-DD format
rank	integer	Chart position (1 = #1)
title	string	Song or album title
artist	string	Artist name(s)
last_week	integer	Rank the prior week (null for new entries)
peak_position	integer	Highest chart position ever reached
weeks_on_chart	integer	Total weeks on this chart
is_new	boolean	First week on the chart
is_reentry	boolean	Returned after a gap
billboard_url	string	Source URL for this chart/date page

How to use

Current week (default)

Leave startDate and endDate empty. The actor fetches the current chart week for every chart in your charts list.

Historical back-fill

Set startDate and endDate to an ISO date range (e.g. 2024-01-01 to 2024-03-31). The actor walks every Saturday-ending chart week in that range — Billboard's native cadence.

Multi-chart run

Set charts to a list of slugs:

{
  "charts": ["hot-100", "billboard-200", "artist-100", "country-songs", "latin-songs"],
  "startDate": "2023-01-01",
  "endDate": "2023-12-31"
}

This produces a full-year view across 5 charts (approximately 250 chart-week pages with 50 to 200 rows each).

Input parameters

Parameter	Type	Default	Description
charts	string[]	Major charts	List of Billboard chart slugs to scrape. Leave empty for all 16 default major charts.
startDate	string	Current week	Start date YYYY-MM-DD. Leave empty for current week only.
endDate	string	Current week	End date YYYY-MM-DD. Defaults to current week if startDate is set.
maxItems	integer	0 (unlimited)	Cap on total records collected.

Available chart slugs (selected)

Slug	Chart name
hot-100	Billboard Hot 100
billboard-200	Billboard 200 (albums)
artist-100	Billboard Artist 100
streaming-songs	Streaming Songs
radio-songs	Radio Songs
digital-song-sales	Digital Song Sales
country-songs	Hot Country Songs
latin-songs	Hot Latin Songs
rock-songs	Hot Rock Songs
rap-song	Hot Rap Songs
r-b-hip-hop-songs	Hot R&B/Hip-Hop Songs
adult-contemporary	Adult Contemporary
adult-pop-songs	Adult Pop Airplay
hot-alternative-songs	Hot Alternative Songs

Billboard has 200+ chart slugs. Any slug from the charts navigation at billboard.com/charts/ will work.

Use cases

• Music analytics — track chart trajectories, peak positions, and weeks-on-chart for any song or artist over any time range
• Journalism and research — pull historical chart data for articles, features, or academic research
• Artist history — reconstruct an artist's full chart-run timeline across all charts
• Trend analysis — compare chart performance across genres and time periods
• Database enrichment — join chart data with streaming, radio, or sales data for deeper analysis

Performance and cost

• Each chart/date page: 200-800 ms fetch time, 50-200 rows extracted
• A full current-week run across 16 default charts: approximately 15 seconds, 945 records
• A full-year back-fill for Hot 100: 52 requests x 100 rows = 5,200 records

Notes

• Billboard chart weeks end on Saturday. When you specify a date range, the actor snaps to the nearest Saturday and steps by 7 days.
• If a requested date redirects (Billboard sometimes adjusts historical dates), the chart_date field reflects the actual chart returned.
• The last_week field is null for new entries (is_new: true) and re-entries (is_reentry: true).