billboard.py is a Python API for accessing music charts from Billboard.com.
To install with pip, run
pip install billboard.py
You can also clone this repository and run
python setup.py install.
To download a Billboard chart, we use the
Let's fetch the current Hot 100 chart.
>>> import billboard >>> chart = billboard.ChartData('hot-100')
Now we can look at the chart entries, which are of type
ChartEntry and have attributes like
>>> song = chart # Get no. 1 song on chart >>> song.title u'One Dance' >>> song.artist u'Drake Featuring WizKid & Kyla' >>> song.weeks # Number of weeks on chart 15 >>> song.spotifyID u'11hqMWwX7sF3sOGdtijofF'
We can also
>>> print chart hot-100 chart (current) ----------------------- 1. 'One Dance' by Drake Featuring WizKid & Kyla (0) 2. 'Can't Stop The Feeling!' by Justin Timberlake (0) 3. 'Cheap Thrills' by Sia Featuring Sean Paul (+2) # ... 97 more lines
Downloading a chart
ChartData constructor to download a chart:
ChartData(name, date=None, fetch=True, all=False, quantize=True)
The arguments are:
name– The chart name, e.g.
'pop-songs'. You can browse the Charts section of Billboard.com to find valid chart names; the URL of a chart will look like
date– The chart date as a string, in YYYY-MM-DD format. By default, the latest chart is fetched.
fetch– A boolean indicating whether to fetch the chart data from Billboard.com immediately (at instantiation time). If
False, the chart data can be populated at a later time using the
all– Deprecated; has no effect.
quantize– A boolean indicating whether to round the
dateparameter to the nearest date with a chart.
Walking through chart dates
ChartData instance has a
previousDate attribute containing a string representation of the previous chart's date. You can feed this into another
ChartData instance to effectively walk back through previous charts.
chart = billboard.ChartData('hot-100') while chart.previousDate: doSomething(chart) chart = billboard.ChartData('hot-100', chart.previousDate)
Accessing chart entries
chart is a
ChartData instance, we can ask for its
entries attribute to get the chart entries (see below) as a list.
chart[x] is equivalent to
ChartData instances are iterable.
Chart entry attributes
A chart entry (typically a single track) is of type
ChartEntry instance has the following attributes:
title– The title of the track.
artist– The name of the artist, as formatted on Billboard.com. If there are multiple artists and/or featured artists, they will all be included in this string.
peakPos– The track's peak position on the chart, as an int.
lastPos– The track's position on the previous week's chart, as an int. This value is 0 if the track has never been on the chart before.
weeks– The number of weeks the track has been on the chart. This value is 1 if the track is new on the chart.
rank– The track's current position on the chart.
change– A string indicating how the track's position has changed since the previous week. This may be one of the following:
- A signed integer like +4, -1, or 0, indicating the difference between the track's current position and its position on the previous week's chart.
- 'Hot Shot Debut', which means track is the highest-rated track that is completely new to the chart.
- 'New', which means the track is completely new to the chart, yet not the highest rated new track.
- 'Re-Entry', which means the track is re-entering the chart after leaving it for at least a week.
spotifyID– The Spotify ID of the track, or an empty string if it was not provided. This can be used to access more information about the track via the Spotify Web API.
spotifyLink– The Spotify embed URL of the track, generated from the spotifyID. Will be an empty string if no such ID was provided.
videoLink– The video URL of the track. Will be an empty string if no such URL was provided.
For additional documentation, take a look at the source code for
billboard.py, or use Python's interactive
If you're stuck or confused: This is a small project, so you can also just email me (Allen). My contact info is on my profile page.
Found a bug? Create an issue here.
Pull requests are welcome! Please adhere to the following style guidelines:
- In general, follow PEP 8. You may ignore E501 ("line too long") and E127 ("continuation line over-indented for visual indent") if following them would detract from the readability of the code. Use your best judgement!
- We use
mixedCasefor variable names.
- All-uppercase words remain all-uppercase when they appear at the end of variable names (e.g.
To run all of the tests, run
Assuming you have both Python 2.7 and 3.4 installed on your machine, you can also run
to run tests on both versions; see
tox.ini for configuration details.
Made with billboard.py
Projects and articles that use billboard.py:
- "What Makes Music Pop?" by Zach Loery
- "How Has Hip Hop Changed Over the Years?" by Rohan Kshirsagar
- "Spotify and billboard.py" by Allen Guo
- "Top Billboard Streaks" and "Drake's Hot-100 Streak" by James Wenzel @ Polygraph
- "Determining the 'Lifecycle' of Each Music Genre" by Jack Beckwith @ The Data Face
Have an addition? Make a pull request!
- This project is licensed under the MIT License.