pycmc documentation

pycmc.album module

pycmc.album.charts(stype, cmid, start_date, end_date=None)

Query the charts for the given album of a selected streamer type.

https://api.chartmetric.com/api/album/:id/:type/charts

Parameters

  • stype: string streaming platform, choose from

‘applemusic’, ‘itunes’ or ‘amazon’ * cmid: string or int chartmetric album ID * start_date: string start data in ISO format * end_date: string end date in ISO format

Returns

A list of dictionaries of the chart for the given album.

pycmc.album.get_album_ids(id_type, specific_id)

Query all the related album IDs given a specific ID type.

https://api.chartmetric.com/api/album/:type/:id/get-ids

Parameters

  • id_type: string of the type of ID, choose from

‘chartmetric’, ‘upc’, ‘spotify’, ‘itunes’, ‘deezer’ * specific_id: specific ID corresponding to the id_type

Returns

A list of dictionaries with various types of ID.

pycmc.album.metadata(cmid)

Query the album metadata endpoint given the chartmetric ID.

https://api.chartmetric.com/api/album/:id

Parameters

  • cmid: string or int Chartmetric album ID

Returns

A dictionary of album metadata.

pycmc.album.playlists(cmid, start_date, end_date=None, stype='spotify', status='current', indie=False, limit=100)

Query the album playlist placement API endpoint.

https://api.chartmetric.com/api/album/:id/:platform/:status/playlists

Parameters

  • cmid: string or int Chartmetric album ID

  • start_date: string ISO date

  • end_date: string ISO date

  • stype: string streaming platform, choose from ‘spotify, ‘applemusic’, or ‘deezer’

  • status: string ‘current’ or ‘past’

  • indie: Boolean true if playlist created by major labels

  • limit: int number of entries to be returned, maximum acceptable is 100

Returns

A list of dictionaries of playlists for the album.

pycmc.album.stats(cmid, stype, start_date=None, end_date=None)

Query the statistics from the given streaming platform, specifically popularity for Spotify.

https://api.chartmetric.com/api/album/:id/:platform/stats

Parameters

  • cmid: string or int Chartmetric album ID

  • stype: string streaming platform type, only ‘spotify’

  • start_date: string of start date in ISO format

  • end_date: string of end date in ISO format

Returns

A list of dictionaries of the statistics for an album on a streaming platform.

pycmc.album.tracks(cmid)

Query the tracks included in a given album.

https://api.chartmetric.com/api/album/:id/tracks

Parametrs

  • cmid: string or int Chartmetric album ID

Returns

A list of dictionaries of the tracks in an album.

pycmc.album.tunefind(cmid)

Query the album tunefind stats given the Chartmetric ID.

https://api.chartmetric.com/api/album/:id/tunefind

Parameters

  • cmid: string or int Chartmetric album ID

Returns

A list of dictionaries of tunefind stats.

pycmc.artist module

pycm.artist

pycmc.artist.albums(cmid)

Get the albums for the artist given CMID.

https://api.chartmetric.com/api/artist/:id/albums

Parameters

  • cmid: string or int Chartmetric artist ID

Returns

A dictionary of artist metatdata.

pycmc.artist.charts(chart_type, cmid, start_date, end_date=None)

Get the given type of charts for the artist.

https://api.chartmetric.com/api/artist/:id/:type/charts

Parameters

  • chart_type: string type of charts to pull, choose from’spotify_viral_daily’, ‘spotify_viral_weekly’,

‘spotify_top_daily’, ‘spotify_top_weekly’, ‘applemusic_top’, ‘applemusic_daily’, ‘applemusic_albums’, ‘itunes_top’, ‘itunes_albums’, ‘shazam’, ‘beatport’ * cmid: string or int Chartmetric artist ID * start_date: string of start data in ISO format * end_date: string of end date in ISO format

Returns

A list of dictionaries of specific type of charts for the given artist.

pycmc.artist.cpp_data(cmid, cpp_stat, start_date=None, end_date=None)

Get the historical CPP data for the given artist.

https://api.chartmetric.com/api/artist/:id/cpp

Parameters

  • cmid: string or int Chartmetric artist ID

  • cpp_stat: string CPP statistic to pull, choose from’rank’, ‘score’

  • start_date: string of start data in ISO format

  • end_date: string of end date in ISO format

