TracksAPI¶
- class minim.api.spotify.TracksAPI(client: APIClient, /)[source]¶
Bases:
SpotifyResourceAPITracks API endpoints for the Spotify Web API.
Important
This class is managed by
SpotifyWebAPIClientand should not be instantiated directly.- Parameters:
- clientminim.api._shared.APIClient
API client instance used to make HTTP requests.
Methods
Tracks > Check User's Saved Tracks: Check whether one or more tracks are saved in the current user's library.
Tracks > Get User's Saved Tracks: Get Spotify catalog information for tracks saved in the current user's library.
Users > Get Current User's Top Tracks: Get Spotify catalog information for the current user's top tracks.
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.
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.
Tracks > Get Recommendations: Get track recommendations based on seed artists, genres, and/or tracks, with optional tuning parameters.
Tracks > Get Track: Get Spotify catalog information for a track․ Tracks > Get Several Tracks: Get Spotify catalog information for multiple tracks.
Tracks > Remove User's Saved Tracks: Remove one or more tracks from the current user's library.
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-readscopeAccess 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-readscopeAccess 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:
1to50.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.
Sample response
{ "href": <str>, "items": [ { "added_at": <str>, "track": { "album": { "album_type": <str>, "artists": [ { "external_urls": { "spotify": <str> }, "href": <str>, "id": <str>, "name": <str>, "type": "artist", "uri": <str> } ], "available_markets": <list[str]>, "external_urls": { "spotify": <str> }, "href": <str>, "id": <str>, "images": [ { "height": <int>, "url": <str>, "width": <int> } ], "name": <str>, "release_date": <str>, "release_date_precision": <str>, "restrictions": { "reason": <str> }, "total_tracks": <int>, "type": "album", "uri": <str> }, "artists": [ { "external_urls": { "spotify": <str> }, "href": <str>, "id": <str>, "name": <str>, "type": "artist", "uri": <str> } ], "available_markets": <list[str]>, "disc_number": <int>, "duration_ms": <int>, "explicit": <bool>, "external_ids": { "ean": <str>, "isrc": <str>, "upc": <str> }, "external_urls": { "spotify": <str> }, "href": <str>, "id": <str>, "is_local": <bool>, "is_playable": <bool>, "linked_from": <dict[str, Any]>, "name": <str>, "popularity": <int>, "preview_url": <str>, "restrictions": { "reason": <str> }, "track_number": <int>, "type": "track", "uri": <str> } } ], "limit": <int>, "next": <str>, "offset": <int>, "previous": <str>, "total": <int> }
- 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-readscopeRead 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:
1to50.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.
Sample response
{ "href": <str>, "items": [ { "album": { "album_type": <str>, "artists": [ { "external_urls": { "spotify": <str> }, "href": <str>, "id": <str>, "name": <str>, "type": "artist", "uri": <str> } ], "available_markets": <list[str]>, "external_urls": { "spotify": <str> }, "href": <str>, "id": <str>, "images": [ { "height": <int>, "url": <str>, "width": <int> } ], "is_playable": <bool>, "name": <str>, "release_date": <str>, "release_date_precision": <str>, "total_tracks": <int>, "type": "album", "uri": <str> }, "artists": [ { "external_urls": { "spotify": <str> }, "href": <str>, "id": <str>, "name": <str>, "type": "artist", "uri": <str></str> } ], "available_markets": <list[str]>, "disc_number": <int>, "duration_ms": <int>, "explicit": <bool>, "external_ids": { "isrc": <str> }, "external_urls": { "spotify": <str> }, "href": <str>, "id": <str>, "is_local": <bool>, "is_playable": <bool>, "name": <str>, "popularity": <int>, "preview_url": <str>, "track_number": <int>, "type": "track", "uri": <str> } ], "limit": <int>, "next": <str>, "offset": <int>, "previous": <str>, "total": <int> }
- 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.
Sample response
{ "bars": [ { "confidence": <float>, "duration": <float>, "start": <float> } ], "beats": [ { "confidence": <float>, "duration": <float>, "start": <float> } ], "meta": { "analysis_time": <float>, "analyzer_version": <str>, "detailed_status": <str>, "input_process": <str>, "platform": <str>, "status_code": <int>, "timestamp": <int> }, "sections": [ { "confidence": <float>, "duration": <float>, "key": <int>, "key_confidence": <float>, "loudness": <float>, "mode": <int>, "mode_confidence": <float>, "start": <float>, "tempo": <float>, "tempo_confidence": <float>, "time_signature": <int>, "time_signature_confidence": <float> } ], "segments": [ { "confidence": <float>, "duration": <float>, "loudness_end": <float>, "loudness_max": <float>, "loudness_max_time": <float>, "loudness_start": <float>, "pitches": <list[float]>, "start": <float>, "timbre": <list[float]> } ], "tatums": [ { "confidence": <float>, "duration": <float>, "start": <float> } ], "track": { "analysis_channels": <int>, "analysis_sample_rate": <int>, "code_version": <float>, "codestring": <str>, "duration": <float>, "echoprint_version": <float>, "echoprintstring": <str>, "end_of_fade_in": <float>, "key": <int>, "key_confidence": <float>, "loudness": <float>, "mode": <int>, "mode_confidence": <float>, "num_samples": <int>, "offset_seconds": <float>, "rhythm_version": <int>, "rhythmstring": <str>, "sample_md5": <str>, "start_of_fade_out": <float>, "synch_version": <int>, "synchstring": <str>, "tempo": <float>, "tempo_confidence": <float>, "time_signature": <int>, "time_signature_confidence": <float>, "window_seconds": <float> } }
- 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.
Sample responses
{ "acousticness": <float>, "analysis_url": <str>, "danceability": <float>, "duration_ms": <int>, "energy": <float>, "id": <str>, "instrumentalness": <float>, "key": <int>, "liveness": <float>, "loudness": <float>, "mode": <int>, "speechiness": <float>, "tempo": <float>, "time_signature": <int>, "track_href": <str>, "type": "audio_features", "uri": <str>, "valence": <float> }
{ "audio_features": [ { "acousticness": <float>, "analysis_url": <str>, "danceability": <float>, "duration_ms": <int>, "energy": <float>, "id": <str>, "instrumentalness": <float>, "key": <int>, "liveness": <float>, "loudness": <float>, "mode": <int>, "speechiness": <float>, "tempo": <float>, "time_signature": <int>, "track_href": <str>, "type": "audio_features", "uri": <str>, "valence": <float> } ] }
- 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/recommendationsendpoint. 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, andseed_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:
1to50.API default:
20.- acousticnessfloat or tuple[float, …]; keyword-only; optional
Confidence measure of whether a track is acoustic.
Valid range:
0.0(electronic) to1.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) to1.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) to1.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) to1.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– D3– 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) to1.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:
0for minor scale,1for 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) to100(most popular).- speechinessfloat or tuple[float, …]; keyword-only; optional
Confidence measure of whether a track contains spoken words.
Valid range:
0.0(music) to1.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) to1.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.
Sample response
{ "seeds": [ { "afterFilteringSize": <int>, "afterRelinkingSize": <int>, "href": <str>, "id": <str>, "initialPoolSize": <int>, "type": <str> } ], "tracks": [ { "album": { "album_type": <str>, "artists": [ { "external_urls": { "spotify": <str> }, "href": <str>, "id": <str>, "name": <str>, "type": "artist", "uri": <str> } ], "available_markets": <list[str]>, "external_urls": { "spotify": <str> }, "href": <str>, "id": <str>, "images": [ { "height": <int>, "url": <str>, "width": <int> } ], "name": <str>, "release_date": <str>, "release_date_precision": <str>, "restrictions": { "reason": <str> }, "total_tracks": <int>, "type": "album", "uri": <str> }, "artists": [ { "external_urls": { "spotify": <str> }, "href": <str>, "id": <str>, "name": <str>, "type": "artist", "uri": <str> } ], "available_markets": <list[str]>, "disc_number": <int>, "duration_ms": <int>, "explicit": <bool>, "external_ids": { "ean": <str>, "isrc": <str>, "upc": <str> }, "external_urls": { "spotify": <str> }, "href": <str>, "id": <str>, "is_local": <bool>, "is_playable": <bool>, "linked_from": {}, "name": <str>, "popularity": <int>, "preview_url": <str>, "restrictions": { "reason": <str> }, "track_number": <int>, "type": "track", "uri": <str> } ] }
- 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.
Third-party application mode
- Extended quota mode before November 27, 2024
Access 30-second preview URLs. 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"]
- 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.
Sample responses
{ "album": { "album_type": <str>, "artists": [ { "external_urls": { "spotify": <str> }, "href": <str>, "id": <str>, "name": <str>, "type": "artist", "uri": <str> } ], "available_markets": <list[str]>, "external_urls": { "spotify": <str> }, "href": <str>, "id": <str>, "images": [ { "height": <int>, "url": <str>, "width": <int> } ], "name": <str>, "release_date": <str>, "release_date_precision": <str>, "restrictions": { "reason": <str> }, "total_tracks": <int>, "type": "album", "uri": <str> }, "artists": [ { "external_urls": { "spotify": <str> }, "href": <str>, "id": <str>, "name": <str>, "type": "artist", "uri": <str> } ], "available_markets": <list[str]>, "disc_number": <int>, "duration_ms": <int>, "explicit": <bool>, "external_ids": { "ean": <str>, "isrc": <str>, "upc": <str> }, "external_urls": { "spotify": <str> }, "href": <str>, "id": <str>, "is_local": <bool>, "is_playable": <bool>, "linked_from": <dict[str, Any]>, "name": <str>, "popularity": <int>, "preview_url": <str>, "restrictions": { "reason": <str> }, "track_number": <int>, "type": "track", "uri": <str> }
{ "tracks": [ { "album": { "album_type": <str>, "artists": [ { "external_urls": { "spotify": <str> }, "href": <str>, "id": <str>, "name": <str>, "type": "artist", "uri": <str> } ], "available_markets": <list[str]>, "external_urls": { "spotify": <str> }, "href": <str>, "id": <str>, "images": [ { "height": <int>, "url": <str>, "width": <int> } ], "name": <str>, "release_date": <str>, "release_date_precision": <str>, "restrictions": { "reason": <str> }, "total_tracks": <int>, "type": "album", "uri": <str> }, "artists": [ { "external_urls": { "spotify": <str> }, "href": <str>, "id": <str>, "name": <str>, "type": "artist", "uri": <str> } ], "available_markets": <list[str]>, "disc_number": <int>, "duration_ms": <int>, "explicit": <bool>, "external_ids": { "ean": <str>, "isrc": <str>, "upc": <str> }, "external_urls": { "spotify": <str> }, "href": <str>, "id": <str>, "is_local": <bool>, "is_playable": <bool>, "linked_from": <dict[str, Any]>, "name": <str>, "popularity": <int>, "preview_url": <str>, "restrictions": { "reason": <str> }, "track_number": <int>, "type": "track", "uri": <str> } ] }
- 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-modifyscopeManage 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-modifyscopeManage 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" } ]