EpisodesAPI¶

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

Bases: SpotifyResourceAPI

Episodes 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_episodes_saved`	Episodes > Check User's Saved Episodes: Check whether one or more show episodes are saved in the current user's library.
`get_episodes`	Episodes > Get Episode: Get Spotify catalog information for a show episode․ Episodes > Get Several Episodes: Get Spotify catalog information for multiple show episodes.
`get_my_saved_episodes`	Episodes > Get User's Saved Episodes: Get Spotify catalog information for the show episodes saved in the current user's library.
`remove_saved_episodes`	Episodes > Remove User's Saved Episodes: Remove one or more show episodes from the current user's library.
`save_episodes`	Episodes > Save Episodes for Current User: Save one or more show episodes to the current user's library.

are_episodes_saved(episode_ids: str | Collection[str], /) → list[bool][source]¶

Episodes > Check User’s Saved Episodes: Check whether one or more show episodes are saved in the current user’s library.

Authorization scope

Required

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

Parameters:

episode_idsstr or Collection[str]; positional-only

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

Examples:

"77o6BIVlYM3msb4MMIL1jH"
"77o6BIVlYM3msb4MMIL1jH,0Q86acNRm6V9GYx55SXKwf"
["77o6BIVlYM3msb4MMIL1jH", "0Q86acNRm6V9GYx55SXKwf"]

Returns:

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

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

Episodes > Get Episode: Get Spotify catalog information for a show episode․ Episodes > Get Several Episodes: Get Spotify catalog information for multiple show episodes.

Authorization scope and third-party application mode

Required

user-read-playback-position scope: Read your position in content you have played. Learn more.

Optional

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

Parameters:

episode_idsstr or Collection[str]; positional-only

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

Examples:

"77o6BIVlYM3msb4MMIL1jH"
"77o6BIVlYM3msb4MMIL1jH,0Q86acNRm6V9GYx55SXKwf"
["77o6BIVlYM3msb4MMIL1jH", "0Q86acNRm6V9GYx55SXKwf"]

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:

episodesdict[str, Any]

Spotify metadata for the show episodes.

Sample responses

Single show episode

{
  "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>
  },
  "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>
  },
  "type": "episode",
  "uri": <str>
}

Multiple show episodes

{
  "episodes": [
    {
      "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>
      },
      "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>
      },
      "type": "episode",
      "uri": <str>
    }
  ]
}

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

Episodes > Get User’s Saved Episodes: Get Spotify catalog information for the show episodes saved in the current user’s library.

Authorization scopes and third-party application mode

Required

user-library-read scope: Access your saved content. Learn more.
user-read-playback-position scope: Read your position in content you have played. 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 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 user’s saved show episodes.

Sample response

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

remove_saved_episodes(episode_ids: str | Collection[str], /) → None[source]¶

Episodes > Remove User’s Saved Episodes: Remove one or more show episodes from the current user’s library.

Authorization scope

Required

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

Parameters:

episode_idsstr or Collection[str]; positional-only

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

Examples:

"77o6BIVlYM3msb4MMIL1jH"
"77o6BIVlYM3msb4MMIL1jH,0Q86acNRm6V9GYx55SXKwf"
["77o6BIVlYM3msb4MMIL1jH", "0Q86acNRm6V9GYx55SXKwf"]

save_episodes(episode_ids: str | Collection[str], /) → None[source]¶

Episodes > Save Episodes for Current User: Save one or more show episodes to the current user’s library.

Authorization scope

Required

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

Parameters:

episode_idsstr or Collection[str]; positional-only

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

Examples:

"77o6BIVlYM3msb4MMIL1jH"
"77o6BIVlYM3msb4MMIL1jH,0Q86acNRm6V9GYx55SXKwf"
["77o6BIVlYM3msb4MMIL1jH", "0Q86acNRm6V9GYx55SXKwf"]