SpotAPI
Build Spotify apps in Python with a typed, async API.
A typed, async Python library for Spotify's public catalogue, playlists, and connected players.
No developer app or API key for public data.
Get started · Explore · Python API · Documentation · Sponsor
Language: English · Português (Brasil) · Español · Français · 日本語
Get started
Python 3.11+ is required. Start with a real search—no Spotify login, Client ID or configuration needed.
python -m pip install spotapi
python -m spotapi search "Daft Punk"
Python API first. The same installation returns typed results to your own app; no terminal UI or Spotify developer credentials are needed:
import asyncio
from spotapi import Public
async def main():
results = await Public.search("Daft Punk", limit=5)
for track in results.tracks:
print(track.name, track.uri)
asyncio.run(main())
More Python examples · Playlist audit and CSV export · No-API-key Python guide
Connect · Search, navigate and control an existing Spotify player from your terminal. Spotify plays the audio; SpotAPI sends the controls.
The terminal Connect demo is built on the same library. Public search, Spotify links, credits and public playlist metadata need no developer app. The first request may be slower while SpotAPI discovers and caches the current web-player queries.
Want something you can browse? Open the interactive terminal explorer:
python -m pip install "spotapi[demo]"
python -m spotapi discover "Daft Punk"
Navigate search results, artwork and Spotify links without signing in. Discover example · Troubleshooting
Explore in the terminal
The CLI goes beyond search. Inspect an artist, pull track credits, or list a public playlist:
python -m spotapi search "Daft Punk" --type artist --json
python -m spotapi get SPOTIFY_URL
python -m spotapi playlist items PLAYLIST_ID --limit 10
These work without a developer API key. Account operations—liked music, private playlists and control of your existing Spotify player—require your own Spotify session. See the account guide and player guide.
Connect: control your Spotify player
Connect brings searching, device selection, up-next, playback and a live activity log into one keyboard-friendly terminal session. It operates an existing signed-in Spotify player; it does not stream, download or decrypt tracks.
Launch Connect with the optional terminal interface:
python -m pip install "spotapi[connect,browser]"
python -m playwright install chromium
python -m spotapi connect
First-time browser sign-in is covered by these commands. Already use SPOTIFY_COOKIE or a saved Connect profile? Install only spotapi[connect] and skip the browser download.
Use search Daft Punk to find music, queue 1 to add a result, or pause, next, and seek 1:30 to control playback. Open /devices to browse available players; /use 2 selects one without transferring playback, while /transfer 2 transfers playback. Ctrl+P opens the command palette.
Connect requires your Spotify session for player controls. For browser-based sign-in, you may also need the browser extra and Playwright's Chromium installation; see the Connect guide for setup.
See what else it can do
SpotAPI also powers Studio, a desktop music explorer built on the same library. Open tracks, inspect credits, follow artists and albums, and display timed lyrics. With a connected Spotify player, clicking a lyric can seek playback to that line.
Watch the synchronized-lyrics demo (GIF, about 11 MB) · Studio itself does not stream full Spotify tracks.
python -m pip install "spotapi[studio]"
python -m spotapi studio
Studio uses a native WebView. Studio setup explains platform requirements and Spotify sign-in. Lyric availability depends on the source and account entitlements; seeking needs an authenticated, controllable player.
Build with Python
The terminal demos are examples. SpotAPI is a Python library first: async operations, typed results, explicit network calls and reusable sessions.
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())
For several related operations, reuse one catalogue session:
import asyncio
from spotapi import Catalogue
async def main() -> None:
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)
asyncio.run(main())
Working with large playlists? Audit up to 10,000 playlist occurrences, identify duplicate tracks and unavailable entries, and export a CSV. The example pages through results instead of loading the whole playlist into memory. Run it from a repository checkout.
Where to go next
| Build | Start here |
|---|---|
| Music search or public metadata tools | Public catalogue |
| A playlist organizer that handles duplicate tracks correctly | Playlist API |
| A live now-playing display or controller | Player example |
| A personal music dashboard | Account and statistics |
| A DJ crate using tempo and harmonic keys | Playlist crate |
| An experimental local music recommender | Taste Lab |
Why SpotAPI?
- Start without credentials. Public catalogue search and metadata require no Spotify developer app.
- Typed, async results. Work with Python models instead of guessing dictionary keys.
- Explicit I/O. Reading a model doesn't silently trigger another HTTP request.
- More than read-only metadata. With your authenticated session, manage saved music, edit playlist occurrences and control existing players.
- Designed for exploration. Use the CLI, Discover and Studio to understand capabilities before integrating them into code.
SpotAPI uses unofficial Spotify web-player endpoints, so behavior can change when Spotify changes those endpoints. It is not a substitute for the official Web API in every use case, and public-data access is different from authenticated playback access. Compare the APIs · Verification boundaries
Documentation and migration
Quickstart · API reference · Coming from Spotipy · CLI and discovery · Troubleshooting
Upgrading from v1? SpotAPI 2 is async-first and contains breaking changes. Existing v1 apps can pin spotapi==1.2.8 while migrating, or use SyncCatalogue for new synchronous scripts. Read the migration guide.
Support SpotAPI
SpotAPI is free and open source. Sponsorship helps fund maintenance, testing and documentation without changing the library's behavior or adding paywalls.
Build developer tools? Explore sponsorship options starting at $50 for 30 days. Paid placements are clearly labeled and kept below the product demos.
Contributing
Bug reports, reproducible issues and thoughtful contributions are welcome. Contributing · Tests · Legal notice · GPL-3.0
If SpotAPI helps you build something, star the repository to help other developers discover it.
Metadata
Release files for spotapi 2.1.3
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.3.tar.gz | 21.1 MB | With provenance | Details for spotapi-2.1.3.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| spotapi-2.1.3-py3-none-any.whl | Python 3 | none | any | Details for spotapi-2.1.3-py3-none-any.whl |
Total release size: 21.4 MB
Release files / spotapi-2.1.3.tar.gz
| Download URL | spotapi-2.1.3.tar.gz |
|---|---|
| Size | 21.1 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
7be063275e42543f5568b7933898f7c5eccccb10f9549277bc3b0245edef5b30
|
|
BLAKE2b-256 checksum How to use checksums |
a31a5a3378f673c0f2721c9f5e611886671900f554cf6b0c34e6904702f308d2
|
| 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 22, 2026.
Transparency logRelease files / spotapi-2.1.3-py3-none-any.whl
| Download URL | spotapi-2.1.3-py3-none-any.whl |
|---|---|
| Size | 358.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b745a94da3a7f92d532f4d022dcf55859e9dbb1cf4eb47203fea84088320cb3d
|
|
BLAKE2b-256 checksum How to use checksums |
8bc2aeb1e971e666ac10ce1f6f6eaa2d6ecdf762f2516228151325c84b0e63ef
|
| 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 22, 2026.
Transparency logSecurity for spotapi 2.1.3
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.3.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 22, 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.