Client¶

class soundchartspy.client.SoundCharts(app_id, api_key)[source]¶

Bases: object

Parameters:

app_id (str)
api_key (str)

Get a song by its SoundCharts UUID.

Parameters:: uuid (str) – The UUID of the song.
Returns:: The song object.
Return type:: Song

Example

>>> soundcharts = SoundCharts(app_id="your_app_id", api_key="your_api_key")
>>> song = soundcharts.song(uuid="7d534228-5165-11e9-9375-549f35161576")

song_by_isrc(isrc)[source]¶

Get a song by its ISRC.

Parameters:: isrc (str) – The ISRC of the song.
Returns:: The song object.
Return type:: Song

Example

>>> soundcharts = SoundCharts(app_id="your_app_id", api_key="your_api_key")
>>> song = soundcharts.song_by_isrc(isrc="USUM71712345")

song_by_platform_id(platform, identifier)[source]¶

Get a song by its platform and identifier.

Parameters:

platform (str) – The platform name (e.g., ‘spotify’).
identifier (str) – The platform-specific song identifier.

Returns:

The song object.

Return type:

Song

Example

>>> soundcharts = SoundCharts(app_id="your_app_id", api_key="your_api_key")
>>> song = soundcharts.song_by_platform_id(platform="spotify", identifier="2Fxmhks0bxGSBdJ92vM42m")

song_ids(uuid, platform=None, offset=0, limit=100)[source]¶

Get platform-specific identifiers for a song.

Parameters:

uuid (str) – The UUID of the song.
platform (str, optional) – A platform name to filter the results.
offset (int, optional) – The starting position of the results. Defaults to 0.
limit (int, optional) – The number of results to return. Defaults to 100.

Returns:

A list of platform identifiers for the song.

Return type:

list[PlatformIdentifier]

Example

>>> soundcharts = SoundCharts(app_id="your_app_id", api_key="your_api_key")
>>> platform_ids = soundcharts.song_ids(uuid="7d534228-5165-11e9-9375-549f35161576", platform="spotify", limit=50)

song_albums(uuid, type='all', offset=0, limit=100, sort_by='title', sort_order='asc')[source]¶

Retrieve albums associated with a song.

Parameters:

uuid (str) – The UUID of the song.
type (str, optional) – Filter by album type. Defaults to ‘all’.
offset (int, optional) – The starting position of the results. Defaults to 0.
limit (int, optional) – The number of results to return. Defaults to 100.
sort_by (str, optional) – Sort by field. Defaults to ‘title’.
sort_order (str, optional) – Sort order. Defaults to ‘asc’.

Returns:

A list of albums associated with the song.

Return type:

list[Album]

Example

>>> soundcharts = SoundCharts(app_id="your_app_id", api_key="your_api_key")
>>> albums = soundcharts.song_albums(uuid="7d534228-5165-11e9-9375-549f35161576", type="album", limit=50, sort_by="releaseDate", sort_order="desc")

song_audience(uuid, platform, start_date=None, end_date=None, identifier=None)[source]¶

Retrieve audience data for a song on a specific platform.

Parameters:

uuid (str) – The UUID of the song.
platform (str) – The platform code.
start_date (str, optional) – The start date for the audience data (format ‘YYYY-MM-DD’).
end_date (str, optional) – The end date for the audience data (format ‘YYYY-MM-DD’).
identifier (str, optional) – A specific song identifier on the platform.

Returns:

Audience data for the song on the specified platform.

Return type:

dict

Example

>>> soundcharts = SoundCharts(app_id="your_app_id", api_key="your_api_key")
>>> audience_data = soundcharts.song_audience(uuid="7d534228-5165-11e9-9375-549f35161576", platform="spotify", start_date="2023-01-01", end_date="2023-03-31", identifier="2Fxmhks0bxGSBdJ92vM42m")

song_spotify_popularity(uuid, start_date=None, end_date=None)[source]¶

Retrieve Spotify popularity data for a song.

Parameters:

uuid (str) – The UUID of the song.
start_date (str, optional) – The start date for the popularity data (format ‘YYYY-MM-DD’).
end_date (str, optional) – The end date for the popularity data (format ‘YYYY-MM-DD’).