Returns

A list of dictionaries with the specific CPP statistics for the given artist.

pycmc.artist.fanmetrics(cmid, start_date, end_date='today', dsrc='instagram', valueCol=None)

Query the Chartmetric API for artist fan metrics.

https://api.chartmetric.com/api/artist/:id/stat/:source

Parameters

  • cmid: string or int Chartmetric artist ID

  • start_date: string ISO date %Y-%m-%d

  • end_date: string ISO date %Y-%m-%d

  • dsrc: string data source, choose from’spotify’, ‘facebook’, ‘twitter’, ‘instagram’,

‘youtube_channel’, ‘wikipedia’, ‘bandsintown’, ‘soundcloud’ * valueCol: None or string specific data field returned, choose from’followers’, ‘popularity’, ‘listeners’, ‘talks’, ‘subscribers’

Returns

A nested dict, {valueCol: [fanmetrics]}. Fanmetrics are dictionaries of time-series statistics.

pycmc.artist.get_artist_ids(id_type, specific_id)

Get all the linked artist IDs using a given type of ID.

https://api.chartmetric.com/api/artist/:type/:id/get-ids

Parameters

  • id_type: string type of input ID, choose fromchartmetric’, ‘spotify’, ‘itunes’, ‘deezer’

  • specific_id: specific ID corresponding to the id_type

Returns

A list of dictionaries of linked artist IDs.

pycmc.artist.get_artists(filter_field, min_thres, max_thres, offset=0)

Get the statistics of artists filtered by given metrics.

https://api.chartmetric.com/api/artist/:type/list

Parameters

  • id_type: string indicating the field for filtering,’sp_monthly_listeners’ (spotify monthly listeners),

‘sp_followers’ (spotify followers), ‘sp_popularity’ (spotify popularity), ‘sp_listeners_to_followers_ratio’, ‘fs_likes’ (Facebook fan count), ‘fs_talks’ (Facebook people talking about count), ‘ycs_views’ (Youtube channel views), ‘ycs_subscribers’ (Youtube channel subscribers), ‘ws_views’ (Wikipedia pages views), ‘ss_followers’ (Soundcloud followers) * min_thres: minimum threshold for filtering * max_thres: maximum threshold for filtering * offset: number of offsets to shift the timeframe

Returns

A list of dictionaries of the filtered artists.

pycmc.artist.listening(cmid, start_date)

Query the Chartmetric API for Spotify’s WherePeopleListen stats.

https://api.chartmetric.com/api/artist/:id/where-people-listen

Parameters

  • cmid: string or int chartmetric artist ID

  • start_date: string ISO start date for stats

Returns

A dictionary of top listening cities with stats.

pycmc.artist.metadata(cmid)

Query the CHartmetric API for artist metadata.

https://api.chartmetric.com/api/artist/:id

Parameters

  • cmid: string or int Chartmetric artist ID

Returns

A dictionary of artist metatdata.

pycmc.artist.playlists(cmid, dsrc, start_date, status='past')

Get the playlists containing the artist on the specific streaming platform.

https://api.chartmetric.com/api/artist/:id/:type/:status/playlists

Parameters

  • cmid: string or int Chartmetric artist ID

  • dsrc: string data source, choose from’spotify’, ‘applemusic’, or ‘deezer’

  • start_date: string ISO date %Y-%m-%d

  • status: string indicating status of pulled playlists,either ‘current’ or ‘past’

Returns

A list of dictionaries of playlists on the data source for the given artist.

pycmc.artist.related(cmid, limit=50)

Get the related artists for the given artist.

https://api.chartmetric.com/api/artist/:id/relatedartists

Parameters

  • cmid: string or int Chartmetric artist ID

  • limit: int number of entries to be returned,maximum acceptable is 50

Returns

A list of dictionaries of related artists.

pycmc.artist.tracks(cmid)

Get the tracks for the given artist.

https://api.chartmetric.com/api/artist/:id/tracks

Parameters

  • cmid: string or int chartmetric artist ID

Returns

A list of dictionaries of the artist’s tracks.

pycmc.artist.tunefind(cmid)

Query the Chartmetric API for artist tunefind data.

https://api.chartmetric.com/api/artist/:id/tunefind

