Users

API #

Implementation to make API calls with.

Parameters:

access_flow (AuthorizationCodeFlow | ClientCredentialsFlow) –

Access flow to use for api requests.

get_current_users_profile #

get_current_users_profile() -> OwnUser

Get detailed profile information about the current user.

Optional Authorization Scopes

USER_READ_PRIVATE - required to access the current user's subscription details.
USER_READ_EMAIL - required to access the current user's email.

Returns:

OwnUser –

The current user.

get_users_top_items #

get_users_top_items(type: TopItemType, *, limit: MissingOr[int] = MISSING, offset: MissingOr[int] = MISSING, time_range: MissingOr[TimeRange] = MISSING) -> Paginator[Artist] | Paginator[TrackWithSimpleArtist]

Get the current user's top artists or tracks based on calculated affinity.

Required Authorization Scope

USER_TOP_READ

Parameters:

type (TopItemType) –

The type of entity to return.
limit (int, default: 20 ) –

The maximum number of items to return. Default: 20. Minimum: 1. Maximum: 50.
offset (int, default: 0 ) –

The index of the first item to return. Default: 0 (the first item)
time_range (TimeRange, default: Medium Term ) –

Over what time frame the affinities are computed.

Returns:

Paginator[Artist] –

A paginator who's items are a list of artists.
Paginator[TrackWithSimpleArtist] –

A paginator who's items are a list of tracks.

get_users_profile #

get_users_profile(user_id: str) -> User

Get public profile information about a Spotify user.

Parameters:

user_id (str) –

The ID of the user.

Returns:

User –

The requested user.

follow_playlist #

follow_playlist(playlist_id: str, public: MissingOr[bool] = MISSING) -> None

Add the current user as a follower of a playlist.

Optional Authorization Scopes

PLAYLIST_MODIFY_PUBLIC - required to add the playlist to the current user's public playlists. PLAYLIST_MODIFY_PRIVATE - required to add the playlist to the current user's private playlists.

Parameters:

playlist_id (str) –

The ID of the playlist.
public (bool, default: True ) –

Whether or not the playlist will be included in the user's public playlists (added to profile).

unfollow_playlist #

unfollow_playlist(playlist_id: str) -> None

Remove the current user as a follower of a playlist.

Optional Authorization Scopes

PLAYLIST_MODIFY_PUBLIC - required to remove the playlist from the current user's public playlists.
PLAYLIST_MODIFY_PRIVATE - required to remove the playlist from the current user's private playlists.

Parameters:

playlist_id (str) –

The ID of the playlist.

get_followed_artists #

get_followed_artists(after: MissingOr[str] = MISSING, limit: MissingOr[int] = MISSING) -> CursorPaginator[Artist]

Get the current user's followed artists.

Required Authorization Scope

USER_FOLLOW_READ

Parameters:

after (str, default: MISSING ) –

The last artist ID retrieved from the previous request.
limit (int, default: 20 ) –

The maximum number of items to return. Default: 20. Minimum: 1. Maximum: 50.

Returns:

CursorPaginator[Artist] –

A paginator who's items are a list of artists.

follow_artists_or_users #

follow_artists_or_users(ids: list[str], type: UserType) -> None

Add the current user as a follower of one or more artists or other Spotify users.

Required Authorization Scope

USER_FOLLOW_MODIFY

Parameters:

ids (list[str]) –

The IDs of the artists. Maximum: 50.
type (UserType) –

The user type (user/artist).

unfollow_artists_or_users #

unfollow_artists_or_users(ids: list[str], type: UserType) -> None

Remove the current user as a follower of one or more artists or other Spotify users.

Required Authorization Scope

USER_FOLLOW_MODIFY

Parameters:

ids (list[str]) –

The IDs of the artists. Maximum: 50.
type (UserType) –

The user type (user/artist).

check_if_user_follows_artists_or_users #

check_if_user_follows_artists_or_users(ids: list[str], type: UserType) -> list[bool]

Check to see if the current user is following one or more artists or other Spotify users.

Required Authorization Scope

USER_FOLLOW_READ

Parameters:

ids (list[str]) –

The IDs of the artists. Maximum: 50.
type (UserType) –

The user type (user/artist).

Returns:

list[bool] –

A list of booleans dictating whether or not the current user has followed the corresponding users or artists.

check_if_current_user_follows_playlist #

check_if_current_user_follows_playlist(playlist_id: str) -> bool

Check to see if the current user is following a specified playlist.

Required Authorization Scope

PLAYLIST_READ_PRIVATE

Parameters:

playlist_id (str) –

The ID of the playlist.

Returns:

bool –

Whether or not the current user is following the playlist.

SimpleUser #

A simplified user.

external_urls #

external_urls: ExternalURLs

Known external URLs for the user.

followers #

followers: Followers | None = None

Information about the followers of the user.

href #

href: str

A link to the Web API endpoint for the user.

id #

id: str

The Spotify user ID for the user.

uri #

uri: str

The Spotify URI for the user.

User #

A user.

external_urls #

external_urls: ExternalURLs

Known external URLs for the user.

followers #

followers: Followers | None = None

Information about the followers of the user.

href #

href: str

A link to the Web API endpoint for the user.

id #

id: str

The Spotify user ID for the user.

uri #

uri: str

The Spotify URI for the user.

display_name #

display_name: str | None

The name displayed on the user's profile. None if not available.

OwnUser #

A user with additional information.

external_urls #

external_urls: ExternalURLs

Known external URLs for the user.

followers #

followers: Followers | None = None

Information about the followers of the user.

href #

href: str

A link to the Web API endpoint for the user.

id #

id: str

The Spotify user ID for the user.

uri #

uri: str

The Spotify URI for the user.

display_name #

display_name: str | None

The name displayed on the user's profile. None if not available.

country #

country: str | None = None

The country of the user, as set in the user's account profile. An ISO 3166-1 alpha-2 country code. This field is only available when the current user has granted access to the USER_READ_PRIVATE scope.

email #

email: str | None = None

The user's email address, as entered by the user when creating their account. This field is only available when the current user has granted access to the USER_READ_EMAIL scope.

Warning

This email address is unverified; there is no proof that it actually belongs to the user.

explicit_content #

explicit_content: ExplicitContent | None = None

The user's explicit content settings. This field is only available when the current user has granted access to the USER_READ_PRIVATE scope.

images #

images: list[Image]

The user's profile image.

product #

product: SubscriptionLevel | None = None

The user's Spotify subscription level. This field is only available when the current user has granted access to the USER_READ_PRIVATE scope.

ExplicitContent #

Explicit content settings.

filter_enabled #

filter_enabled: bool

When True, indicates that explicit content should not be played.

filter_locked #

filter_locked: bool

When True, indicates that the explicit content setting is locked and can't be changed by the user.