API Reference

ListenBrainz client

The ListenBrainz class is the main interface provided by pylistenbrainz. It can be used to interact with the ListenBrainz API.

class pylistenbrainz.client.ListenBrainz

Bases: object

get_listens(username, max_ts=None, min_ts=None, count=None)

Get listens for user username

If none of the optional arguments are given, this function will return the 25 most recent listens. The optional max_ts and min_ts UNIX epoch timestamps control at which point in time to start returning listens. You may specify max_ts or min_ts, but not both in one call.

Parameters

  • username (str) – the username of the user whose data is to be fetched

  • max_ts (int, optional) – If you specify a max_ts timestamp, listens with listened_at less than (but not including) this value will be returned.

  • min_ts (int, optional) – If you specify a min_ts timestamp, listens with listened_at greater than (but not including) this value will be returned.

  • count (int, optional) – the number of listens to return. Defaults to 25, maximum is 100.

Returns

A list of listens for the user username

Return type

List[pylistenbrainz.Listen]

Raises

ListenBrainzAPIException – if the ListenBrainz API returns a non 2xx return code

get_playing_now(username)

Get the listen being played right now for user username.

Parameters

username (str) – the username of the user whose data is to be fetched

Returns

A single listen if the user is playing something currently, else None

Return type

pylistenbrainz.Listen or None

Raises

ListenBrainzAPIException – if the ListenBrainz API returns a non 2xx return code

get_user_artists(username, count=25, offset=0, time_range='all_time')

Get artists for user ‘username’, sorted in descending order of listen count.

Parameters

  • username (str) – the username of the user whose artists are to be fetched.

  • count (int, optional) – the number of artists to fetch, defaults to 25, maximum is 100.

  • offset (int, optional) – the number of artists to skip from the beginning, for pagination, defaults to 0.

  • time_range (str) – the time range, can be ‘all_time’, ‘month’, ‘week’ or ‘year’

Returns

the artists listened to by the user in the time range with listen counts and other data in the same format as the API response

Return type

dict

get_user_listen_count(username)

Get total number of listens for user

Parameters

username (str) – The username of the user whose listens are to be fetched

Returns

Number of listens returned by the Listenbrainz API

Return type

int

get_user_recommendation_recordings(username, artist_type='top', count=25, offset=0)

Get recommended recordings for a user.

Parameters

  • username (str) – the username of the user whose recommended tracks are to be fetched.

  • artist_type (str) – The type of filtering applied to the recommended tracks. ‘top’ for filtering by top artists or ‘similar’ for filtering by similar artists ‘raw’ for no filtering

  • count (int, optional) – the number of recordings to fetch, defaults to 25, maximum is 100.

  • offset (int, optional) – the number of releases to skip from the beginning, for pagination, defaults to 0.

Returns

the recommended recordings as other data returned by the API

Return type

dict

get_user_recordings(username, count=25, offset=0, time_range='all_time')

Get recordings for user ‘username’, sorted in descending order of listen count.

Parameters

  • username (str) – the username of the user whose artists are to be fetched.

  • count (int, optional) – the number of recordings to fetch, defaults to 25, maximum is 100.

  • offset (int, optional) – the number of recordings to skip from the beginning, for pagination, defaults to 0.

  • time_range (str) – the time range, can be ‘all_time’, ‘month’, ‘week’ or ‘year’

Returns

the recordings listened to by the user in the time range with listen counts and other data, in the same format as the API response

Return type

dict

get_user_releases(username, count=25, offset=0, time_range='all_time')

Get releases for user ‘username’, sorted in descending order of listen count.

Parameters

  • username (str) – the username of the user whose releases are to be fetched.

  • count (int, optional) – the number of releases to fetch, defaults to 25, maximum is 100.

  • offset (int, optional) – the number of releases to skip from the beginning, for pagination, defaults to 0.

  • time_range (str) – the time range, can be ‘all_time’, ‘month’, ‘week’ or ‘year’

