ArtistsAPI

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

Bases: SpotifyResourceAPI

Artists 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

follow_artists

Users > Follow Artists: Follow one or more artists.

get_artist_albums

Artists > Get Artist's Albums: Get Spotify catalog information for albums by an artist.

get_artist_top_tracks

Artists > Get Artist's Top Tracks: Get Spotify catalog information for top tracks by an artist.

get_artists

Artists > Get Artist: Get Spotify catalog information for an artist․ Artists > Get Several Artists: Get Spotify catalog information for multiple artists.

get_my_followed_artists

Users > Get Followed Artists: Get Spotify catalog information for artists followed by the current user.

get_my_top_artists

Users > Get User's Top Artists: Get Spotify catalog information for the current user's top artists.

get_similar_artists

Artists > Get Artist's Related Artists: Get Spotify catalog information for related artists.

is_following_artists

Users > Check If Current User Follows Artists: Check whether the current user is following one or more artists.

unfollow_artists

Users > Unfollow Artists: Unfollow one or more artists.
follow_artists(artist_ids: str | Collection[str], /) → None[source]

Users > Follow Artists: Follow one or more artists.

Authorization scope

user-follow-modify scope

Manage your saved content. Learn more.

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

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

Examples:

  • "2CIMQHirSU0MQqyYHq0eOx"

  • "2CIMQHirSU0MQqyYHq0eOx,57dN52uHvrHOxijzpIgu3E"

  • ["2CIMQHirSU0MQqyYHq0eOx", "57dN52uHvrHOxijzpIgu3E"]

get_artist_albums(artist_id: str, /, *, album_types: str | Collection[str] | None = None, country_code: str | None = None, limit: int | None = None, offset: int | None = None) → dict[str, Any][source]

Artists > Get Artist’s Albums: Get Spotify catalog information for albums by an artist.

Parameters:
artist_idstr; positional-only

Spotify ID of the artist.

Example: "0TnOYISbd1XYRBk9myaseg".

album_typesstr or Collection[str]; optional

Album types to return. If not provided, all album types will be returned.

Valid values: "album", "single", "appears_on", "compilation".

Examples: "album", "album,single", ["single", "appears_on"].

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 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 artist’s albums.

Sample response

