Skip to content

Albums

API #

Implementation to make API calls with.

Parameters:

get_album #

get_album(album_id: str, *, market: MissingOr[str] = MISSING) -> Album

Get Spotify catalog information for a single album.

Parameters:

Returns:

  • Album –

    The requested album.

get_several_albums #

get_several_albums(album_ids: list[str], *, market: MissingOr[str] = MISSING) -> list[Album]

Get Spotify catalog information for several albums.

Parameters:

Returns:

get_album_tracks #

get_album_tracks(album_id: str, *, limit: MissingOr[int] = MISSING, offset: MissingOr[int] = MISSING, market: MissingOr[str] = MISSING) -> Paginator[SimpleTrack]

Get Spotify catalog information about an album's tracks.

Parameters:

  • album_id (str) –

    The ID of the album.

  • 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).

  • market (str, default: MISSING ) –

    Only get content available in that market. Must be an ISO 3166-1 alpha-2 country code.

Returns:

get_users_saved_albums #

get_users_saved_albums(*, limit: MissingOr[int] = MISSING, offset: MissingOr[int] = MISSING, market: MissingOr[str] = MISSING) -> Paginator[SavedAlbum]

Get a list of the albums saved in the current user's 'Your Music' library.

Required Authorization Scope

USER_LIBRARY_READ

Parameters:

  • 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).

  • market (str, default: MISSING ) –

    Only get content available in that market. Must be an ISO 3166-1 alpha-2 country code.

Returns:

save_albums_for_current_user #

save_albums_for_current_user(album_ids: list[str]) -> None

Save one or more albums to the current user's 'Your Music' library.

Required Authorization Scope

USER_LIBRARY_MODIFY

Parameters:

  • album_ids (list[str]) –

    The IDs of the albums. Maximum: 50.

remove_users_saved_albums #

remove_users_saved_albums(album_ids: list[str]) -> None

Remove one or more albums from the current user's 'Your Music' library.

Required Authorization Scope

USER_LIBRARY_MODIFY

Parameters:

  • album_ids (list[str]) –

    The IDs of the albums. Maximum: 50.

check_users_saved_albums #

check_users_saved_albums(album_ids: list[str]) -> list[bool]

Check if one or more albums is already saved in the current user's 'Your Music' library.

Required Authorization Scope

USER_LIBRARY_READ

Parameters:

  • album_ids (list[str]) –

    The IDs of the albums. Maximum: 20.

Returns:

  • list[bool] –

    A list of booleans dictating whether or not the corresponding albums are saved.

get_new_releases #

get_new_releases(*, limit: MissingOr[int] = MISSING, offset: MissingOr[int] = MISSING) -> Paginator[SimpleAlbum]

Get a list of new album releases featured in Spotify (shown, for example, on a Spotify player's 'Browse' tab).

Parameters:

  • 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).

Returns:

SimpleAlbum #

A simplified album.

album_type #

album_type: AlbumType

The type of the album.

total_tracks #

total_tracks: int

The number of tracks in the album.

available_markets #

available_markets: list[str] | None = None

The markets in which the album is available (ISO 3166-1 alpha-2 country codes).

Note

An album is considered available in a market when at least 1 of its tracks is available in that market.

external_urls #

external_urls: ExternalURLs

Known external URLs for the album.

href #

href: str

A link to the Web API endpoint providing full details of the album.

id #

id: str

The Spotify ID for the album.

images #

images: list[Image]

The cover art for the album in various sizes, widest first.

name #

name: str

The name of the album.

Note

In case of an album takedown, the value may be an empty string.

release_date #

release_date: date

The date the album was first released.

release_date_precision #

release_date_precision: ReleaseDatePrecision

The precision with which release_date is known.

restrictions #

restrictions: Restrictions | None = None

Restrictions applied to the album. Included when a content restriction is applied.

uri #

uri: str

The Spotify URI for the album.

artists #

artists: list[SimpleArtist]

The artists of the album.

Album #

An album.

album_type #

album_type: AlbumType

The type of the album.

total_tracks #

total_tracks: int

The number of tracks in the album.

available_markets #

available_markets: list[str] | None = None

The markets in which the album is available (ISO 3166-1 alpha-2 country codes).

Note

An album is considered available in a market when at least 1 of its tracks is available in that market.

external_urls #

external_urls: ExternalURLs

Known external URLs for the album.

href #

href: str

A link to the Web API endpoint providing full details of the album.

id #

id: str

The Spotify ID for the album.

images #

images: list[Image]

The cover art for the album in various sizes, widest first.

name #

name: str

The name of the album.

Note

In case of an album takedown, the value may be an empty string.

release_date #

release_date: date

The date the album was first released.

release_date_precision #

release_date_precision: ReleaseDatePrecision

The precision with which release_date is known.

restrictions #

restrictions: Restrictions | None = None

Restrictions applied to the album. Included when a content restriction is applied.

uri #

uri: str

The Spotify URI for the album.

artists #

artists: list[SimpleArtist]

The artists of the album.

tracks #

tracks: Paginator[SimpleTrack]

The tracks of the album.

copyrights #

copyrights: list[Copyright]

The copyright statements of the album.

external_ids #

external_ids: ExternalIDs

Known external IDs for the album.

genres #

genres: list[str]

The genres the album is associated with. If not yet classified, this list is empty.

label #

label: str

The label associated with the album.

popularity #

popularity: int

The popularity of the album. The value will be between 0 and 100, with 100 being the most popular.

ArtistAlbum #

An artist's album.

album_type #

album_type: AlbumType

The type of the album.

total_tracks #

total_tracks: int

The number of tracks in the album.

available_markets #

available_markets: list[str] | None = None

The markets in which the album is available (ISO 3166-1 alpha-2 country codes).

Note

An album is considered available in a market when at least 1 of its tracks is available in that market.

external_urls #

external_urls: ExternalURLs

Known external URLs for the album.

href #

href: str

A link to the Web API endpoint providing full details of the album.

id #

id: str

The Spotify ID for the album.

images #

images: list[Image]

The cover art for the album in various sizes, widest first.

name #

name: str

The name of the album.

Note

In case of an album takedown, the value may be an empty string.

release_date #

release_date: date

The date the album was first released.

release_date_precision #

release_date_precision: ReleaseDatePrecision

The precision with which release_date is known.

restrictions #

restrictions: Restrictions | None = None

Restrictions applied to the album. Included when a content restriction is applied.

uri #

uri: str

The Spotify URI for the album.

artists #

artists: list[SimpleArtist]

The artists of the album.

album_group #

album_group: AlbumGroup

Represents the relationship between the artist and the album.

SavedAlbum #

Information about an album saved to a user's 'Your Music' library.

added_at #

added_at: datetime

The date and time the album was saved.

album #

album: Album

The album.