TracksAPI

class minim.api.spotify.TracksAPI(client: APIClient, /)[source]

Bases: SpotifyResourceAPI

Tracks API endpoints for the Spotify Web API.

Important

This class is managed by SpotifyWebAPIClient and should not be instantiated directly.

Parameters:
clientminim.api._shared.APIClient

API client instance used to make HTTP requests.

Methods

are_tracks_saved

Tracks > Check User's Saved Tracks: Check whether one or more tracks are saved in the current user's library.

get_my_saved_tracks

Tracks > Get User's Saved Tracks: Get Spotify catalog information for tracks saved in the current user's library.

get_my_top_tracks

Users > Get Current User's Top Tracks: Get Spotify catalog information for the current user's top tracks.

get_track_audio_analysis

Tracks > Get Track's Audio Analysis: Get a low-level audio analysis (track structure and musical content, including rhythm, pitch, and timbre) of a track.

get_track_audio_features

Tracks > Get Track's Audio Features: Get the audio features for a track․ Tracks > Get Several Tracks' Audio Features: Get the audio features for multiple tracks.

get_track_recommendations

Tracks > Get Recommendations: Get track recommendations based on seed artists, genres, and/or tracks, with optional tuning parameters.

get_tracks

Tracks > Get Track: Get Spotify catalog information for a track․ Tracks > Get Several Tracks: Get Spotify catalog information for multiple tracks.

remove_saved_tracks

Tracks > Remove User's Saved Tracks: Remove one or more tracks from the current user's library.

save_tracks

Tracks > Save Tracks for Current User: Save one or more tracks to the current user's library.

are_tracks_saved(track_ids: str | Collection[str], /) list[bool][source]

Tracks > Check User’s Saved Tracks: Check whether one or more tracks are saved in the current user’s library.

Authorization scope

user-library-read scope

Access your saved content. Learn more.

Parameters:
track_idsstr or Collection[str]; positional-only

Spotify IDs of the tracks. A maximum of 50 IDs can be sent in a request.

Examples:

  • "7ouMYWpwJ422jRcDASZB7P"

  • "7ouMYWpwJ422jRcDASZB7P,4VqPOruhp5EdPBeR92t6lQ"

  • ["7ouMYWpwJ422jRcDASZB7P", "4VqPOruhp5EdPBeR92t6lQ"]

Returns:
savedlist[bool]

Whether the current user has the specified tracks saved in their library.

get_my_saved_tracks(*, country_code: str | None = None, limit: int | None = None, offset: int | None = None) dict[str, Any][source]

Tracks > Get User’s Saved Tracks: Get Spotify catalog information for tracks saved in the current user’s library.

Authorization scope and third-party application mode

user-library-read scope

Access your saved content. Learn more.

Extended quota mode before November 27, 2024

Access 30-second preview URLs. Learn more.

Parameters:
country_codestr; keyword-only; optional

ISO 3166-1 alpha-2 country code. If provided, only content available in that market is returned. When a user access token accompanies the request, the country associated with the user account takes priority over this parameter.

Note

If neither a country code is provided nor a country can be determined from the user account, the content is considered unavailable for the client.

Example: "ES".

limitint; keyword-only; optional

Maximum number of tracks to return.

Valid range: 1 to 50.

API default: 20.

offsetint; keyword-only; optional

Index of the first track to return. Use with limit to get the next batch of tracks.

Minimum value: 0.

API default: 0.

Returns:
tracksdict[str, Any]

Page of Spotify metadata for the user’s saved tracks.

get_my_top_tracks(*, time_range: str | None = None, limit: int | None = None, offset: int | None = None) dict[str, Any][source]

Users > Get Current User’s Top Tracks: Get Spotify catalog information for the current user’s top tracks.

Authorization scope and third-party application mode

user-top-read scope

Read your top artists and contents. Learn more.

Extended quota mode before November 27, 2024

Access 30-second preview URLs. Learn more.

