A Python client for the chartmetric.com API.
Project description
pycmc
A Python client for the Chartmetric API. Query artists, their music, and where their fans listen.
And do it all in Python.
Installation
We highly recommend you install pycmc
into some type of virtual environment.
Then you should use pip or the like:
pip install pycmc
or
pipenv install pycmc
:warning: You're not done yet; you'll need to set an authentication environment variable for queries.
Quick start
If you're already setup with your environment variable, you can query Rihanna's metadata with a quick call to the artist
module:
>>> import pycmc
>>> rihanna_metadata = pycmc.artists.metadata(cmid=2316)
Yep, it's that simple.
"You should remember that it's peace of mind you're after and not just a fixed machine." -- Robert Pirsig, via Phaedrus
Authentication
Chartmetric requires an authorization process to query their API. You can see their docs here.
Add the CMCREDENTIALS
environment variable
For pycmc
you need to set a single
environment variable, CMCREDENTIALS
, to equal your JSON authentication string of the following:
{
"token":"",
"scope":"",
"expires_in":"",
"refreshtoken":"your-chartmetric-token-here",
}
:mag_right: Be sure the above is a string when you set your environment variable.
How to set up pycmc
authentication
- Save the JSON file above to disk and note the absolute directory.
- Using your absolute directory below,
# REQUIRED - Set your environment variable
export CMCREDENTIALS=$(cat path/to/credentials/file.json)
# OPTIONAL - Remove the .json file you created
rm -rf path/to/credentials/file.json
Design
To somewhat follow the API design of chartmetric and make our lives easier here,
we'll roughly adhere to the following module design where the pycmc
package
contains the following modules:
album
artist
charts
curator
playlist
track
credentials
credentials_manager
utilities
Each module above provides (most) methods for a specific endpoint to the chartmetric.com API, (mostly) labelled as their GET endpoints.
For example,
>>> 'API ALBUM META URL' = 'https://api.charmetric.io/api/album/:id'
Album Metadata
To get an album's metadata just call the metadata function:
>>> import pycmc
>>> pycmc.album.metadata('chartmetricID') # return dict of album metatdata
Spotify top charts
Obviously we'll start with the elephant in the room and get the top charts from Spotify.
What was the US jamming to on the first day of the new year?
>>> cstracks = pycmc.charts.spotify.tracks(date='2019-01-01', )
Apple Music videos charts
What videos are charting in Apple Music on the same day as above?
>>> applemusic_vcharts = pycmc.charts.itunes.videos(date='2019-01-01')
Track metatdata
Let's get some metadata on the track Believe It by PARTYNEXTDOOR and Rihanna:
>>> believe_it = pycmc.track.metadata(cmid='28856569', )
Reference Documentation
We have hosted documentation over at our docs site pycmc.docs.musicfox.io, which review the many endpoints offered by the Chartmetric API.
Problems? Ideas?
We'd love to hear your feedback. Please use the Github for communication about pycmc
.
🐛 Bug Reports 🐞
Please report bugs or problems in our issues in the Github repository.
🍨 Feature Requests
If you have an idea for a feature or suggestion, please open an issue the Github repository, linked herein. Please describe what you're trying to
accomplish and your idea to fix it with pycmc
.
Contibutors
Contributions are quite welcome and it's very easy to get started.
We ❤ community contributions!
Do note, we do require a contributor license agreement such that contributors' contributions are protected property, outside of the "open-source" MIT license covering code here.
Please see our CONTRIBUTING.md
to get started.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.