Parameters

  • cmid: string or int Chartmetric artist ID

Returns

A list of dictionaries of tunefind data for the given artist.

pycmc.artist.urls(cmid)

Query the artist URL endpoint given the chartmetric ID and return the streaming/social/service URLs.

https://api.chartmetric.com/api/artist/:id/urls

Parameters

  • cmid: string or int Chartmetric artist ID

Returns

A dictionary of various URLs for the artist.

pycmc.background module

from github.com/kennethreitz/background

pycmc.background.callback(f)
pycmc.background.default_n()
pycmc.background.run(f, *args, **kwargs)
pycmc.background.task(f)

pycmc.credentials module

credentials

Utilities for the pycmc api credentials interface.

Usage

See credentials_manager for usage details.

pycmc.credentials.Check()

Check that the CMCREDENTIALS environment variable is extant within the environment.

It is important that this causes failure as early in the client init phase as possible. DefaultCredentials will throw if a refreshtoken is unavailable.

Returns

  • boolean True if CMCREDENTIALS exists AND the dictionary contains a non-empty string for the refreshtoken string, otherwise False.

pycmc.credentials.DefaultCredentials(refreshtoken: str) → None

Set the default (only refreshtoken) into the CMCREDENTIALS environment variable, warn the user and raise a KeyError exception.

Parameters

  • refreshtoken: the refresh token queried from the Chartmetric API

pycmc.credentials.FetchAccessToken()

Use the refreshtoken to fetch the access and other credentials from chartmetric.com.

Returns

  • A Python Requests response object in dictionary form with keys:

  • token,

  • expires_in,

  • refresh_token,

  • scope.

 Raises for any non-200 response. See the Requests library documentation.

pycmc.credentials.Load()

Load the credentials from the environment and return the credentials dictionary.

Returns

  • dict of keys:

  • token,

  • scope,

  • expires_in,

  • refreshtoken.

pycmc.credentials.PeriodicUpdate(TTL_seconds=3600, repeat=None)

Wrapper method to take a TTL variable, wait, and call UpdateCredentials. Current chartmetric api documentation (Feb-2019) indicates a credential refresh is required every 3600 seconds.

Parameters

  • TTL_seconds integer seconds to wait between refreshes

  • repeat default: None; integer loops to repeat; -1 = inf

Returns

  • None

pycmc.credentials.TTLwait(func)
pycmc.credentials.Update() → None

Use the CMCREDENTIALS environment variable to make a HTTP GET request for the token, lifetime, and scope attributes and subsequently update the CMCREDENTIALS environment variable.

Returns

  • None

pycmc.credentials.Varname() → str

Returns

The set charmetric credentials environment variable name.

pycmc.credentials_manager module

Credential manager for pycm. Load, store (globally), and automagically update credentials given response TTL seconds.

 You probably shouldn’t do anything with this manually! All you need to do is set your CMCREDENTIALS environment variable to your JSON string of your Chartmetric API token.

Usage:

>>> import credential_manager as cm
>>> print(cm.token)
>>> print(cm.refreshtoken)
>>> print(cm.expires_in) # gives actual seconds to expiry as integer
>>> print(cm.scope)

Note:

The ``expires_in`` global variable here IS NOT a string, as is required for
the api queries; here it is the actual representative TTL count since
our last refresh. **Don't forget to str(expires_in)** for API use.
pycmc.credentials_manager.UpdateCredentials()

TODO Write documentation here.

pycmc.curator module

pycmc.curator.lists(stype, limit=100, offset=0, indie=False, social=True)

Get the chart of curators on the given streaming platfrorm.

https://api.chartmetric.com/api/curator/:platform/lists

Parameters

  • stype: string streaming platform, choose from’spotify’, ‘applemusic’, or ‘deezer’

  • limit: int number of entries returned; maximum acceptable is 100

  • offset: int offset of entries returned

  • indie: boolean True to return the charts not curated by major labels

  • social: boolean True to return social url data

Returns

A Python list of dictionaries of curators.

pycmc.curator.metadata(cmid, stype)

Get the metadata for the curator on a given streaming platform.

https://api.chartmetric.com/api/curator/:platform/:id/

Parameters

  • cmid: string or int Chartmetric curator ID

  • stype: string streaming platform, choose from’spotify’, ‘applemusic’, ‘deezer’

