SpotAPI

Spotify for Python. Async, typed, and no API key for public data.

Start · Demos · Studio · Integrate · Docs

---

Search the Spotify catalogue from your terminal, or build a Python app on top of fully typed async results. Start with public data, no signup and no developer dashboard. Connect your account later for saved music, playlist editing and live player events.

SpotAPI 2 is a breaking async release. Synchronous projects can pin spotapi==1.2.8. See the migration guide and the release checks.

This README includes unreleased additions. Until they reach PyPI, install this checkout with python -m pip install -e ".[demo,studio]". Packaged releases include both interfaces; users do not need a clone to launch them.

First search

Requires Python 3.11 or newer.

python -m pip install spotapi
spotapi search "Daft Punk"

No key, no login, no config. The first request discovers Spotify's current web-player queries; this can take longer on a cold cache. Later runs reuse queries cached for the same Spotify build.

Next, browse with Discover, open Studio, or start building directly in Python:

import asyncio
from spotapi import Public


async def main() -> None:
    results = await Public.search("Daft Punk", limit=5)
    for track in results.tracks:
        print(track.name, track.uri)


asyncio.run(main())

Public searches ten categories, resolves Spotify links and streams tracks from public playlists. It cleans up its own connections.

Why SpotAPI

• No API key for public data. Search, lookups, credits and public playlists work anonymously.
• Typed and async. Every result is a model you can autocomplete, not a dict you have to guess at.
• No surprises. Reading a model never triggers a hidden HTTP request. Optional metadata stays optional.
• Duplicate-aware playlists. Edit one occurrence of a track without touching its twin.
• Your account when you want it. Liked songs, rankings, playlist edits and live player events.
• A CLI that does real work. Search, credits, playlists, library and player control from one command.
• No developer dashboard setup. No Client ID, no Premium requirement and no user cap for public data. See the comparison.

See it in action

Browse search results, artwork and typed data directly from your terminal:

For this development checkout, use python -m pip install -e ".[demo]". Once the release containing discover is published, the package-only setup is:

python -m pip install "spotapi[demo]"
spotapi discover "Daft Punk"

Demo	What you get	Run it
Discover	A keyboard-driven terminal UI for browsing Spotify's public search. No login. Start here.	spotapi discover "Daft Punk"
Mix map	Finds harmonically compatible transitions in a public playlist and tells you how far to shift the incoming track's tempo.	python -m examples.mix_map

Discover accepts a search query or Spotify link. Mix map runs from a clone of the repository and accepts your own public playlist link. Tempo and key data depend on what Spotify supplies; missing analysis stays unknown.

Studio

Open a track, read its credits, follow links into artists and albums, or expand the typed data behind every view. Studio also shows public lyrics and can seek to a timed line on a connected Spotify player.

python -m pip install "spotapi[studio]"
spotapi studio

Studio uses your platform's native WebView; see the platform setup.

Use Connect Spotify to sign in through Spotify's normal login window, or set SPOTIFY_COOKIE in a local .env. Cookies stay in Python. Playback controls an existing Spotify device; Studio does not render audio.

Studio guide · Small examples

Go beyond search

The CLI also looks up credits, lists playlist occurrences, manages liked tracks and controls an existing Spotify player:

spotapi search "Daft Punk" --type artist --json
spotapi get SPOTIFY_URL
spotapi credits 0DiWol3AO6WpXZgp0goxAV
spotapi playlist items PLAYLIST_ID --limit 10
spotapi library list
spotapi player status

search and get work anonymously. Library and player commands, playlist edits and playlist items --private read SPOTIFY_COOKIE from your environment. See sign-in setup.

Run spotapi playlist --help, spotapi library --help or spotapi player --help for every action. Playlist remove and move take occurrence IDs from playlist items, so duplicate tracks can be edited individually.

Build it into your app

Pick the idea closest to yours:

Your idea	Start with
A DJ crate with tempo and harmonic keys	Playlist crate
A public-data inspector	spotapi discover or spotapi get SPOTIFY_URL
A playlist discovery companion	Public.get_radio() · Public.get_playlist_recommendations()
Your own music dashboard	Account, rankings and saved music
A duplicate-aware playlist curator	Playlist.items() · Playlist.move_occurrences() · Playlist.remove_occurrences()
A live now-playing display	Player example · Lyrics example

Public data: reuse one Catalogue

For several operations, share a single context inside your async application:

from spotapi import Catalogue

async with Catalogue() as spotify:
    results = await spotify.search("Daft Punk")
    if results.artists:
        artist = await spotify.get_artist(results.artists[0].uri)
        print(artist.name)

Your own account: Private

Private opens and closes the authenticated session for you:

import os

from spotapi import Private

async with Private.from_cookies(os.environ["SPOTIFY_COOKIE"]) as spotify:
    favorites = await spotify.stats.get(time_range="medium_term", limit=5)
    for track in favorites.tracks:
        print(track.name)

Production details

• Import result types from spotapi.models.
• Catch SpotAPIError for library failures.
• Use AsyncClient directly to share transports and configure connection options.
• See the guides for ownership, cancellation and explicit mutations.

SpotAPI vs the official Web API

In February 2026, Spotify tightened Development Mode for its official Web API. Libraries built on that API, such as Spotipy, work within those limits. SpotAPI uses Spotify's web-player endpoints without a developer app. These endpoints have their own rate limits, authentication requirements and changing response contracts.

	Official Web API (Development Mode)	SpotAPI, public data
Developer app / Client ID	Required; up to 25 apps per developer	Not needed
Spotify account	App owner needs Premium in Development Mode	Not needed
Authorized users	Up to five per Client ID	No cap to manage
Intended use	Non-commercial personal projects and learning	Your call, subject to the legal notice
Setup	Create an app, then wire up credentials	pip install spotapi

Choose based on the endpoints and authentication your application needs. SpotAPI relies on unofficial web-player contracts; see the verification boundaries before integrating.

_{Checked against Spotify's migration guide and July 2026 update. The app owner needs Premium in Development Mode. Existing apps can retain previously authorized user counts above five; Extended Quota Mode differs. Development Mode apps share their developer account's quota.}

Guides

Read the complete rendered documentation, or jump directly to a guide:

First result · Coming from Spotipy · Discovery, previews and captions · Python API reference

Catalogue · Account · Player · Request policy · API layout · Migration from v1

Sponsorship

Support SpotAPI's maintenance, testing and documentation. Sponsors receive a clearly labeled placement here and, where useful, in a relevant guide.

Choose a supporter listing, featured placement, README category exclusivity, or an optional integration partnership such as a CAPTCHA-provider adapter. Users keep their choice of provider; paid services are never required for ordinary public-data workflows.

Contact aran.inbox.personal@gmail.com to discuss a placement and arrange payment directly through PayPal. See sponsorship details.

Contributing

Contributing · Tests · Release review · Legal notice · GPL-3.0

If SpotAPI helps you build something, star the repository or share what you built.