Parameters:
time_rangestr; keyword-only; optional

Time frame over which the current user’s listening history is analyzed to determine top tracks.

Valid values:

  • "long_term" – Approximately one year of data, including all new data as it becomes available.

  • "medium_term" – Approximately the last six months of data.

  • "short_term" – Approximately the last four weeks of data.

API default: "medium_term".

limitint; keyword-only; optional

Maximum number of tracks to return.

Valid range: 1 to 50.

API default: 20.

offsetint; keyword-only; optional

Index of the first track to return. Use with limit to get the next batch of tracks.

Minimum value: 0.

API default: 0.

Returns:
itemsdict[str, Any]

Page of Spotify metadata for the current user’s top tracks.

get_track_audio_analysis(track_id: str, /) dict[str, Any][source]

Tracks > Get Track’s Audio Analysis: Get a low-level audio analysis (track structure and musical content, including rhythm, pitch, and timbre) of a track.

Third-party application mode

Extended quota mode before November 27, 2024

Access the GET/audio-analysis/{track_id} endpoint. Learn more.

Parameters:
track_idstr; positional-only

Spotify ID of the track.

Example: "11dFghVXANMlKmJXsNCbNl".

Returns:
audio_analysisdict[str, Any]

Audio analysis of the track.

get_track_audio_features(track_ids: str | Collection[str], /) dict[str, Any][source]

Tracks > Get Track’s Audio Features: Get the audio features for a track․ Tracks > Get Several Tracks’ Audio Features: Get the audio features for multiple tracks.

Third-party application mode

Extended quota mode before November 27, 2024

Access the GET /audio-features/{id} endpoint. Learn more.

Parameters:
track_idsstr or Collection[str]; positional-only

Spotify IDs of the tracks. A maximum of 50 IDs can be sent in a request.

Examples:

  • "7ouMYWpwJ422jRcDASZB7P"

  • "7ouMYWpwJ422jRcDASZB7P,4VqPOruhp5EdPBeR92t6lQ"

  • ["7ouMYWpwJ422jRcDASZB7P", "4VqPOruhp5EdPBeR92t6lQ"]

Returns:
audio_featuresdict[str, Any]

Audio features for the tracks.

get_track_recommendations(seed_artist_ids: str | Collection[str] | None = None, seed_genres: str | Collection[str] | None = None, seed_track_ids: str | Collection[str] | None = None, *, country_code: str | None = None, limit: int | None = None, acousticness: FloatAttributeSpec | None = None, danceability: FloatAttributeSpec | None = None, duration_ms: IntAttributeSpec | None = None, energy: FloatAttributeSpec | None = None, instrumentalness: FloatAttributeSpec | None = None, key: IntAttributeSpec | None = None, liveness: FloatAttributeSpec | None = None, loudness: FloatAttributeSpec | None = None, mode: IntAttributeSpec | None = None, popularity: IntAttributeSpec | None = None, speechiness: FloatAttributeSpec | None = None, tempo: FloatAttributeSpec | None = None, time_signature: IntAttributeSpec | None = None, valence: FloatAttributeSpec | None = None) dict[str, Any][source]

Tracks > Get Recommendations: Get track recommendations based on seed artists, genres, and/or tracks, with optional tuning parameters.

Third-party application mode

Extended quota mode before November 27, 2024

Access the GET/recommendations endpoint. Learn more.

Note

For very new or obscure artists and tracks, there might not be enough data to generate recommendations.

Important

At least one and up to five seed values may be provided in any combination of seed_artist_ids, seed_genres, and seed_track_ids.

Hint

Track attribute parameters (acousticness, danceability, duration_ms, etc.) can be provided in one of the following ways:

Track attribute specifications

Data type

Specification

Number

Target value

tuple[Number, Number]

Minimum and maximum values

tuple[Number, Number, Number]

Minimum, maximum, and target values

Parameters:
seed_artist_idsstr or Collection[str]; optional

Spotify IDs of seed artists.