Returns

A dictionary of curator metadata.

pycmc.curator.playlists(cmid, stype)

Get the playlists by the curator on the given streaming platform.

https://api.chartmetric.com/api/curator/:platform/:id/playlists

Parameters

  • cmid: string or in Chartmetric curator ID

  • stype: string streaming platform, choose from’spotify’, ‘applemusic’, ‘deezer’

Returns

A Python list of dictionaries of playlist by the curator

pycmc.playlist module

pycmc.playlist.evolution(cmid, byType)

Get the playlist evolution stats, given artist, album or track CMID.

https://api.chartmetric.com/api/playlist/by/:type/:id/playlist-evolution

Parameters

  • cmid: string Chartmetric {byType} ID

  • byType: string type of evolution stats requested, choose from’artist’, ‘track’, ‘album’

Returns

A nested dict, keys being

  • ‘playlistDataPerDate’ (dicts indexed by dates),

  • ‘statsDataPlot’ (list of lists)

  • ‘playlistDataPlot’ (list of lists)

pycmc.playlist.lists(stype='spotify', sort='followers', country='US', limit=100, offset=0, indie=False)

Get the list of playlists, given the streaming platform.

https://api.chartmetric.com/api/playlist/:streamingType/lists

Parameters

  • stype: string streaming platform, choose from’spotify’, ‘applemusic’, ‘deezer’ or ‘amazon’

  • sort: string column to sort the playlists by, e.g. ‘followers’, ‘last_updated’

  • country: string country code

  • limit: int number of playlists to return,maximum acceptable is 100

  • offset: offset of entries to be returned

  • indie: boolean True to return indie playlists

Returns

A list of dicts of playlists.

pycmc.playlist.metadata(cmid, stype)

Get the metadata for the playlist on streaming platform given CMID.

https://api.chartmetric.com/api/playlist/:platform/:id

Parameters

  • cmid: string or int Chartmetric playlist ID

  • stype: string streaming platform, choose from’spotify’, ‘applemusic’, or ‘deezer’

Returns

A dictionary of playlist metadata.

pycmc.playlist.snapshot(cmid, stype, date)

Get the snapshot of all tracks in a playlist given CMID on a given streaming platform for a given date.

https://api.chartmetric.com/api/playlist/:platform/:id/snapshot

Parameters

  • cmid: string or int Chartmetric playlist ID

  • stype: string streaming platform, choose from’spotify’, ‘applemusic’, ‘deezer’ or ‘amazon’

  • date: string date in ISO format %Y-%m-%d

Returns

A list of dictionaries of tracks contained in the playlist.

pycmc.playlist.tracks(cmid, stype, span='current')

Get the current or past tracks contained in a playlist given CMID on a given streaming platform.

https://api.chartmetric.com/api/playlist/:platform/:id/:span/tracks

Parameters

  • cmid: string or int Chartmetric playlist ID

  • stype: string streaming platform, choose from’spotify’, ‘applemusic’, ‘deezer’ or ‘amazon’

  • span: string ‘past’ or ‘current’

Returns

A list of dictionaries of tracks contained in the playlist.

pycmc.track module

pycmc.track.charts(chart_type, cm_track_id, start_date, end_date=None)

Get the charts of certain type containing this given track since a specified start date.

https://api.chartmetric.com/api/track/:id/:type/charts

Parameters

  • chart_type: string type of chart, choose from’spotify_viral_daily’, ‘spotify_viral_weekly’,

‘spotify_top_daily’, ‘spotify_top_weekly’, ‘applemusic_top’, ‘applemusic_daily’, ‘applemusic_albums’, ‘itunes_top’, ‘amazon’, ‘itunes_albums’, ‘shazam’, ‘beatport’ * cm_track_id: string or int Chartmetric track ID * start_date: string ISO date * end_date: string ISO date

Returns

A list of dictionaries of the charts data.

pycmc.track.get_track_ids(id_type, matching_id)

Get all related track IDs for a given track by a specific ID. There can be multiple corresponding Spotify and iTunes IDs for some tracks.

https://api.chartmetric.com/api/track/:type/:id/get-ids

Parameters

  • id_type: string type of track ID,’chartmetric’ (for cm_track), ‘isrc’,

