SpotAPI
Spotify in your terminal. Spotify data in your Python app.
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
Connect · Search, navigate and control an existing Spotify player from your terminal. Spotify plays the audio; SpotAPI sends the controls.
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"
That's the public catalogue. Search, resolve Spotify links, inspect credits and read public playlist metadata without setting up a Spotify developer application. The first request can take longer while SpotAPI discovers the current web-player queries; subsequent requests reuse the cached results.
Building with Python instead? The same installation provides a typed API. No terminal interface is required:
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
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]"
python -m spotapi connect
If pip warns that the connect extra does not exist, that PyPI release predates the extra. Until the next release, clone the repository and run python -m pip install -e ".[connect]" from its root.
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 to reach developers using SpotAPI. Paid placements are clearly labeled and help support the project.
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.1
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.1.tar.gz | 21.1 MB | With provenance | Details for spotapi-2.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| spotapi-2.1.1-py3-none-any.whl | Python 3 | none | any | Details for spotapi-2.1.1-py3-none-any.whl |
Total release size: 21.4 MB
Release files / spotapi-2.1.1.tar.gz
| Download URL | spotapi-2.1.1.tar.gz |
|---|---|
| Size | 21.1 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
37eec47a89a07c14364436633ea459565f519385497c3ba5e9f765b282c90630
|
|
BLAKE2b-256 checksum How to use checksums |
c536fe239c93dc6ffd5e510e70dcc36b27e0ea3753c03d4c1f3599082938fbe8
|
| 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 21, 2026.
Transparency logRelease files / spotapi-2.1.1-py3-none-any.whl
| Download URL | spotapi-2.1.1-py3-none-any.whl |
|---|---|
| Size | 356.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
4c78fc595aac59d43482a46978c854448b54cd5eb936c7ea84d4972db3d6b941
|
|
BLAKE2b-256 checksum How to use checksums |
e5c1a70ee7f08379ab9b7848f5b3eb0d6b2bdb9349fe10a64eab251b0352e86e
|
| 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 21, 2026.
Transparency logSecurity for spotapi 2.1.1
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.1.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 21, 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.