Examples:

  • "0TnOYISbd1XYRBk9myaseg"

  • "0TnOYISbd1XYRBk9myaseg,57dN52uHvrHOxijzpIgu3E"

  • ["0TnOYISbd1XYRBk9myaseg", "57dN52uHvrHOxijzpIgu3E"]

seed_genresstr or Collection[str]; optional

Spotify IDs of seed genres.

See also

get_seed_genres() – Get available seed genres.

seed_track_idsstr or Collection[str]; optional

Spotify IDs of seed tracks.

Examples:

  • "7ouMYWpwJ422jRcDASZB7P"

  • "7ouMYWpwJ422jRcDASZB7P,4VqPOruhp5EdPBeR92t6lQ"

  • ["7ouMYWpwJ422jRcDASZB7P", "4VqPOruhp5EdPBeR92t6lQ"]

country_codestr; keyword-only; optional

ISO 3166-1 alpha-2 country code. If provided, only content available in that market is returned. When a user access token accompanies the request, the country associated with the user account takes priority over this parameter.

Note

If neither a country code is provided nor a country can be determined from the user account, the content is considered unavailable for the client.

Example: "ES".

limitint; keyword-only; optional

Maximum number of tracks to return.

Valid range: 1 to 50.

API default: 20.

acousticnessfloat or tuple[float, …]; keyword-only; optional

Confidence measure of whether a track is acoustic.

Valid range: 0.0 (electronic) to 1.0 (acoustic).

Example: 0.00242.

danceabilityfloat or tuple[float, …]; keyword-only; optional

Suitability of a track for dancing based on a combination of musical elements, including tempo, rhythim stability, beat strength, and overall regularity.

Valid range: 0.0 (least danceable) to 1.0 (most danceable).

Example: 0.585.

duration_msint or tuple[int, …]; keyword-only; optional

Track duration in milliseconds.

Minimum value: 0.

Example: 237_040.

energyfloat or tuple[float, …]; keyword-only; optional

Perceptual measure of a track’s intensity and activity based on its dynamic range, perceived loudness, timbre, onset rate, and general entropy.

Valid range: 0.0 (e.g., Bach prelude) to 1.0 (e.g., death metal).

Example: 0.842.

instrumentalnessfloat or tuple[float, …]; keyword-only; optional

Confidence measure of whether a track contains no vocals.

Valid range: 0.0 (vocal) to 1.0 (instrumental).

Example: 0.00686.

keyint or tuple[int, …]; keyword-only; optional

Key a track is in using standard pitch class notation.

Valid values:

  • -1 – No key detected.

  • 0 – C.

  • 1 – C♯ or D♭.

  • 2 – D

  • 3 – D♯ or E♭.

  • 4 – E.

  • 5 – F.

  • 6 – F♯ or G♭.

  • 7 – G.

  • 8 – G♯ or A♭.

  • 9 – A.

  • 10 – A♯ or B♭.

  • 11 – B.

livenessfloat or tuple[float, …]; keyword-only; optional

Confidence measure of whether a track was performed live based on the presence of an audience in the recording.

Valid range: 0.0 (studio) to 1.0 (live).

Example: 0.0866.

loudnessfloat or tuple[float, …]; keyword-only; optional

Overall loudness of a track in decibels.

Maximum value: 0.0.

Example: -5.883.

modeint or tuple[int, …]; keyword-only; optional

Musical mode of a track.

Valid values: 0 for minor scale, 1 for major scale.

popularityint or tuple[int, …]; keyword-only; optional

Popularity of a track based on the total number of plays it has had and how recent those plays are.

Note

The popularity value is not updated in real time and may lag actual value by a few days.

Valid range: 0 (least popular) to 100 (most popular).

speechinessfloat or tuple[float, …]; keyword-only; optional

Confidence measure of whether a track contains spoken words.

Valid range: 0.0 (music) to 1.0 (speech-like).

Example: 0.0556.

tempofloat or tuple[float, …]; keyword-only; optional

