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 ChartData()
constructor.
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 artist
and title
:
>>> song = chart[0] # 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
the entire chart:
>>> 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
# ...
Use the ChartData
constructor to download a chart:
ChartData(name, date=None, fetch=True, timeout=25)
The arguments are:
name
– The chart name, e.g.'hot-100'
or'pop-songs'
. You can browse the Charts page on Billboard.com to find valid chart names; the URL of a chart will look likehttp://www.billboard.com/charts/CHART-NAME
(example). Almost any chart should work; the only chart known not to work isspotify-rewind
.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). IfFalse
, the chart data can be populated at a later time using thefetchEntries()
method.timeout
– The number of seconds to wait for a server response. IfNone
, no timeout is applied.
Every 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)
If chart
is a ChartData
instance, we can ask for its entries
attribute to get the chart entries (see below) as a list.
For convenience, chart[x]
is equivalent to chart.entries[x]
, and ChartData
instances are iterable.
A chart entry (typically a single track) is of type ChartEntry
. A ChartEntry
instance has the following attributes:
title
– The title of the track.artist
– The name of the artist, as formatted on Billboard.com.peakPos
– The track's peak position on the chart at any point in time, including future dates, as an int (orNone
if the chart does not include this information).lastPos
– The track's position on the previous week's chart, as an int (orNone
if 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 help
feature.
Think you 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 the following rules if following them would decrease readability:
- E127 ("continuation line over-indented for visual indent")
- E221 ("multiple spaces before operator")
- E501 ("line too long")
- We use
mixedCase
for variable names. - All-uppercase words remain all-uppercase when they appear at the end of variable names (e.g.
downloadHTML
notdownloadHtml
).
To run all of the tests, run
nosetests
Assuming you have both Python 2.7 and 3.4 installed on your machine, you can also run
tox
to run tests on both versions; see tox.ini
for configuration details.
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
Have an addition? Make a pull request!
- This project is licensed under the MIT License.
- The Billboard charts are owned by Prometheus Global Media LLC. See Billboard.com's Terms of Use for more information.