{
  "href": <str>,
  "items": [
    {
      "album_group": <str>,
      "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>
}
get_artist_top_tracks(artist_id: str, /, *, country_code: str) → dict[str, Any][source]

Artists > Get Artist’s Top Tracks: Get Spotify catalog information for top tracks by an artist.

Third-party application mode

Extended quota mode before November 27, 2024

Access 30-second preview URLs. Learn more.

Parameters:
artist_idstr; positional-only

Spotify ID of the artist.

Example: "0TnOYISbd1XYRBk9myaseg".

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:
top_tracksdict[str, Any]

Spotify metadata for the artist’s top tracks.

Sample response

{
  "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_artists(artist_ids: str | Collection[str], /) → dict[str, Any][source]

Artists > Get Artist: Get Spotify catalog information for an artist․ Artists > Get Several Artists: Get Spotify catalog information for multiple artists.

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

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

Examples:

  • "2CIMQHirSU0MQqyYHq0eOx"

  • "2CIMQHirSU0MQqyYHq0eOx,57dN52uHvrHOxijzpIgu3E"

  • ["2CIMQHirSU0MQqyYHq0eOx", "57dN52uHvrHOxijzpIgu3E"]

Returns:
artistsdict[str, Any]

Spotify metadata for the artists.

Sample responses

{
  "external_urls": {
    "spotify": <str>
  },
  "followers": {
    "href": <str>,
    "total": <int>
  },
  "genres": <list[str]>,
  "href": <str>,
  "id": <str>,
  "images": [
    {
      "height": <int>,
      "url": <str>,
      "width": <int>
    }
  ],
  "name": <str>,
  "popularity": <int>,
  "type": "artist",
  "uri": <str>
}

{
  "artists": [
    {
      "external_urls": {
        "spotify": <str>
      },
      "followers": {
        "href": <str>,
        "total": <int>
      },
      "genres": <list[str]>,
      "href": <str>,
      "id": <str>,
      "images": [
        {
          "height": <int>,
          "url": <str>,
          "width": <int>
        }
      ],
      "name": <str>,
      "popularity": <int>,
      "type": "artist",
      "uri": <str>
    }
  ]
}
get_my_followed_artists(*, cursor: str | None = None, limit: int | None = None) → dict[str, Any][source]

Users > Get Followed Artists: Get Spotify catalog information for artists followed by the current user.

Authorization scope

user-follow-read scope

Access your followers and who you are following. Learn more.

Parameters:
limitint; keyword-only; optional

Maximum number of artists to return.

Valid range: 1 to 50.

API default: 20.

cursorstr; keyword-only; optional

Cursor (Spotify ID of the last artist retrieved in the previous request) for fetching the next page of results.

Example: "0I2XqVXqHScXjHhk6AYYRe".

Returns:
artistsdict[str, Any]

Spotify metadata for the artists followed by the current user.

Sample response

{
  "artists": {
    "cursors": {
      "after": <str>,
      "before": <str>
    },
    "href": <str>,
    "items": [
      {
        "external_urls": {
          "spotify": <str>
        },
        "followers": {
          "href": <str>,
          "total": <int>
        },
        "genres": <list[str]>,
        "href": <str>,
        "id": <str>,
        "images": [
          {
            "url": <str>,
            "height": <int>,
            "width": <int>
          }
        ],
        "name": <str>,
        "popularity": <int>,
        "type": "artist",
        "uri": <str>
      }
    ],
    "limit": <int>,
    "next": <str>,
    "total": <int>
  }
}
get_my_top_artists(*, time_range: str | None = None, limit: int | None = None, offset: int | None = None) → dict[str, Any][source]

Users > Get User’s Top Artists: Get Spotify catalog information for the current user’s top artists.

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 artists.

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

Valid range: 1 to 50.

API default: 20.

offsetint; keyword-only; optional

Index of the first artist to return. Use with limit to get the next batch of artists.

Minimum value: 0.

API default: 0.

Returns:
artistsdict[str, Any]

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

Sample response :class: response dropdown

{
  "href": <str>,
  "items": [
    {
      "external_urls": {
        "spotify": <str>
      },
      "followers": {
        "href": <str>,
        "total": <int>
      },
      "genres": <list[str]>,
      "href": <str>,
      "id": <str>,
      "images": [
        {
          "height": <int>,
          "url": <str>,
          "width": <int>
        }
      ],
      "name": <str>,
      "type": "artist",
      "uri": <str>
    }
  ],
  "limit": <int>,
  "next": <str>,
  "offset": <int>,
  "previous": <str>,
  "total": <int>
}
get_similar_artists(artist_id: str, /) → dict[str, Any][source]

Artists > Get Artist’s Related Artists: Get Spotify catalog information for related artists.

Third-party application mode

Extended quota mode before November 27, 2024

Access the GET /artists/{artist_id} /related-artists endpoint. Learn more.

Parameters:
artist_idstr; positional-only

Spotify ID of the artist.

Example: "0TnOYISbd1XYRBk9myaseg".

Returns:
artistsdict[str, Any]

Spotify metadata for the related artists.

Sample response

{
  "artists": [
    {
      "external_urls": {
        "spotify": <str>
      },
      "followers": {
        "href": <str>,
        "total": <int>
      },
      "genres": <list[str]>,
      "href": <str>,
      "id": <str>,
      "images": [
        {
          "height": <int>,
          "url": <str>,
          "width": <int>
        }
      ],
      "name": <str>,
      "popularity": <int>,
      "type": "artist",
      "uri": <str>
    }
  ]
}
is_following_artists(artist_ids: str | Collection[str], /) → list[bool][source]

Users > Check If Current User Follows Artists: Check whether the current user is following one or more artists.

Authorization scope

user-follow-read scope

Access your followers and who you are following. Learn more.

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

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

Examples:

  • "2CIMQHirSU0MQqyYHq0eOx"

  • "2CIMQHirSU0MQqyYHq0eOx,57dN52uHvrHOxijzpIgu3E"

  • ["2CIMQHirSU0MQqyYHq0eOx", "57dN52uHvrHOxijzpIgu3E"]

Returns:
followinglist[bool]

Whether the current user follows the specified artists.

Sample response: [False, True].

unfollow_artists(artist_ids: str | Collection[str], /) → None[source]

Users > Unfollow Artists: Unfollow one or more artists.

Authorization scope

user-follow-modify scope

Manage your saved content. Learn more.

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

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

Examples:

  • "2CIMQHirSU0MQqyYHq0eOx"

  • "2CIMQHirSU0MQqyYHq0eOx,57dN52uHvrHOxijzpIgu3E"

  • ["2CIMQHirSU0MQqyYHq0eOx", "57dN52uHvrHOxijzpIgu3E"]