Spotifyscraper

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 →](https://aliakhtari.com/spotify/) — 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 --max-tracks 50 --pretty spotifyscraper download preview -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 (default 5). See the batch guide.

Response caching

For repeated lookups, enable an opt-in persistent cache. It only stores token-free pathfinder responses — never the embed pages that carry the anonymous token — so no credential is ever written to disk:

from spotify_scraper import SpotifyClient, CacheConfig, FileCache

with SpotifyClient(cache=CacheConfig(store=FileCache())) as client: client.get_track("4uLU6hMCjMI75M1A2tKUQC") # first call hits the network client.get_track("4uLU6hMCjMI75M1A2tKUQC") # served from the cache

Default TTL is 24h; the FileCache is stdlib-only and the backend is pluggable. See the caching guide.

Search

search() runs one anonymous, aggregate query across every entity type and returns a typed SearchResults:

from spotify_scraper import SpotifyClient

with SpotifyClient() as client: results = client.search("daft punk", types=("track", "artist"), limit=5) print(results.total, "track matches") for track in results.tracks: print(track.name, "—", track.artists[0].name)

Hits are sparse (pass an id to get_album()/get_show() for the full entity); total is the track-match count. See the search guide.

Lyrics & transcripts

Lyrics and podcast transcripts need a Spotify account cookie (sp_dc); the library handles the token handshake for you, and one cookie powers both:

from spotify_scraper import SpotifyClient

with SpotifyClient(cookies="cookies.txt") as client: # or cookies={"sp_dc": "..."} lyrics = client.get_lyrics("4uLU6hMCjMI75M1A2tKUQC") for line in lyrics.lines: print(line.start_ms, line.text)

transcript = client.get_transcript("07gKzPFkbvGF0cHoeG7ARS") # a podcast episode for line in transcript.lines: print(line.s