Skip to main content

SpotAPI logo

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

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.

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.

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 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)

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

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

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

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

Select from 2 files

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