AlbumsAPI¶

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

Bases: SpotifyResourceAPI

Albums 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_albums_saved`	Albums > Check User's Saved Albums: Check whether one or more albums are saved in the current user's library.
`get_album_tracks`	Albums > Get Album Tracks: Get Spotify catalog information for tracks on an album.
`get_albums`	Albums > Get Album: Get Spotify catalog information for an album․ Albums > Get Several Albums: Get Spotify catalog information for multiple albums.
`get_my_saved_albums`	Albums > Get User's Saved Albums: Get Spotify catalog information for the albums saved in the current user's library.
`get_new_releases`	Albums > Get New Releases: Get Spotify catalog information for featured new releases.
`remove_saved_albums`	Albums > Remove User's Saved Albums: Remove one or more albums from the current user's library.
`save_albums`	Albums > Save Albums for Current User: Save one or more albums to the current user's library.

are_albums_saved(album_ids: str | Collection[str], /) → list[bool][source]¶

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

Authorization scope

Required

user-library-read scope: Access your saved content. Learn more.

Parameters:

album_idsstr or Collection[str]; positional-only

Spotify IDs of the albums. A maximum of 20 IDs can be sent in a request.

Examples:

"382ObEPsp2rxGrnsizN5TX"
"382ObEPsp2rxGrnsizN5TX,1A2GTWGtFfWp7KSQTwWOyo"
["382ObEPsp2rxGrnsizN5TX", "1A2GTWGtFfWp7KSQTwWOyo"]

Returns:

savedlist[bool]: Whether the current user has the specified albums saved in their library.

get_album_tracks(album_id: str, /, *, country_code: str | None = None, limit: int | None = None, offset: int | None = None) → dict[str, Any][source]¶

Albums > Get Album Tracks: Get Spotify catalog information for tracks on an album.

Third-party application mode

Optional

Extended quota mode before November 27, 2024: Access 30-second preview URLs. Learn more.

Parameters:

album_idstr; positional-only

Spotify ID of the album.

Example: "4aawyAB9vmqN3uQ7FjRGTy".

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 album’s tracks.

Sample response

{
  "href": <str>,
  "items": [
    {
      "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_urls": {
        "spotify": <str>
      },
      "href": <str>,
      "id": <str>,
      "is_local": <bool>,
      "is_playable": <bool>,
      "linked_from": {
        "external_urls": {
          "spotify": <str>
        },
        "href": <str>,
        "id": <str>,
        "type": "track",
        "uri": <str>
      },
      "name": <str>,
      "preview_url": <str>,
      "restrictions": {
        "reason": <str>
      },
      "track_number": <int>,
      "type": "track",
      "uri": <str>
    }
  ],
  "limit": <int>,
  "next": <str>,
  "offset": <int>,
  "previous": <str>,
  "total": <int>
}

get_albums(album_ids: str | Collection[str], /, *, country_code: str | None = None) → dict[str, Any][source]¶

Albums > Get Album: Get Spotify catalog information for an album․ Albums > Get Several Albums: Get Spotify catalog information for multiple albums.

Third-party application mode

Optional

Extended quota mode before November 27, 2024: Access 30-second preview URLs. Learn more.

Parameters:

album_idsstr or Collection[str]; positional-only

Spotify IDs of the albums. A maximum of 20 IDs can be sent in a request.

Examples:

"382ObEPsp2rxGrnsizN5TX"
"382ObEPsp2rxGrnsizN5TX,1A2GTWGtFfWp7KSQTwWOyo"
["382ObEPsp2rxGrnsizN5TX", "1A2GTWGtFfWp7KSQTwWOyo"]

country_codestr; keyword-only; optional

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:

albumsdict[str, Any]

Spotify metadata for the albums.

Sample responses

Single album

{
  "album_type": <str>,
  "artists": [
    {
      "external_urls": {
        "spotify": <str>
      },
      "href": <str>,
      "id": <str>,
      "name": <str>,
      "type": "artist",
      "uri": <str>
    }
  ],
  "available_markets": <list[str]>,
  "copyrights": [
    {
      "text": <str>,
      "type": <str>
    }
  ],
  "external_ids": {
    "ean": <str>,
    "isrc": <str>,
    "upc": <str>
  },
  "external_urls": {
    "spotify": <str>
  },
  "genres": <list[str]>,
  "href": <str>,
  "id": <str>,
  "images": [
    {
      "height": <int>,
      "url": <str>,
      "width": <int>
    }
  ],
  "label": <str>,
  "name": <str>,
  "popularity": <int>,
  "release_date": <str>,
  "release_date_precision": <str>,
  "restrictions": {
    "reason": <str>
  },
  "total_tracks": <int>,
  "tracks": {
    "href": <str>,
    "items": [
      {
        "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_urls": {
          "spotify": <str>
        },
        "href": <str>,
        "id": <str>,
        "is_local": <bool>,
        "is_playable": <bool>,
        "linked_from": {
          "external_urls": {
            "spotify": <str>
          },
          "href": <str>,
          "id": <str>,
          "type": "track",
          "uri": <str>
        },
        "name": <str>,
        "preview_url": <str>,
        "restrictions": {
          "reason": <str>
        },
        "track_number": <int>,
        "type": "track",
        "uri": <str>
      }
    ],
    "limit": <int>,
    "next": <str>,
    "offset": <int>,
    "previous": <str>,
    "total": <int>
  },
  "type": "album",
  "uri": <str>
}

Multiple albums

{
  "albums": [
    {
      "album_type": <str>,
      "artists": [
        {
          "external_urls": {
            "spotify": <str>
          },
          "href": <str>,
          "id": <str>,
          "name": <str>,
          "type": "artist",
          "uri": <str>
        }
      ],
      "available_markets": <list[str]>,
      "copyrights": [
        {
          "text": <str>,
          "type": <str>
        }
      ],
      "external_ids": {
        "ean": <str>,
        "isrc": <str>,
        "upc": <str>
      },
      "external_urls": {
        "spotify": <str>
      },
      "genres": <list[str]>,
      "href": <str>,
      "id": <str>,
      "images": [
        {
          "height": <int>,
          "url": <str>,
          "width": <int>
        }
      ],
      "label": <str>,
      "name": <str>,
      "popularity": <int>,
      "release_date": <str>,
      "release_date_precision": <str>,
      "restrictions": {
        "reason": <str>
      },
      "total_tracks": <int>,
      "tracks": {
        "href": <str>,
        "items": [
          {
            "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_urls": {
              "spotify": <str>
            },
            "href": <str>,
            "id": <str>,
            "is_local": <bool>,
            "is_playable": <bool>,
            "linked_from": {
              "external_urls": {
                "spotify": <str>
              },
              "href": <str>,
              "id": <str>,
              "type": "track",
              "uri": <str>
            },
            "name": <str>,
            "preview_url": <str>,
            "restrictions": {
              "reason": <str>
            },
            "track_number": <int>,
            "type": "track",
            "uri": <str>
          }
        ],
        "limit": <int>,
        "next": <str>,
        "offset": <int>,
        "previous": <str>,
        "total": <int>
      },
      "type": "album",
      "uri": <str>
    }
  ]
}

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

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

Authorization scope and third-party application mode

Required

user-library-read scope: Access your saved content. Learn more.

Optional

Extended quota mode before November 27, 2024: Access 30-second preview URLs. Learn more.

Parameters:

country_codestr; keyword-only; optional

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 albums to return.

Valid range: 1 to 50.

API default: 20.

offsetint; keyword-only; optional

Index of the first album to return. Use with limit to get the next batch of albums.

Minimum value: 0.

API default: 0.

Returns:

albumsdict[str, Any]

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

Sample response

{
  "href": <str>,
  "items": [
    {
      "added_at": <str>,
      "album": {
        "album_type": <str>,
        "artists": [
          {
            "external_urls": {
              "spotify": <str>
            },
            "href": <str>,
            "id": <str>,
            "name": <str>,
            "type": "artist",
            "uri": <str>
          }
        ],
        "available_markets": <list[str]>,
        "copyrights": [
          {
            "text": <str>,
            "type": <str>
          }
        ],
        "external_ids": {
          "ean": <str>,
          "isrc": <str>,
          "upc": <str>
        },
        "external_urls": {
          "spotify": <str>
        },
        "genres": <list[str]>,
        "href": <str>,
        "id": <str>,
        "images": [
          {
            "height": <int>,
            "url": <str>,
            "width": <int>
          }
        ],
        "label": <str>,
        "name": <str>,
        "popularity": <int>,
        "release_date": <str>,
        "release_date_precision": <str>,
        "restrictions": {
          "reason": <str>
        },
        "total_tracks": <int>,
        "tracks": {
          "href": <str>,
          "items": [
            {
              "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_urls": {
                "spotify": <str>
              },
              "href": <str>,
              "id": <str>,
              "is_local": <bool>,
              "is_playable": <bool>,
              "linked_from": {
                "external_urls": {
                  "spotify": <str>
                },
                "href": <str>,
                "id": <str>,
                "type": "track",
                "uri": <str>
              },
              "name": <str>,
              "preview_url": <str>,
              "restrictions": {
                "reason": <str>
              },
              "track_number": <int>,
              "type": "track",
              "uri": <str>
            }
          ],
          "limit": <int>,
          "next": <str>,
          "offset": <int>,
          "previous": <str>,
          "total": <int>
        },
        "type": "album",
        "uri": <str>
      }
    }
  ],
  "limit": <int>,
  "next": <str>,
  "offset": <int>,
  "previous": <str>,
  "total": <int>
}

get_new_releases(*, limit: int | None = None, offset: int | None = None) → dict[str, Any][source]¶

Albums > Get New Releases: Get Spotify catalog information for featured new releases.

Parameters:

limitint; keyword-only; optional

Maximum number of albums to return.

Valid range: 1 to 50.

API default: 20.

offsetint; keyword-only; optional

Index of the first album to return. Use with limit to get the next batch of albums.

Minimum value: 0.

API default: 0.

Returns:

albumsdict[str, Any]

Page of Spotify metadata for the featured new releases.

Sample response

{
  "albums": {
    "href": <str>,
    "items": [
      {
        "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>
      }
    ],
    "limit": <int>,
    "next": <str>,
    "offset": <int>,
    "previous": <str>,
    "total": <int>
  }
}

remove_saved_albums(album_ids: str | Collection[str], /) → None[source]¶

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

Authorization scope

Required

user-library-modify scope: Manage your saved content. Learn more.

Parameters:

album_idsstr or Collection[str]; positional-only

Spotify IDs of the albums. A maximum of 20 IDs can be sent in a request.

Examples:

"382ObEPsp2rxGrnsizN5TX"
"382ObEPsp2rxGrnsizN5TX,1A2GTWGtFfWp7KSQTwWOyo"
["382ObEPsp2rxGrnsizN5TX", "1A2GTWGtFfWp7KSQTwWOyo"]

save_albums(album_ids: str | Collection[str], /) → None[source]¶

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

Authorization scope

Required

user-library-modify scope: Manage your saved content. Learn more.

Parameters:

album_idsstr or Collection[str]; positional-only

Spotify IDs of the albums. A maximum of 20 IDs can be sent in a request.

Examples:

"382ObEPsp2rxGrnsizN5TX"
"382ObEPsp2rxGrnsizN5TX,1A2GTWGtFfWp7KSQTwWOyo"
["382ObEPsp2rxGrnsizN5TX", "1A2GTWGtFfWp7KSQTwWOyo"]