Skip to main content

SpotAPI logo

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

SpotAPI Connect controlling a real Spotify player from the terminal

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.

SpotAPI Studio desktop application preview

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)

Source distribution for spotapi 2.1.1
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)

Table of built distributions (wheels) for spotapi 2.1.1
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Release history Release notifications | RSS feed

This release

2.1.1 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page