Returns:

Spotify popularity data for the song.

Return type:

dict

Example

>>> soundcharts = SoundCharts(app_id="your_app_id", api_key="your_api_key")
>>> spotify_popularity = soundcharts.song_spotify_popularity(uuid="7d534228-5165-11e9-9375-549f35161576")

song_chart_entries(uuid, platform='spotify', current_only=True, offset=0, limit=100, sort_by='position', sort_order='asc')[source]¶

Retrieve chart entries for a song.

Parameters:

uuid (str) – The UUID of the song.
platform (str, optional) – The platform code.
current_only (bool, optional) – Whether to return only current chart entries. Set to False for current and past entries. Defaults to True.
offset (int, optional) – The starting position of the results. Defaults to 0.
limit (int, optional) – The number of results to return. Defaults to 100. Maximum is 100.
sort_by (str, optional) – Sort by field. Defaults to ‘position’. Other options are ‘rankdate’.
sort_order (str, optional) – Sort order. Defaults to ‘asc’. Other options are ‘desc’.

Returns:

Chart entries for the song.

Return type:

dict

Example

>>> soundcharts = SoundCharts(app_id="your_app_id", api_key="your_api_key")
>>> chart_entries = soundcharts.song_chart_entries(uuid="7d534228-5165-11e9-9375-549f35161576", platform="spotify", current_only=True, limit=50)

song_playlist_entries(uuid, platform='spotify', type='all', offset=0, limit=100, sort_by='position', sort_order='asc')[source]¶

Retrieve playlist entries for a song.

Parameters:

uuid (str) – The UUID of the song
platform (str, optional) – The platform code
type (str, optional) – A playlist type. Available values are : ‘all’ or one of editorial, algorithmic, algotorial, major, charts, curators_listeners, radios, this_is
offset (int, optional) – The starting position of the results
limit (int, optional) – The number of results to return. Maximum is 100
sort_by (str, optional) – Sort criteria. Available values are : ‘position’, ‘positionDate’, ‘subscriberCount’, ‘entryDate’
sort_order (str, optional) – Sort order. Available values are : asc, desc

Returns:

A list of playlist entries for the song

Return type:

list[tuple[Playlist, PlaylistPosition]]

Example

>>> soundcharts = SoundCharts(app_id="your_app_id", api_key="your_api_key")
>>> playlist_entries = soundcharts.song_playlist_entries(uuid="7d534228-5165-11e9-9375-549f35161576")

song_radio_spins(uuid, radio_slugs, country_code=None, start_date=None, end_date=None, offset=0, limit=100)[source]¶

Retrieve radio spins for a song.

Parameters:

uuid (str) – The UUID of the song.
radio_slugs (list[str]) – A list of radio slugs.
country_code (str) – The country code.
start_date (str) – Period start date (Format ATOM). Example : 2019-01-01T00:00:00Z
end_date (str) – Period end date (Format ATOM). Example : 2019-01-01T00:00:00Z
offset (int, optional) – The starting position of the results. Defaults to 0.
limit (int, optional) – The number of results to return. Defaults to 100. Maximum is 100.

Returns:

Radio spins for the song.

Return type:

dict

Example

>>> soundcharts = SoundCharts(app_id="your_app_id", api_key="your_api_key")
>>> radio_spins = soundcharts.song_radio_spins(uuid="7d534228-5165-11e9-9375-549f35161576", radio_slugs=["nrj", "funradio"], country_code="FR", start_date="2019-01-01T00:00:00Z", end_date="2019-01-01T00:00:00Z", offset=0, limit=100)

song_radio_spin_count(uuid, radio_slugs, country_code=None, start_date=None, end_date=None, offset=0, limit=100)[source]¶

Retrieve radio spin count for a song.

Parameters:

uuid (str) – The UUID of the song.
radio_slugs (list[str]) – A list of radio slugs.
country_code (str) – The country code.
start_date (str) – Period start date (Format ATOM). Example : 2019-01-01T00:00:00Z
end_date (str) – Period end date (Format ATOM). Example : 2019-01-01T00:00:00Z
offset (int, optional) – The starting position of the results. Defaults to 0.
limit (int, optional) – The number of results to return. Defaults to 100. Maximum is 100.

