A fully-fledged installable python package for extracting top 200 and viral 50 charts off of spotifycharts.com
A fully-fledged installable python package for extracting top 200 and viral 50 charts off of spotifycharts.com
In a nutshell, the unofficial Spotify Charts API
This was built to fill the gap left when Spotify deprecated their official Spotify charts API. It arose as a needed crawler for the Spotify data analysis and machine learning project done here
fycharts exposes both a set of functions (an API), and a CLI.
pip install fycharts
Note: The CLI is only available for fycharts>=4.0.0
Say you want to extract top 200 daily charts for all time, all regions:
myCrawler.py
from fycharts.SpotifyCharts import SpotifyCharts
api = SpotifyCharts()
api.top200Daily(output_file = "top_200_daily.csv")
Then: python myCrawler.py
fycharts top200Daily --csv top_200_daily.csv
Or you want viral 50 daily charts for January 2019 in the us and globally, to be written into a csv file and a SQLLite db
Note: This works only for fycharts>=3.0.0
myCrawler.py
from fycharts.SpotifyCharts import SpotifyCharts
import sqlalchemy
api = SpotifyCharts()
connector = sqlalchemy.create_engine("sqlite:///spotifycharts.db", echo=False)
api.viral50Daily(output_file = "viral_50_daily.csv", output_db = connector, webhook = ["https://mywebhookssite.com/post/"], start = "2019-01-01", end = "2019-01-31", region = ["us", "global"])
Then: python myCrawler.py
fycharts viral50Daily --csv viral_50_daily.csv --webhook https://mywebhookssite.com/post/ --start 2019-01-01 --end 2019-01-31 -r us -r global
Note: The CLI cannot write to a DB. You can however pass multiple webhooks to POST to:
-w https://mywebhookssite.com/post/1 -w https://mywebhookssite.com/post/2
The API was designed and published first (fycharts<4.0.0) then the CLI was introduced in v4.0.0. The CLI is merely a convinient wrapper over the API.
This means that the rules that apply at the API level, also apply at the CLI level
fycharts chartsName [OPTIONS]
The charts are:
These invoke the API functions exposed by the library
The options are:
-s, --start Start of date range (YYYY-MM-DD)
-e, --end End of date range (YYYY-MM-DD)
-r, --region Region(s) to get the chart for
-c, --csv Output CSV file (only one)
-w, --webhook Output webhook(s)
fycharts --help for the MAN page
The CLI has been tested on Ubuntu 18.04LTS (Bionic Beaver) and Windows 10 Home v1909
For all the charts provided by Spotify, four functions exist:
All four functions take the following parameters:
output_file - CSV file to write the data to (Compulsory for fycharts<3.0.0)
output_db - A connector object for any database supported by SQLAlchemy (only available in fycharts>=3.0.0)
webhook - A HTTP endpoint (or a list of them) to POST the extracted data to (only available in fycharts>=3.0.0)
Create webhooks for testing here: https://webhook.site/ or here: https://beeceptor.com/
start - Start date of range of interest as string with the format YYYY-MM-DD
end - End date of range of interest as string with the format YYYY-MM-DD
region - Region (or a list of regions e.g. ["global", "us", "fr"]) of interest, as a country abbreviation code. "global" is also valid
Refer to COUNTRY CODES below for supported regions.
If not specified, data is extracted for all dates, all regions
The data extracted from spotifycharts.com is written to the output with the following fields:
Position - The song's position during that week or day
Track Name - Name of the song
Artist - Name of artist
Streams - Number of streams for that week or day. Only applicable to top 200 charts
date - This varies
For instance if you set 'start = 2020-01-03' & 'end = 2020-01-15'
For daily charts -> YYYY-MM-DD e.g 2020-01-03
For top 200 weekly chart -> week_start_date--week_end_date e.g 2020-01-03--2020-01-10
For viral 50 weekly chart -> week_start_date--week_start_date e.g 2020-01-03--2020-01-03
region - Region of the chart as a code
spotify_id - Spotify track id ('id' for fycharts < 3.0.0)
Note: When writing to a db, fycharts is setup to write:
1. viral50Daily to the table `viral_50_daily`
2. viral50Weekly to the table `viral_50_weekly`
3. top200Daily to the table `top_200_daily`
4. top200Weekly to the table `top_200_weekly`
Note: To REST endpoints, a JSON payload is sent with the structure:
{
"chart": "top_200_daily",
"data": [
{
"Position": 1,
"Track Name": "The Box",
"Artist": "Roddy Ricch",
"Streams": 2278155,
"date": "2020-01-03",
"region": "us",
"spotify_id": "0nbXyq5TXYPCO7pr3N8S4I"
},
{
"Position": 2,
"Track Name": "Yummy",
"Artist": "Justin Bieber",
"Streams": 1863557,
"date": "2020-01-03",
"region": "us",
"spotify_id": "41L3O37CECZt3N7ziG2z7l"
},
]
}
Only the following country codes are supported so far:
| ad | ca | dk | gr | is | mx | ph | sv |
| ar | ch | do | gt | it | my | pl | th |
| at | cl | ec | hk | jp | ni | pt | tr |
| au | co | ee | hn | lt | nl | py | tw |
| be | cr | es | hu | lu | no | ro | us |
| bg | cy | fi | id | lv | nz | se | uy |
| bo | cz | fr | ie | mc | pa | sg | vn |
| br | de | gb | il | mt | pe | sk | global |
The start date of the range you're interested in, is very specific for each chart. If you enter an invalid date, you'll be prompted with a list of suggestions and given a choice whether to use fycharts' suggestion or your own.
If using multithreading to run multiple functions, the prompt comes up but is non-blocking. You can still respond
To fully take advantage of multithreading, you may write your code as follows:
myCrawler.py
import sqlalchemy
import threading
from fycharts.SpotifyCharts import SpotifyCharts
def main():
api = SpotifyCharts()
connector = sqlalchemy.create_engine("sqlite:///spotifycharts.db", echo=False)
hooks = ["https://mywebhookssite.com/post/", "http://asecondsite.net/post"]
a_thread = threading.Thread(target = api.top200Daily, kwargs = {"output_file": "top_200_daily.csv", "output_db": connector, "webhook": hooks, "start": "2020-01-03", "end":"2020-01-12", "region": ["global", "us"]})
b_thread = threading.Thread(target = api.top200Weekly, kwargs = {"output_file": "top_200_weekly.csv", "output_db": connector, "webhook": hooks, "start": "2020-01-03", "end":"2020-01-12", "region": ["global", "us"]})
c_thread = threading.Thread(target = api.viral50Daily, kwargs = {"output_file": "viral_50_daily.csv", "output_db": connector, "webhook": hooks, "start": "2020-01-03", "end":"2020-01-12", "region": ["global", "us"]})
d_thread = threading.Thread(target = api.viral50Weekly, kwargs = {"output_file": "viral_50_weekly.csv", "output_db": connector, "webhook": hooks, "start": "2020-01-02", "end":"2020-01-12", "region": ["global", "us"]})
a_thread.start()
b_thread.start()
c_thread.start()
d_thread.start()
if __name__ == "__main__":
main()
TAKE NOTE: DO NOT SHARE THE OUTPUT DESTINATION ACROSS THE FUNCTIONS i.e. each function should be writing to its own set of outputs
The API exposes a function that you may find of use:
This function prints a list of valid dates for the kind of data you are interested in.
start - Start date of range of interest as string with the format YYYY-MM-DD
end - End date of range of interest as string with the format YYYY-MM-DD
desired - A string specifying the kind of data desired
Accepts:
* top200Daily
* top200Weekly
* viral50Daily
* viral50Weekly
This changelog loosely follows semantic versioning
Fixed
Fixed
Fixed
Added
Added
Added
Fixed
Changed
Fixed
Added
Improved
FAQs
A fully-fledged installable python package for extracting top 200 and viral 50 charts off of spotifycharts.com
We found that fycharts demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
/Security News
A flawed sandbox in @nestjs/devtools-integration lets attackers run code on your machine via CSRF, leading to full Remote Code Execution (RCE).
Product
Customize license detection with Socket’s new license overlays: gain control, reduce noise, and handle edge cases with precision.
Product
Socket now supports Rust and Cargo, offering package search for all users and experimental SBOM generation for enterprise projects.