ShowsAPI

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

Bases: SpotifyResourceAPI

Shows 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_shows_saved

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

get_my_saved_shows

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

get_show_episodes

Shows > Get Show Episodes: Get Spotify catalog information for episodes in a show.

get_shows

Shows > Get Show: Get Spotify catalog information for a show․ Shows > Get Several Shows: Get Spotify catalog information for multiple shows.

remove_saved_shows

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

save_shows

Shows > Save Shows for Current User: Save one or more shows to the current user's library.
are_shows_saved(show_ids: str | Collection[str], /) → list[bool][source]

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

Authorization scope

user-library-read scope

Access your saved content. Learn more.

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

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

Examples:

  • "5CfCWKI5pZ28U0uOzXkDHe"

  • "5CfCWKI5pZ28U0uOzXkDHe,5as3aKmN2k11yfDDDSrvaZ"

  • [5CfCWKI5pZ28U0uOzXkDHe", "5as3aKmN2k11yfDDDSrvaZ"]

Returns:
savedlist[bool]

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

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

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

Authorization scope

user-library-read scope

Access your saved content. Learn more.

Parameters:
limitint; keyword-only; optional

Maximum number of shows to return.

Valid range: 1 to 50.

API default: 20.

offsetint; keyword-only; optional

Index of the first show to return. Use with limit to get the next batch of shows.

Minimum value: 0.

API default: 0.

Returns:
showsdict[str, Any]

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

Sample response

{
  "href": <str>,
  "items": [
    {
      "added_at": <str>,
      "show": {
        "available_markets": <list[str]>,
        "copyrights": [
          {
            "text": <str>,
            "type": <str>
          }
        ],
        "description": <str>,
        "explicit": <bool>,
        "external_urls": {
          "spotify": <str>
        },
        "href": <str>,
        "html_description": <str>,
        "id": <str>,
        "images": [
          {
            "height": <int>,
            "url": <str>,
            "width": <int>
          }
        ],
        "is_externally_hosted": <bool>,
        "languages": <list[str]>,
        "media_type": <str>,
        "name": <str>,
        "publisher": <str>,
        "total_episodes": <int>,
        "type": "show",
        "uri": <str>
      }
    }
  ],
  "limit": <int>,
  "next": <str>,
  "offset": <int>,
  "previous": <str>,
  "total": <int>
}
get_show_episodes(show_id: str, /, *, country_code: str | None = None, limit: int | None = None, offset: int | None = None) → dict[str, Any][source]

Shows > Get Show Episodes: Get Spotify catalog information for episodes in a show.

Authorization scope and third-party application mode

user-read-playback-position scope

Read your position in content you have played. Learn more.

Extended quota mode before November 27, 2024

Access 30-second preview URLs. Learn more.

Parameters:
show_idstr; positional-only

Spotify ID of the show.

Examples: "38bS44xjbVVZ3No3ByF1dJ".

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 show episodes to return.

Valid range: 1 to 50.

API default: 20.

offsetint; keyword-only; optional

Index of the first show episode to return. Use with limit to get the next batch of show episodes.

Minimum value: 0.

API default: 0.

Returns:
episodesdict[str, Any]

Page of Spotify metadata for the show’s episodes.

Sample response

{
  "href": <str>,
  "items": [
    {
      "audio_preview_url": <str>,
      "description": <str>,
      "duration_ms": <int>,
      "explicit": <bool>,
      "external_urls": {
        "spotify": <str>
      },
      "href": <str>,
      "html_description": <str>,
      "id": <str>,
      "images": [
        {
          "height": <int>,
          "url": <str>,
          "width": <int>
        }
      ],
      "is_externally_hosted": <bool>,
      "is_playable": <bool>,
      "language": <str>,
      "languages": <list[str]>,
      "name": <str>,
      "release_date": <str>,
      "release_date_precision": <str>,
      "restrictions": {
        "reason": <str>
      },
      "resume_point": {
        "fully_played": <bool>,
        "resume_position_ms": <int>
      },
      "type": "episodes",
      "uri": <str>
    }
  ],
  "limit": <int>,
  "next": <str>,
  "offset": <int>,
  "previous": <str>,
  "total": <int>
}
get_shows(show_ids: str | Collection[str], /, *, country_code: str | None = None) → dict[str, Any][source]

Shows > Get Show: Get Spotify catalog information for a show․ Shows > Get Several Shows: Get Spotify catalog information for multiple shows.

Third-party application mode

user-read-playback-position scope

Read your position in content you have played. Learn more.

Extended quota mode before November 27, 2024

Access 30-second preview URLs. Learn more.

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

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

Examples:

  • "5CfCWKI5pZ28U0uOzXkDHe"

  • "5CfCWKI5pZ28U0uOzXkDHe,5as3aKmN2k11yfDDDSrvaZ"

  • [5CfCWKI5pZ28U0uOzXkDHe", "5as3aKmN2k11yfDDDSrvaZ"]

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

Spotify metadata for the shows.

Sample responses

{
  "available_markets": <list[str]>,
  "copyrights": [
    {
      "text": <str>,
      "type": <str>
    }
  ],
  "description": <str>,
  "episodes": {
    "href": <str>,
    "items": [
      {
        "audio_preview_url": <str>,
        "description": <str>,
        "duration_ms": <int>,
        "explicit": <bool>,
        "external_urls": {
          "spotify": <str>
        },
        "href": <str>,
        "html_description": <str>,
        "id": <str>,
        "images": [
          {
            "height": <int>,
            "url": <str>,
            "width": <int>
          }
        ],
        "is_externally_hosted": <bool>,
        "is_playable": <bool>,
        "language": <str>,
        "languages": <list[str]>,
        "name": <str>,
        "release_date": <str>,
        "release_date_precision": <str>,
        "restrictions": {
          "reason": <str>
        },
        "resume_point": {
          "fully_played": <bool>,
          "resume_position_ms": <int>
        },
        "type": "episode",
        "uri": <str>
      }
    ],
    "limit": <int>,
    "next": <str>,
    "offset": <int>,
    "previous": <str>,
    "total": <int>
  },
  "explicit": <bool>,
  "external_urls": {
    "spotify": <str>
  },
  "href": <str>,
  "html_description": <str>,
  "id": <str>,
  "images": [
    {
      "height": <int>,
      "url": <str>,
      "width": <int>
    }
  ],
  "is_externally_hosted": <bool>,
  "languages": <list[str]>,
  "media_type": <str>,
  "name": <str>,
  "publisher": <str>,
  "total_episodes": <int>,
  "type": "show",
  "uri": <str>
}

{
  "shows": [
    {
      "available_markets": <list[str]>,
      "copyrights": [
        {
          "text": <str>,
          "type": <str>
        }
      ],
      "description": <str>,
      "episodes": {
        "href": <str>,
        "items": [
          {
            "audio_preview_url": <str>,
            "description": <str>,
            "duration_ms": <int>,
            "explicit": <bool>,
            "external_urls": {
              "spotify": <str>
            },
            "href": <str>,
            "html_description": <str>,
            "id": <str>,
            "images": [
              {
                "height": <int>,
                "url": <str>,
                "width": <int>
              }
            ],
            "is_externally_hosted": <bool>,
            "is_playable": <bool>,
            "language": <str>,
            "languages": <list[str]>,
            "name": <str>,
            "release_date": <str>,
            "release_date_precision": <str>,
            "restrictions": {
              "reason": <str>
            },
            "resume_point": {
              "fully_played": <bool>,
              "resume_position_ms": <int>
            },
            "type": "episode",
            "uri": <str>
          }
        ],
        "limit": <int>,
        "next": <str>,
        "offset": <int>,
        "previous": <str>,
        "total": <int>
      },
      "explicit": <bool>,
      "external_urls": {
        "spotify": <str>
      },
      "href": <str>,
      "html_description": <str>,
      "id": <str>,
      "images": [
        {
          "height": <int>,
          "url": <str>,
          "width": <int>
        }
      ],
      "is_externally_hosted": <bool>,
      "languages": <list[str]>,
      "media_type": <str>,
      "name": <str>,
      "publisher": <str>,
      "total_episodes": <int>,
      "type": "show",
      "uri": <str>
    }
  ]
}
remove_saved_shows(show_ids: str | Collection[str], /) → None[source]

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

Authorization scope

user-library-modify scope

Manage your saved content. Learn more.

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

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

Examples:

  • "5CfCWKI5pZ28U0uOzXkDHe"

  • "5CfCWKI5pZ28U0uOzXkDHe,5as3aKmN2k11yfDDDSrvaZ"

  • [5CfCWKI5pZ28U0uOzXkDHe", "5as3aKmN2k11yfDDDSrvaZ"]

save_shows(show_ids: str | Collection[str], /) → None[source]

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

Authorization scope

user-library-modify scope

Manage your saved content. Learn more.

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

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

Examples:

  • "5CfCWKI5pZ28U0uOzXkDHe"

  • "5CfCWKI5pZ28U0uOzXkDHe,5as3aKmN2k11yfDDDSrvaZ"

  • [5CfCWKI5pZ28U0uOzXkDHe", "5as3aKmN2k11yfDDDSrvaZ"]