Returns:

Radio spin count for the song. Example Return = [{“playCount”: 10,”radio”: RadioStation}, {“playCount”: 20,”radio”: RadioStation}]

Return type:

list of dict

Example

>>> soundcharts = SoundCharts(app_id="your_app_id", api_key="your_api_key")
>>> radio_spins = soundcharts.song_radio_spin_count(uuid="7d534228-5165-11e9-9375-549f35161576", radio_slugs=["nrj", "funradio"], country_code="FR", start_date="2019-01-01T00:00:00Z", end_date="2019-01-01T00:00:00Z", offset=0, limit=100)

artist(uuid)[source]¶

Get an artist by its SoundCharts UUID.

Parameters:: uuid (str) – The UUID of the artist.
Returns:: The artist object.
Return type:: artist (Artist)

Example

>>> soundcharts = SoundCharts(app_id="your_app_id", api_key="your_api_key")
>>> artist = soundcharts.artist(uuid="7d534228-5165-11e9-9375-549f35161576")

artist_by_platform_id(platform, identifier)[source]¶

Get an artist by its platform and identifier. :param platform: The platform code (e.g.’spotify’). Usually just the platform name in lowercase, replace spaces with -.

These can be found using the platforms method.

Parameters:

identifier (str) – The platform-specific artist identifier.
platform (str)

Returns:

The artist object.

Return type:

artist (Artist)

artist_ids(uuid, platform=None, offset=0, limit=100)[source]¶

Get platform-specific identifiers for an artist.

Parameters:

uuid (str) – The UUID of the artist.
platform (str, optional) – A platform name to filter the results.
offset (int, optional) – The starting position of the results. Defaults to 0.
limit (int, optional) – The number of results to return. Defaults to 100.

Returns:

A list of platform identifiers for the artist.

Return type:

list[PlatformIdentifier]

Example

>>> soundcharts = SoundCharts(app_id="your_app_id", api_key="your_api_key")
>>> platform_ids = soundcharts.artist_ids(uuid="7d534228-5165-11e9-9375-549f35161576", platform="spotify", limit=50)

artist_songs(uuid, offset=0, limit=100, sort_by='name', sort_order='asc')[source]¶

Get songs associated with an artist.

Parameters:

uuid (str) – The UUID of the artist.
offset (int, optional) – The starting position of the results. Defaults to 0.
limit (int, optional) – The number of results to return. Defaults to 100.
sort_by (str, optional) – Sort by field. Defaults to ‘name’. Available values are : name, releaseDate, spotifyStream, shazamCount, youtubeViews, spotifyPopularity
sort_order (str, optional) – Sort order. Defaults to ‘asc’. Other options are ‘desc’.

Returns:

A list of songs associated with the artist.

Return type:

list[Song]

Example

>>> soundcharts = SoundCharts(app_id="your_app_id", api_key="your_api_key")
>>> songs = soundcharts.artist_songs(offset=0, limit=50)

artist_albums(uuid, type='all', offset=0, limit=100, sort_by='title', sort_order='asc')[source]¶

Get albums associated with an artist. :param uuid: The UUID of the artist. :type uuid: str :param type: Filter by album type. Defaults to ‘all’. Available values are : all, album, single, compil :type type: str, optional :param offset: The starting position of the results. Defaults to 0. :type offset: int, optional :param limit: The number of results to return. Defaults to 100. :type limit: int, optional :param sort_by: Sort by field. Defaults to ‘title’. Available values are : title, releaseDate :type sort_by: str, optional :param sort_order: Sort order. Defaults to ‘asc’. Other options are ‘desc’. :type sort_order: str, optional

Returns:

A list of albums associated with the artist.

Return type:

list[Album]

Parameters:

uuid (str)
type (str)
offset (int)
limit (int)
sort_by (str)
sort_order (str)

artist_similar_artists(uuid, offset=0, limit=100)[source]¶

