SpotifyScraper

Extract public Spotify data — tracks, albums, artists, playlists, and podcasts — without the official API or an API key.

🎧 Try it live in your browser → — paste any Spotify link and watch SpotifyScraper pull typed data, cover art, and a preview, with the exact Python that does it. (How it was built.)

SpotifyScraper bootstraps an anonymous token from Spotify's own public embed pages and reads the same JSON endpoints the web player uses, returning typed, immutable models. v3 is a ground-up rewrite focused on reliability and a clean, modern API. Public data needs no login; the opt-in logged-in features (lyrics, podcast transcripts, and account info) add your own Spotify sp_dc cookie — never a password or an API key.

Upgrading from v2? See the migration guide. The previous line lives on the v2.x branch.

SpotifyScraper vs. the official API (spotipy)

spotipy wraps Spotify's official Web API — the right choice when you need to write to a user's account or read private/library data. SpotifyScraper reads the public data the web player already exposes, so it skips the setup entirely.

Use spotipy for authenticated writes and private, market-accurate data; use SpotifyScraper for fast, key-free access to public metadata, lyrics, and previews — plus a drop-in MCP server for AI agents.

Hit by the official-API deprecations? Spotify's audio-features, recommendations, and related-artists endpoints have returned 403 for new apps since Nov 2024. SpotifyScraper still returns related artists and recommendations with no API key. (It can't bring back audio-features — Spotify removed that data entirely, from every tool.)

Install

pip install spotifyscraper                 # core (only depends on httpx)
pip install "spotifyscraper[media]"        # + cover/preview embedding (mutagen)
pip install "spotifyscraper[browser]"      # + Playwright browser fallback & login
pip install "spotifyscraper[cli]"          # + the spotifyscraper command-line tool
pip install "spotifyscraper[keyring]"      # + store the login cookie in the OS keyring
pip install "spotifyscraper[mcp]"          # + the spotifyscraper-mcp MCP server for LLM hosts
pip install "spotifyscraper[all]"          # everything

Python 3.10+.

Quickstart

from spotify_scraper import SpotifyClient

with SpotifyClient() as client:
    track = client.get_track("https://open.spotify.com/track/4uLU6hMCjMI75M1A2tKUQC")
    print(track.name, "—", track.artists[0].name)
    print(track.duration_ms, "ms |", track.preview_url)

    print(track.to_dict())          # JSON-safe dict, if you prefer dicts

Every entity has its own method — get_track, get_album, get_artist, get_playlist, get_episode, get_show — each accepting a URL, URI, or bare ID.

Async

import asyncio
from spotify_scraper import AsyncSpotifyClient

async def main():
    async with AsyncSpotifyClient() as client:
        track, album = await asyncio.gather(
            client.get_track("4uLU6hMCjMI75M1A2tKUQC"),
            client.get_album("6N9PS4QXF1D0OWPk0Sxtb4"),
        )
        print(track.name, "|", album.name)

asyncio.run(main())

Download a cover and preview

from spotify_scraper import SpotifyClient

with SpotifyClient() as client:
    track = client.get_track("4uLU6hMCjMI75M1A2tKUQC")
    client.download_cover(track, dest="covers/")
    client.download_preview(track, dest="previews/", embed_cover=True)  # needs [media]

Localized display names

Pass locale — a BCP-47 language tag: a bare language subtag ("de", "ja") or a language-region tag ("ja-JP") — to localize the language of display names. Set it per client or override it per call:

with SpotifyClient(locale="ja-JP") as client:        # default for every call
    track = client.get_track("4uLU6hMCjMI75M1A2tKUQC")
    other = client.get_track("4uLU6hMCjMI75M1A2tKUQC", locale="de-DE")  # per-call wins

It is sent as the Accept-Language header and changes only how names are spelled. It is not a country/market code — a bare "US" is meaningless as a language and is ignored — and it does not filter regional availability or vary preview URLs: anonymous Spotify resolves country from the request IP, and its pathfinder silently ignores a market variable. True market/availability filtering requires the authenticated Web API, which this library does not implement; for region-specific results, point the client's proxy at the target region. See the localization guide.

Features

• All core entities + podcasts — tracks, albums, artists, playlists, shows, episodes.
• Search across every entity type, returning one typed SearchResults.
• Charts & discovery — editorial charts, related artists, full paginated discography, and album recommendations.
• Cover colors & Canvas — extract an artwork's theming palette and download a track's looping Canvas video.
• Credits & concerts — performers/writers/producers and an artist's upcoming live events.
• Public user profiles — get_user() (name, follower counts, public playlists).
• MCP server — expose everything to Claude/LLMs via spotifyscraper-mcp (batch tools + a one-call get_track_visuals); also ships as a container on ghcr.io.
• Localized display names — pass a BCP-47 language tag (locale) to set the language of names.
• Lyrics & podcast transcripts — cookie-authenticated, time-synced, one token for both.
• Browser-assisted login + session persistence — log in once, then run headless (no stored passwords).
• Account-aware — get_account() / is_premium(), plus cookie-free session_info().
• Batch helpers — plural get_*s([...]) with partial-failure-safe results and managed concurrency.
• Sync & async clients sharing one sans-io core.
• Typed, frozen models with JSON-safe to_dict() / from_dict().
• Two-tier resilience — Spotify's GraphQL API with automatic fallback to the embed page.
• One core dependency (httpx); media and browser support are optional extras.
• Optional response cache — opt-in, persistent, token-safe (only token-free pathfinder GETs).
• Anti-ban built in — per-host rate limiting, retries with backoff, UA rotation, proxies.
• Browser fallback via Playwright when you need a real browser.

Command line

With the cli extra installed, a spotifyscraper command is available:

spotifyscraper track 4uLU6hMCjMI75M1A2tKUQC          # entity metadata as JSON
spotifyscraper playlist <id> --max-tracks 50 --pretty
spotifyscraper download preview <id> -o ./previews --embed-cover

Every command emits JSON, so it composes with tools like jq. See the CLI guide.

Batch helpers

Each getter has a plural sibling (get_tracks, get_albums, …) that fetches many inputs and returns one BatchItem per input — index-aligned, and a dead input never aborts the rest:

items = client.get_tracks(["4uLU6hMCjMI75M1A2tKUQC", "bad-id"])
ok = [i.result for i in items if i.ok]
failed = {i.value: i.error for i in items if not i.ok}

The async client runs them concurrently, bounded by max_concurrency (defaul