Overall estimated tempo of a track in beats per minute.

Minimum value: 0.0.

Example: 118.211.

time_signatureint or tuple[int, …]; keyword-only; optional

Estimated time signature of the track.

Valid values:

  • 3 – 3/4.

  • 4 – 4/4.

  • 5 – 5/4.

  • 6 – 6/4.

  • 7 – 7/4.

valencefloat or tuple[float, …]; keyword-only; optional

Confidence measure of the musical positiveness conveyed by a track.

Valid range: 0.0 (e.g., happy, cheerful, euphoric) to 1.0 (e.g., sad, depressed, angry).

Example: 0.428.

Returns:
recommendationsdict[str, Any]

Spotify metadata for the tracks recommended based on the provided seeds and tuning parameters.

get_tracks(track_ids: str | Collection[str], /, *, country_code: str | None = None) dict[str, Any][source]

Tracks > Get Track: Get Spotify catalog information for a track․ Tracks > Get Several Tracks: Get Spotify catalog information for multiple tracks.

Parameters:
track_idsstr or Collection[str]; positional-only

Spotify IDs of the tracks. A maximum of 50 IDs can be sent in a request.

Examples:

  • "7ouMYWpwJ422jRcDASZB7P"

  • "7ouMYWpwJ422jRcDASZB7P,4VqPOruhp5EdPBeR92t6lQ"

  • ["7ouMYWpwJ422jRcDASZB7P", "4VqPOruhp5EdPBeR92t6lQ"]

country_codestr; keyword-only; optional

ISO 3166-1 alpha-2 country code. If provided, only content available in that market is returned. When a user access token accompanies the request, the country associated with the user account takes priority over this parameter.

Note

If neither a country code is provided nor a country can be determined from the user account, the content is considered unavailable for the client.

Example: "ES".

Returns:
tracksdict[str, Any]

Spotify metadata for the tracks.

remove_saved_tracks(track_ids: str | Collection[str], /) None[source]

Tracks > Remove User’s Saved Tracks: Remove one or more tracks from the current user’s library.

Authorization scope

user-library-modify scope

Manage your saved content. Learn more.

Parameters:
track_idsstr or Collection[str]; positional-only

Spotify IDs of the tracks. A maximum of 50 IDs can be sent in a request.

Examples:

  • "7ouMYWpwJ422jRcDASZB7P"

  • "7ouMYWpwJ422jRcDASZB7P,4VqPOruhp5EdPBeR92t6lQ"

  • ["7ouMYWpwJ422jRcDASZB7P", "4VqPOruhp5EdPBeR92t6lQ"]

save_tracks(track_ids: str | tuple[str, str | datetime] | dict[str, str | datetime] | list[str | tuple[str, str | datetime] | dict[str, str | datetime]], /) None[source]

Tracks > Save Tracks for Current User: Save one or more tracks to the current user’s library.

Authorization scope

user-library-modify scope

Manage your saved content. Learn more.

Parameters:
track_idsstr, tuple[str, str | datetime], dict[str, str | datetime], or list[str | tuple[str, str | datetime] | dict[str, str | datetime]]; positional-only

Spotify IDs of the tracks, optionally accompanied by timestamps to maintain a chronological order in the user’s library. A maximum of 50 IDs can be sent in one request.

Examples:

  • "4iV5W9uYEdYUVa79Axb7Rh"

  • ("4iV5W9uYEdYUVa79Axb7Rh", "2010-01-01T00:00:00Z")

  • {"id": "4iV5W9uYEdYUVa79Axb7Rh", "added_at": "2010-01-01T00:00:00Z"}

  • [
        "4iV5W9uYEdYUVa79Axb7Rh",
        ("11dFghVXANMlKmJXsNCbNl", "2017-05-26T00:00:00Z"),
        {
            "id": "7ouMYWpwJ422jRcDASZB7P",
            "added_at": "2006-06-28T00:00:00Z"
        }
    ]