Similar artists (“Fans Also Like” profiles) are determined by Spotify algorithms that analyze the listening habits of artists’ fans. For instance, if many fans of artist A frequently listen to artists B and C, then B and C are considered similar artists. Artists cannot edit what appears in “Fans Also Like.” We obtain the list of similar artists from Spotify and rank it alphabetically, which may differ from the ranking on Spotify’s dashboard. :param uuid: The UUID of the artist. :type uuid: str :param offset: The starting position of the results. Defaults to 0. :type offset: int, optional :param limit: The number of results to return. Defaults to 100. :type limit: int, optional

Returns:

Parameters:

uuid (str)
offset (int)
limit (int)

Return type:

list[Artist]

artist_current_stats(uuid, period=7)[source]¶

This API returns all current stats of all platforms, with the growth period of your choice. :param uuid: The UUID of the artist. :type uuid: str :param period: The number of days to calculate the growth. Defaults to 7. :type period: int, optional

Returns:

The current stats for the artist. “Social”, “Popularity”, “Retention”, “Streaming” are main categories.

Return type:

dict

Parameters:

uuid (str)
period (int)

artist_audience(uuid, platform='spotify', start_date=None, end_date=None)[source]¶

Available platforms are listed in the Get platforms for audience data endpoint.

The API response will include the platform’s primary “fan” metric even if it is named differently (e.g., Facebook likes, YouTube subscribers, Deezer fans, Gaana favorites, Line Music Likes). All these are under the “followerCount” metric.

The API response may not return a value for all dates, as we may miss a day or two. These data points may still show on our UI because we estimate the missing data between two points.

Audience refresh frequency depends on the artist’s followers on the platform:

less than 9 followers: every 15 days between 10 and 149 followers: every 7 days between 150 and 499 followers: every 5 days between 500 and 4,999 followers: every 3 days more than 5,000: every 2 days

Parameters:

uuid (str) – The UUID of the artist.
platform (str) – The platform code. Options include but not limited to “instagram”, “spotify”, “soundcloud”, “tiktok”, “triller”, “youtube”, “deezer” etc.
start_date (str) – Optional period start date for the audience data (format ‘YYYY-MM-DD’). Period cannot exceed 90 days
end_date (str) – Optional period end date for the audience data (format ‘YYYY-MM-DD’). Period cannot exceed 90 days

Returns:

A list of audience data for the artist on the specified platform.

Return type:

list[AudienceData]

artist_local_audience(uuid, platform='spotify', start_date=None, end_date=None)[source]¶

Get all values for artist followers for a month and located followers for a given date within that month

Parameters:

uuid (str) – The UUID of the artist.
platform (str) – The platform code.
start_date (str) – The start date for the listening data (format ‘YYYY-MM-DD’).
end_date (str) – The end date for the listening data (format ‘YYYY-MM-DD’).

Return type:

dict

Returns:

artist_listeners_streams_views(uuid, platform, start_date=None, end_date=None)[source]¶

Get the number of listeners, streams, and views for an artist on a specific platform.

Parameters:

uuid (str) – The UUID of the artist.
platform (str) – The platform code.
start_date (str) – The start date for the listening data (format ‘YYYY-MM-DD’).
end_date (str) – The end date for the listening data (format ‘YYYY-MM-DD’).

Returns:

The number of listeners, streams, and views for the artist on the specified platform.

Return type:

dict

artist_spotify_monthly_listeners_latest(uuid)[source]¶

Get the number of monthly listeners for an artist on Spotify. Spotify uses 28 rolling days (4 weeks of 7 days) to measure a month. It makes sense as the number of days in a month varies from 28 to 31, and people’s behavior depends more on the days of the week than on dates within a single month. This way, there is always an equal number of each day within the 28 rolling day ‘monthly listeners’ stats.

Parameters:: uuid (str) – The UUID of the artist.
Returns:: The number of monthly listeners for the artist on Spotify.
Return type:: dict

artist_spotify_monthly_listeners_by_month(uuid, year, month)[source]¶

Get the number of monthly listeners for an artist on Spotify by month. :param uuid: The UUID of the artist. :type uuid: str :param year: Year YYYY format :type year: str :param month: Month MM format :type month: str

Returns:

The number of monthly listeners for the artist on Spotify by month.

Return type:

dict

Parameters:

uuid (str)
year (str)
month (str)

