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.
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:
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.
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
SpotAPIErrorfor library failures. - Use
AsyncClientdirectly 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.
Metadata
Release files for spotapi 2.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| spotapi-2.1.0.tar.gz | 1.7 MB | With provenance | Details for spotapi-2.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| spotapi-2.1.0-py3-none-any.whl | Python 3 | none | any | Details for spotapi-2.1.0-py3-none-any.whl |
Total release size: 2.0 MB
Release files / spotapi-2.1.0.tar.gz
| Download URL | spotapi-2.1.0.tar.gz |
|---|---|
| Size | 1.7 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
52ab253fc76717b7c90890df2b7d568bde4d85cb89c57df39d1b294ee398ea48
|
|
BLAKE2b-256 checksum How to use checksums |
bde33aa52df2245e45ce9aeaac1c6a1eae3315c781f5c7fc05580575073d6c2a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.
Transparency logRelease files / spotapi-2.1.0-py3-none-any.whl
| Download URL | spotapi-2.1.0-py3-none-any.whl |
|---|---|
| Size | 325.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
0afbe2cda5129708d5d66b5166f2644bbde2bef9ca263708307c5580edae00a8
|
|
BLAKE2b-256 checksum How to use checksums |
fc14ebcf2e7e908efb0127b2f29280df4119c479e3e39b87c0c9e01cb0dcb935
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.
Transparency logSecurity for spotapi 2.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for spotapi-2.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.