‘spotify’, ‘itunes’ * matching_id: specific track ID that matches the type

Returns

A list of dictionaries of the related track IDs.

pycmc.track.metadata(cmid)

Get the metadata for the track given CMID.

https://api.chartmetric.com/api/track/:id

Parameters

  • cmid: string or int Chartmetric track ID

Returns

dictionary of track metadata

pycmc.track.playlist_snapshot(cmid, platform, date, limit=100, offset=0)

Get the snapshot of playlists on the platform containing the track for a given date.

https://api.chartmetric.com/api/track/:id/:platform/playlists/snapshot

Parameters

  • cmid: string or int Chartmetric track ID

  • platform: string ‘spotify’, ‘applemusic’, ‘deezer’

  • date: string ISO date

  • limit: int number of entries to be returned; maximum acceptable is 100

  • offset: int offset of entries to be returned

Returns

A list of dictionaries of playlists data.

pycmc.track.playlists(cmid, platform, status='current', start_date=None, end_date=None, indie=False, limit=100, offset=0)

Get the current or past playlists containing the track on the given streaming platform.

https://api.chartmetric.com/api/track/:id/:platform/:status/playlists

Parameters

  • cmid: string or int Chartmetric track ID

  • platform: string ‘spotify’, ‘applemusic’, ‘deezer’, ‘amazon’

  • status: string ‘past’ or ‘current’

  • start_date: string ISO start date

  • end_date: string ISO end date, default today

  • indie: bool, False for playlist curated by major label

  • limit: int number of entries to be returned; maximum acceptable is 100

  • offset: int offset of entries, use this to recursively acquire

Returns

A list of dictionaries of playlists data.

pycmc.track.stats(cm_track_id, platform, start_date=None, end_date=None)

Get the value time-series for the given track on the given platform. Specifically, get popularity for Spotify, views for YouTube and count for Shazam.

https://api.chartmetric.com/api/track/:id/:platform/stats

Parameters

  • cm_track_id: string or int Chartmetric track ID

  • platform: string of streaming platform, choose from’spotify’, ‘youtube’, ‘shazam’

  • start_date: string date in ISO format

  • end_date: string date in ISO format, default is today

Returns

A list of dictionaries of the track value stats time-series.

pycmc.track.tunefind(cmid)

Get the Tunefind stats given the track.

https://api.chartmetric.com/api/track/:id/tunefind

Parameters

  • cmid: string or int Chartmetric track ID

Returns

A list of dictionaries of Tunefind data.

pycmc.utilities module

utilities.py

Utilities for the pycmc api interface.

pycmc.utilities.BaseURL()
pycmc.utilities.FindProcess(name)

Return a list of processes matching given name.

Parameters

  • name: string process name

Returns

list of items matching process ‘name’

pycmc.utilities.ProjectRootDir()

Return path to root directory of project with trailing slash.

Returns

string path with trailing /

pycmc.utilities.RequestData(urlhandle, params)

Build chartmetric data object and call requests.get with constructed data.

Parameters

  • urlhandle: string additional url after base

with a leading and without ending slash * params: dictionary of keyword data to send in the query string, specific to the particular api endpoint

Returns

A dictionary with keys url, headers and params.

pycmc.utilities.RequestGet(data)

Method to call requests.get with data.

Parameters

  • data: dictionary with at least the followingkey:value pairs: url, headers, params

Returns

A dictionary of request data.

pycmc.utilities.TTLwait(func)

Utility waiting function for the credentials.PeriodicUpdate method.

Parameters

  • func: function PeriodicUpdate from the credentials.py module

Returns

credentials.PeriodicUpdate method instantiation

pycmc.utilities.strDateToday()

Simple method to return the string date of today as given by the datetime module.

Specifically, a string is returned in ISO Year-Month-Day format.

Parameters

None

Returns

A Python str representing the ISO date.

pycmc.utilities.strWeekday(date: str, target: int, after: bool = False) → str

Given a ISO string date return the nearest target weekday.

Parameters

  • date: The date around which the caller would like target searched.

  • target: Weekday number as in the datetime Standard Library Module.

Returns

The ISO YYYY-MM-DD string representation of the nearest given weekday.

Module contents

pycmc: Python Chartmetric Client Documentation pycmc.charts.applemusic module