artist_retention(uuid, platform='spotify', start_date=None, end_date=None)[source]¶

Get an artist’s fan retention rate across platforms.

Also called “conversion rate” or “followers to listeners ratio”, this metric shows the relationship between the listeners and the followers. Do take into account that not all followers are listeners. We calculate this by dividing the total number of listeners by the total number of followers, multiplied by 100. The higher the percentage is, the better the artist can turn its listeners into followers.

Available platforms for this endpoint are Spotify, YouTube, Anghami and JioSaavn.

Note that the metrics can be different according to the platform:

Spotify: Followers / Monthly Listeners JioSaavn: Followers / Monthly Listeners YouTube: Subscribers / Views Anghami: Followers / Plays

Parameters:

uuid (str) – The UUID of the artist.
platform (str) – The platform code.
start_date (str) – The start date for the retention data (format ‘YYYY-MM-DD’).
end_date (str) – The end date for the retention data (format ‘YYYY-MM-DD’).

Returns:

The retention data for the artist on the specified platform.

Return type:

dict

artist_popularity(uuid, platform='spotify', start_date=None, end_date=None)[source]¶

Get an artist’s popularity on a platform.

Parameters:

uuid (str) – The UUID of the artist.
platform (str) – The platform code.
start_date (str) – The start date for the popularity data (format ‘YYYY-MM-DD’).
end_date (str) – The end date for the popularity data (format ‘YYYY-MM-DD’).

Returns:

The popularity data for the artist on the specified platform.

Return type:

dict

artist_audience_report_latest(uuid, platform='instagram')[source]¶

Get the latest demographics reports for social/streaming platforms.

Please note that:

Available platforms for this endpoint are instagram, youtube, and tiktok. The artist should have at least 1,000 followers/subscribers on the platform for us to get an audience report. The depth for these platform reports depends on the platform. Instagram is the only platform that returns data for both likes & followers. Audience reports are updated monthly.

Parameters:

uuid (str) – The UUID of the artist.
platform (str) – The platform code.

Returns:

The latest audience report for the artist on the specified platform.

Return type:

dict

artist_audience_report_dates(uuid, platform='instagram', start_date=None, end_date=None, offset=0, limit=100)[source]¶

Get the available dates for demographics reports for social/streaming platforms.

Please note that:

Parameters:

uuid (str) – The UUID of the artist.
platform (str) – The platform code.
start_date (str) – The start date for the audience reports (format ‘YYYY-MM-DD’).
end_date (str) – The end date for the audience reports (format ‘YYYY-MM-DD’).
offset (int) – The starting position of the results.
limit (int) – The number of results to return. Maximum is 100.

Returns:

The available dates for audience reports for the artist on the specified platform.

Return type:

dict

artist_audience_report_by_date(uuid, platform='instagram', date=None)[source]¶

Get the demographics reports for social/streaming platforms by date.

Please note that:

To avoid unnecessary requests, you can first get the dates with available data from the Get available audience report dates endpoint. Available platforms for this endpoint are Instagram, YouTube, and TikTok. Note that the depth for these platform reports depends on the platform. Instagram is the only platform that returns data for both likes & followers.

Parameters:

uuid (str) – The UUID of the artist.
platform (str) – The platform code.
date (str) – The date for the audience reports (format ‘YYYY-MM-DD’).

Returns:

The audience report for the artist on the specified platform by date.

Return type:

dict

artist_short_videos(uuid, platform='instagram')[source]¶

Get an artist’s short videos, and the current audience of each video (comments/likes/views).

This endpoint is available for YouTube shorts and Instagram reels.

Parameters:

uuid (str) – The UUID of the artist.
platform (str) – The platform code. Options include “instagram”, “youtube”.

Return type:

list[ShortVideo]

Returns:

artist_short_video_audience(identifier, start_date=None, end_date=None)[source]¶

Get the audience data for a short video.

This endpoint is available for YouTube shorts and Instagram reels.

Parameters:

identifier (str) – The identifier of the short video.
start_date (str) – The start date for the audience data (format ‘YYYY-MM-DD’).
end_date (str) – The end date for the audience data (format ‘YYYY-MM-DD’).

Return type:

dict

Returns: