(Unofficial) Billboard API

Endpoints Reference

Album or Song Rankings

Get the ranked albums or songs for a specific date. Dates should be in the format of YYYY-MM-DD with no leading zeros. Album rankings go from 1 to 200 and Song rankings go from 1 to 100. Album rankings go back as far as 1963-8-24, and Song rankings go back as far as 1958-8-9.

Sample GET Request
http://billboard.modulo.site/charts/{date}?[query-params] date: the date of any Saturday optional query parameters: { filter: desc: only get album or song rankings accepts: 'album' or 'song' min: desc: only get entries rank 'min' (inclusive) and higher accept: int default: 1 max: desc: only get entries rank 'max' (inclusive) and lower accept: int pithy: desc: if 1, only returns Album and Song IDs; otherwise, returns all Album and Song info accept: 0 or 1 default: 0 }
Sample GET Response
GET http://billboard.modulo.site/charts/2011-1-1?max=1 { albums: [ { rank: "1", album_id: "29129", album_name: "Speak Now", artist_id: "371422", display_artist: "Taylor Swift", spotify_id: "5MfAxS5zz8MlfROjGQVXhy" } ], songs: [ { rank: "1", song_id: "24797", song_name: "Firework", artist_id: "305595", display_artist: "Katy Perry", spotify_id: "4lCv7b86sLynZbXhfScfm2" } ] }

Ranking History for Albums or Songs

Get all albums or songs that were ranked at a specific position. Album rankings go from 1 to 200 and Song rankings go from 1 to 100. Use the 'from' and 'to' query parameters to specify the range of dates to return.

Sample GET Request
http://billboard.modulo.site/rank/{filter}/{num}?[query-params] filter: either 'album' or 'song' num: a ranking number optional query parameters: { from: desc: only entries after date 'from' (inclusive) accepts: date (format of YYYY-MM-DD with no leading zeros) to: desc: only entries before date 'to' (inclusive) accepts: date (format of YYYY-MM-DD with no leading zeros) pithy: desc: if 1, only returns Album and Song IDs; otherwise, returns all Album and Song info accept: 0 or 1 default: 0 }
Sample GET Response
GET http://billboard.modulo.site/rank/album/3?from=1984-6-23&to=1984-6-30 [ { date: "1984-06-30", album_id: "11601", album_name: "Born In The U.S.A.", artist_id: "298448", display_artist: "Bruce Springsteen", spotify_id: "0PMasrHdpaoIRuHuhHp72O" }, { date: "1984-06-23", album_id: "11316", album_name: "Can't Slow Down", artist_id: "307447", display_artist: "Lionel Richie", spotify_id: "609oTPBaxPzZUCHzQikOtC" } ]

Artist's Album & Song History

Get an artists's ranked discography. By default, returns all Albums and Songs. Also includes aggregate data: the highest rank each entry has attained and the total number of weeks said entry was ranked. Use the 'from' and 'to' query parameters to specify the range of dates the results will reference.

Sample GET Request
http://billboard.modulo.site/artist/{id}?[query-params] id: an artist's unique ID number optional query parameters: { filter: desc: only get album or song information accepts: 'album' or 'song' from: desc: only entries after date 'from' (inclusive) accepts: date (format of YYYY-MM-DD with no leading zeros) to: desc: only entries before date 'to' (inclusive) accepts: date (format of YYYY-MM-DD with no leading zeros) pithy: desc: if 1, only returns Album and Song info, no aggregates accept: 0 or 1 default: 0 }
Sample GET Response
GET http://billboard.modulo.site/artist/1493192?filter=album { name: "G-Eazy", albums: [ { album_id: "101", album_name: "These Things Happen", spotify_id: "6wDc63NhKy2PyXdbhkRmrl", highest_rank: "3", weeks_on_chart: "105" }, { album_id": "29", album_name: "When It's Dark Out", spotify_id: "09Q3WwGYsQe5ognkvVkmCu", highest_rank: "5", weeks_on_chart: "32" } ] }

Album's or Song's Rank History

Get an Album's or Song's ranking history over time. Returns each week the entry is ranked as well as it's ranking position. Album rankings go from 1 to 200 and Song rankings go from 1 to 100. Use the 'from' and 'to' query parameters to specify the range of dates the results will reference.

Sample GET Request
http://billboard.modulo.site/music/{filter}/{id} filter: either 'album' or 'song' id: an Album's or Song's unique ID number optional query parameters: { from: desc: only entries after date 'from' (inclusive) accepts: date (format of YYYY-MM-DD with no leading zeros) to: desc: only entries before date 'to' (inclusive) accepts: date (format of YYYY-MM-DD with no leading zeros) min: desc: only get dates ranked 'min' (inclusive) and higher accept: int default: 1 max: desc: only get dates rank 'max' (inclusive) and lower accept: int }
Sample GET Response
GET http://billboard.modulo.site/music/song/10150?from=1974-3-30&to=1974-4-13 { song: { song_id: "10150", song_name: "Bennie And The Jets", artist_id: "301679", display_artist: "Elton John", spotify_id: "0LHzd11GIXVmND7TfQnGiy" }, rankings: [ { date: "1974-03-30", rank: "4" }, { date: "1974-04-06", rank: "2" }, { date: "1974-04-13", rank: "1" } ] }

Search Database

Search the database for an Album, Artist, or Artist. The search is case insensitive, and forgiving on extra whitespace. However, spelling is important as the search is not fuzzy.

Sample GET Request
http://billboard.modulo.site/search/{category}?q=... category: either 'album', 'song', or 'artist' required query parameters: { q: desc: the query to search for, case insensitive accepts: string } optional query parameters: { exact: desc: if 1, only returns results that exactly matches the search, case insensitive accept: 0 or 1 default: 0 }
Sample GET Response
GET http://billboard.modulo.site/search/artist?q=kanye [ { artist_id: "276709", artist_name: "Kanye West" } ]