Returns

the releases listened to by the user in the time range with listen counts and other data

Return type

dict

is_token_valid(token)

Check if the specified ListenBrainz auth token is valid using the /1/validate-token endpoint.

Parameters

token (str) – the auth token that needs to be checked for validity

Raises

ListenBrainzAPIException – if the ListenBrainz API returns a non 2xx return code

set_auth_token(auth_token, check_validity=True)

Give the client an auth_token to use for future requests. This is required if the client wishes to submit listens. Each user has a unique auth token and the auth token is used to identify the user whose data is being submitted.

Parameters

  • auth_token (str) – auth token

  • check_validity (bool, optional) – specify whether we should check the validity of the auth token by making a request to ListenBrainz before setting it (defaults to True)

Raises
submit_multiple_listens(listens)

Submit a list of listens to ListenBrainz.

Requires that the auth token for the user whose listens are being submitted has been set.

Parameters

listens (List[pylistenbrainz.Listen]) – the list of listens to be submitted

Raises
submit_playing_now(listen)

Submit a playing now notification to ListenBrainz.

Requires that the auth token for the user whose data is being submitted has been set.

Parameters

listen (pylistenbrainz.Listen) – the listen to be submitted, the listen should NOT have a listened_at attribute

Raises
submit_single_listen(listen)

Submit a single listen to ListenBrainz.

Requires that the auth token for the user whose data is being submitted has been set.

Parameters

listen (pylistenbrainz.Listen) – the listen to be submitted

Raises

class Listen

The Listen class represents a Listen from ListenBrainz.

class pylistenbrainz.Listen(track_name, artist_name, listened_at=None, release_name=None, recording_mbid=None, artist_mbids=None, release_mbid=None, tags=None, release_group_mbid=None, work_mbids=None, tracknumber=None, spotify_id=None, listening_from=None, isrc=None, additional_info=None, username=None)

Bases: object

__init__(track_name, artist_name, listened_at=None, release_name=None, recording_mbid=None, artist_mbids=None, release_mbid=None, tags=None, release_group_mbid=None, work_mbids=None, tracknumber=None, spotify_id=None, listening_from=None, isrc=None, additional_info=None, username=None)

Creates a Listen.

Needs at least a track name and an artist name.

Parameters

  • track_name (str) – the name of the track

  • artist_name (str) – the name of the artist

  • listened_at (int, optional) – the unix timestamp at which the user listened to this listen

  • release_name (str, optional) – the name of the MusicBrainz release the track is a part of

  • recording_mbid (str, optional) – the MusicBrainz ID of this listen’s recording

  • artist_mbids (List[str], optional) – the MusicBrainz IDs of this listen’s artists

  • release_mbid (str, optional) – the MusicBrainz ID of this listen’s release

  • tags (List[str], optional) – a list of user defined tags for this recording, each listen can only have at most 50 tags and each tag must be shorter than 64 characters.

  • release_group_mbid (str, optional) – A MusicBrainz Release Group ID of the release group this recording was played from.

  • work_mbids (List[str], optional) – A list of MusicBrainz Work IDs that may be associated with this recording.

  • tracknumber (int, optional) – The tracknumber of the recording. This first recording on a release is tracknumber 1.

  • spotify_id (str, optional) – The Spotify track URL associated with this recording. e.g.: http://open.spotify.com/track/1rrgWMXGCGHru5bIRxGFV0

  • listening_from (str, optional) – the source of the listen, for example: ‘spotify’ or ‘vlc’,

  • isrc (str, optional) – The ISRC code associated with the recording.

  • additional_info (dict, optional) – a dict containing any additional fields that should be submitted with the listen.

  • username (str, optional) – the username of the user to whom this listen belongs

Returns

A listen object with the passed properties

Return type

Listen

Statistics (beta)

ListenBrainz has started exposing statistics endpoints. The following classes are related to those endpoints.