Models

Every entity is a frozen, slotted dataclass. Fields that only the tier-1 pathfinder payload can supply are typed | None, so a value of None means "not available from the source that answered", not "empty". Every model has a JSON-safe to_dict().

Lyrics need a cookie

Lyrics and LyricsLine are populated by get_lyrics, which requires a user sp_dc cookie — see the lyrics & cookies guide.

Track

spotify_scraper.models.Track dataclass

Track(
    id: str,
    uri: str,
    name: str,
    duration_ms: int,
    explicit: bool,
    playable: bool,
    preview_url: str | None,
    artists: tuple[ArtistRef, ...],
    images: tuple[Image, ...],
    release_date: datetime | None,
    album: AlbumRef | None = None,
    track_number: int | None = None,
    play_count: int | None = None,
    share_url: str | None = None,
)

Bases: ModelBase

A Spotify track.

Tier-1-only fields (album, track_number, play_count, share_url) stay None when built from embed data alone.

url property

url: str

Canonical open.spotify.com URL for this track.

Album

spotify_scraper.models.Album dataclass

Album(
    id: str,
    uri: str,
    name: str,
    album_type: str,
    images: tuple[Image, ...],
    release_date: datetime | None,
    artists: tuple[ArtistRef, ...],
    label: str | None = None,
    total_tracks: int | None = None,
    tracks: tuple[Track, ...] = (),
    copyrights: tuple[str, ...] = (),
    share_url: str | None = None,
)

Bases: ModelBase

A Spotify album.

album_type is the lowercased release kind ("album", "single", or "compilation"). Tier-1-only fields default to None or empty.

url property

url: str

Canonical open.spotify.com URL for this album.

Artist

spotify_scraper.models.Artist dataclass

Artist(
    id: str,
    uri: str,
    name: str,
    images: tuple[Image, ...],
    biography: str | None = None,
    followers: int | None = None,
    monthly_listeners: int | None = None,
    world_rank: int | None = None,
    top_tracks: tuple[Track, ...] = (),
    albums: tuple[AlbumRef, ...] = (),
    singles: tuple[AlbumRef, ...] = (),
    external_links: tuple[str, ...] = (),
    share_url: str | None = None,
)

Bases: ModelBase

A Spotify artist.

Tier-1-only fields (biography, followers, monthly_listeners, world_rank, share_url) default to None; discography collections default to empty tuples.

url property

url: str

Canonical open.spotify.com URL for this artist.

Playlist

spotify_scraper.models.Playlist dataclass

Playlist(
    id: str,
    uri: str,
    name: str,
    description: str = "",
    owner: UserRef | None = None,
    followers: int | None = None,
    images: tuple[Image, ...] = (),
    total_tracks: int | None = None,
    tracks: tuple[PlaylistTrack, ...] = (),
    share_url: str | None = None,
)

Bases: ModelBase

A Spotify playlist.

url property

url: str

Canonical open.spotify.com URL for this playlist.

PlaylistTrack

spotify_scraper.models.PlaylistTrack dataclass

PlaylistTrack(
    track: Track,
    added_at: datetime | None = None,
    added_by: UserRef | None = None,
)

Bases: ModelBase

A track entry in a playlist, with playlist-specific metadata.

Episode

spotify_scraper.models.Episode dataclass

Episode(
    id: str,
    uri: str,
    name: str,
    duration_ms: int,
    description: str = "",
    explicit: bool = False,
    playable: bool = True,
    release_date: datetime | None = None,
    images: tuple[Image, ...] = (),
    preview_url: str | None = None,
    show: ShowRef | None = None,
    share_url: str | None = None,
)

Bases: ModelBase

A podcast episode.

Tier-1-only fields (show, share_url) are None when the episode was built from an embed payload.

url property

url: str

Canonical open.spotify.com URL for this episode.

Show

spotify_scraper.models.Show dataclass

Show(
    id: str,
    uri: str,
    name: str,
    description: str = "",
    publisher: str | None = None,
    media_type: str | None = None,
    images: tuple[Image, ...] = (),
    total_episodes: int | None = None,
    episodes: tuple[Episode, ...] = (),
    topics: tuple[str, ...] = (),
    rating: float | None = None,
    share_url: str | None = None,
)

Bases: ModelBase

A podcast show.

Tier-1-only fields (publisher, media_type, total_episodes, rating, share_url) are None when the show was built from an embed payload.

url property

url: str

Canonical open.spotify.com URL for this show.

Image

spotify_scraper.models.Image dataclass

Image(
    url: str,
    width: int | None = None,
    height: int | None = None,
)

Bases: ModelBase

An image source with optional pixel dimensions.

ArtistRef

spotify_scraper.models.ArtistRef dataclass

ArtistRef(name: str, uri: str = '', id: str = '')

Bases: ModelBase

Lightweight reference to an artist.

Embed payloads provide name (and sometimes uri); pathfinder payloads provide all fields.

AlbumRef

spotify_scraper.models.AlbumRef dataclass

AlbumRef(
    id: str,
    uri: str,
    name: str,
    images: tuple[Image, ...] = (),
)

Bases: ModelBase

Lightweight reference to an album.

ShowRef

spotify_scraper.models.ShowRef dataclass

ShowRef(
    id: str,
    uri: str,
    name: str,
    publisher: str | None = None,
    images: tuple[Image, ...] = (),
)

Bases: ModelBase

Lightweight reference to a podcast show.

UserRef

spotify_scraper.models.UserRef dataclass

UserRef(name: str, uri: str = '')

Bases: ModelBase

Lightweight reference to a Spotify user.

Lyrics

spotify_scraper.models.Lyrics dataclass

Lyrics(
    lines: tuple[LyricsLine, ...],
    sync_type: str = "UNSYNCED",
    provider: str | None = None,
    language: str | None = None,
)

Bases: ModelBase

Lyrics for a track.

sync_type is "LINE_SYNCED" when start_ms offsets are meaningful, otherwise "UNSYNCED".

LyricsLine

spotify_scraper.models.LyricsLine dataclass

LyricsLine(start_ms: int, text: str)

Bases: ModelBase

A single lyrics line with its start offset.