Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time
August 20, 2017 11:27
November 20, 2021 18:26
December 8, 2013 12:30
November 20, 2021 18:30
December 8, 2013 12:30
November 20, 2021 18:26
November 20, 2021 18:30
August 17, 2018 22:31

Build Status is a Python API for accessing music charts from


Install with pip:

pip install

Or clone this repo and run python 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')
>>> chart.title
'The 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
>>> song.weeks  # Number of weeks on chart

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
# ...


What charts exist?

This page shows all charts grouped by category.

Year-end charts are here.

Downloading a chart

Use the ChartData constructor to download a chart:

ChartData(name, date=None, year=None, fetch=True, timeout=25)

The arguments are:

  • name – The chart name, e.g. 'hot-100' or 'pop-songs'.
  • date – The chart date as a string, in YYYY-MM-DD format. By default, the latest chart is fetched.
  • year – The chart year, if requesting a year-end chart. Must be a string in YYYY format. Cannot supply both date and year.
  • fetch – A boolean indicating whether to fetch the chart data from immediately (at instantiation time). If False, the chart data can be populated at a later time using the fetchEntries() method.
  • 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.

For example, to download the Alternative Songs year-end chart for 2006:

>>> chart = billboard.ChartData('alternative-songs', year=2006)

Accessing chart entries

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.

Chart entry attributes

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
  • 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 None if the chart does not include this information).
  • lastPos – The track's position on the previous week's chart, as an int (or None 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.

More resources

For additional documentation, look at the file, 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:

  • We use Black for formatting.
    • If you have pre-commit installed, run pre-commit install to install a pre-commit hook that runs Black.
  • Variable names should be in mixedCase.

Running tests

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

Projects and articles that use

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's Terms of Use for more information.