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') >>> chart.title 'The 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 'Nice For What' >>> song.artist 'Drake' >>> song.weeks # Number of weeks on chart 2
We can also
>>> print(chart) hot-100 chart from 2018-04-28 ----------------------------- 1. 'Nice For What' by Drake 2. 'God's Plan' by Drake 3. 'Meant To Be' by Bebe Rexha & Florida Georgia Line 4. 'Psycho' by Post Malone Featuring Ty Dolla $ign 5. 'The Middle' by Zedd, Maren Morris & Grey # ...
Listing all charts
charts function to list all chart names:
>>> billboard.charts() ['hot-100', 'billboard-200', 'artist-100', 'social-50', ...
Alternatively, the bottom of this page shows all charts grouped by category.
Downloading a chart
ChartData constructor to download a chart:
ChartData(name, date=None, fetch=True, timeout=25)
The arguments are:
name– The chart name, e.g.
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
max_retries– The max number of times to retry when requesting data (default: 5).
timeout– The number of seconds to wait for a server response. If
None, no timeout is applied.
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.
image– The URL of the image for the track.
peakPos– The track's peak position on the chart as of the chart date, as an int (or
Noneif the chart does not include this information).
lastPos– The track's position on the previous week's chart, as an int (or
Noneif the chart does not include this information). This value is 0 if the track was not on the previous week's chart.
weeks– The number of weeks the track has been or was on the chart, including future dates (up until the present time).
rank– The track's current position on the chart.
isNew– Whether the track is new to the chart.
For additional documentation, look at the file
billboard.py, or use Python's interactive
Think you found a bug? Create an issue here.
Pull requests are welcome! Please adhere to the following style guidelines:
- We use Black for formatting.
- If you have pre-commit installed, run
pre-commit installto install a pre-commit hook that runs Black.
- If you have pre-commit installed, run
- Variable names should be in
We use Travis CI to automatically run our test suite on all PRs.
To run the test suite locally, install nose and run
To run the test suite locally on both Python 2.7 and 3.4, install tox and run
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
- chart_success.py by 3ngthrust
- "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
- "Splunking the Billboard Hot 100 with Help from the Spotify API" by Karthik Subramanian
- "Predicting Movement on 70s & 80s Billboard R&B Charts" by Andy Friedman
- "Billboard Trends" by Tom Johnson
- "Billboard Charts Alexa Skill" by Cameron Ezell
Have an addition? Make a pull request!
- This project is licensed under the MIT License.