Skip to main content

​
Show and Episode Models

The show and episode models represent podcast data from the Spotify API.

​
SimplifiedShow

Basic show (podcast) information embedded in other objects.

​
Fields

​
available_markets
list[str] | None
A list of ISO 3166-1 alpha-2 country codes where the show is available
​
copyrights
list[Copyright]
required
Copyright statements for the show. See Common Models.
​
description
str
required
Plain text description of the show
​
html_description
str
required
HTML description of the show
​
explicit
bool
required
Whether the show contains explicit content
​
external_urls
ExternalUrls
required
External URLs for this show. See Common Models.
​
href
str
required
A link to the Web API endpoint providing full details
​
id
str
required
The Spotify ID for the show
​
images
list[Image]
required
Cover art for the show. See Common Models.
​
is_externally_hosted
bool | None
Whether the show is hosted outside of Spotify’s CDN
​
languages
list[str]
required
A list of languages the show is available in
​
media_type
str
required
The media type of the show (typically “audio”)
​
name
str
required
The name of the show
​
publisher
str
required
The publisher of the show
​
type
Literal['show']
required
The object type, always “show”
​
uri
str
required
The Spotify URI for the show
​
total_episodes
int
required
The total number of episodes in the show

​
SimplifiedEpisode

Basic episode information embedded in other objects.

​
Fields

​
audio_preview_url
str | None
A URL to a 30-second preview (MP3) of the episode
​
description
str
required
Plain text description of the episode
​
html_description
str
required
HTML description of the episode
​
duration_ms
int
required
The duration of the episode in milliseconds
​
explicit
bool
required
Whether the episode contains explicit content
​
external_urls
ExternalUrls
required
External URLs for this episode. See Common Models.
​
href
str
required
A link to the Web API endpoint providing full details
​
id
str
required
The Spotify ID for the episode
​
images
list[Image]
required
Cover art for the episode. See Common Models.
​
is_externally_hosted
bool | None
Whether the episode is hosted outside of Spotify’s CDN
​
is_playable
bool | None
Whether the episode is playable in the current market
​
language
str | None
The language of the episode (deprecated, use languages instead)
​
languages
list[str]
required
A list of languages available for the episode
​
name
str
required
The name of the episode
​
release_date
str
required
The release date of the episode
​
release_date_precision
str
required
The precision of the release date: “year”, “month”, or “day”
​
restrictions
Restriction | None
Content restrictions applied to this episode. See Common Models.
​
resume_point
ResumePoint | None
The user’s resume point for the episode (only when authenticated). See Audiobook Models.
​
type
Literal['episode']
required
The object type, always “episode”
​
uri
str
required
The Spotify URI for the episode

​
Show

Complete show object with episode list. Extends SimplifiedShow.

​
Additional Fields

​
episodes
Page[SimplifiedEpisode]
required
Paginated list of episodes in the show. See Common Models.

​
Example JSON

{
  "id": "show123",
  "name": "Example Podcast",
  "publisher": "Example Media",
  "description": "An example podcast about technology",
  "html_description": "<p>An example podcast about technology</p>",
  "explicit": false,
  "languages": ["en"],
  "media_type": "audio",
  "total_episodes": 150,
  "episodes": {
    "href": "https://api.spotify.com/v1/shows/show123/episodes",
    "items": [
      {
        "id": "episode123",
        "name": "Episode 1: Introduction",
        "duration_ms": 3600000,
        "release_date": "2023-01-15"
      }
    ],
    "limit": 50,
    "next": "https://api.spotify.com/v1/shows/show123/episodes?offset=50",
    "offset": 0,
    "previous": null,
    "total": 150
  }
}

​
Episode

Complete episode object with show information. Extends SimplifiedEpisode.

​
Additional Fields

​
show
SimplifiedShow
required
The show this episode belongs to

​
Example JSON

{
  "id": "episode123",
  "name": "Episode 1: Introduction",
  "description": "Welcome to the first episode",
  "html_description": "<p>Welcome to the first episode</p>",
  "duration_ms": 3600000,
  "explicit": false,
  "release_date": "2023-01-15",
  "release_date_precision": "day",
  "languages": ["en"],
  "show": {
    "id": "show123",
    "name": "Example Podcast",
    "publisher": "Example Media",
    "type": "show",
    "uri": "spotify:show:show123"
  },
  "type": "episode",
  "uri": "spotify:episode:episode123"
}

​
SavedShow

Represents a show saved in a user’s library with metadata about when it was saved.

​
Fields

​
added_at
datetime
required
The timestamp when the show was saved to the user’s library
​
show
SimplifiedShow
required
The simplified show object

​
Example JSON

{
  "added_at": "2023-12-01T10:30:00Z",
  "show": {
    "id": "show123",
    "name": "Example Podcast",
    "publisher": "Example Media",
    "type": "show"
  }
}

​
SavedEpisode

Represents an episode saved in a user’s library with metadata about when it was saved.

​
Fields

​
added_at
datetime
required
The timestamp when the episode was saved to the user’s library
​
episode
Episode
required
The complete episode object with show information

​
Example JSON

{
  "added_at": "2023-12-01T10:30:00Z",
  "episode": {
    "id": "episode123",
    "name": "Episode 1: Introduction",
    "duration_ms": 3600000,
    "show": {
      "id": "show123",
      "name": "Example Podcast"
    }
  }
}

​
Model Relationships

Show/Episode Model Hierarchy
  • SimplifiedShow contains basic podcast metadata
  • Show extends SimplifiedShow and includes a Page of SimplifiedEpisode objects
  • SimplifiedEpisode contains basic episode information
  • Episode extends SimplifiedEpisode and includes the parent SimplifiedShow
  • SavedShow wraps a SimplifiedShow with a timestamp
  • SavedEpisode wraps a complete Episode with a timestamp

​
Usage Example

from spotify_sdk.models.show import Show, Episode, SavedShow

# Parse a show from the API response
show = Show(**api_response)

print(f"Podcast: {show.name}")
print(f"Publisher: {show.publisher}")
print(f"Total episodes: {show.total_episodes}")
print(f"Explicit: {'Yes' if show.explicit else 'No'}")

# Iterate through episodes
for episode in show.episodes.items:
    duration_min = episode.duration_ms // 60000
    print(f"\n{episode.name}")
    print(f"  Duration: {duration_min} minutes")
    print(f"  Released: {episode.release_date}")
    
    # Check resume point if available
    if episode.resume_point:
        if episode.resume_point.fully_played:
            print("  ✓ Completed")
        else:
            resume_min = episode.resume_point.resume_position_ms // 60000
            print(f"  Resume at {resume_min} minutes")

# Working with saved shows
saved_show = SavedShow(**saved_response)
print(f"\nSaved on: {saved_show.added_at.strftime('%Y-%m-%d')}")

​
Common Use Cases

Build docs developers (and LLMs) love

Get started for freeTalk to us