← Back to archive

Repo of the Day

Aran404/SpotAPI

Published: Nov 19, 2026

Open repository ↗

Typed async Spotify tools for Python, built on Spotify’s private API. Search public data without an API key, control playback without Premium, and build catalogue, playlist and player apps

Summary

SpotAPI is a typed, asynchronous Python library and CLI for working with Spotify through its unofficial web-player API. Public catalogue searches, lookups, credits, and playlist inspection require no API key or login, while account features use a Spotify session cookie. It also includes terminal interfaces for browsing results and controlling an existing Spotify player.

What it is useful for

  • Catalogue search and inspection: Find tracks, artists, albums, and playlists, then traverse Spotify links or read track credits through typed result objects.
  • Playlist-oriented applications: Build discovery tools, playlist crates, and duplicate-aware editors. Playlist occurrences have IDs, allowing one copy of a repeated track to be moved or removed without affecting another.
  • Private account workflows: Read liked music and rankings, edit playlists, and access live player events after authenticating with SPOTIFY_COOKIE.
  • Command-line and terminal workflows: The CLI supports JSON search output, library and player commands, and playlist operations. The optional Discover interface adds keyboard-driven browsing, while Studio provides track details, lyrics, and playback seeking.
  • Data-oriented Python projects: Catalogue can be shared across several asynchronous operations, and Private manages an authenticated session through an async context manager.

The main caveat is that SpotAPI relies on unofficial web-player contracts rather than Spotify’s official Web API. Those endpoints have their own rate limits, authentication requirements, and changing response contracts, so teams should review the project’s legal notice and release-check documentation before integrating it. Studio uses the platform’s native WebView, requires platform-specific setup, and controls an existing Spotify device rather than rendering audio itself. Mix-map analysis also depends on the tempo and key data Spotify supplies; unavailable analysis remains unknown.

How engineers can use it

SpotAPI requires Python 3.11 or newer. The documented installation and first search are:

python -m pip install spotapi
spotapi search "Daft Punk"

For direct use in an asynchronous application:

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

When several public operations are needed, reuse one catalogue context:

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)

Optional interfaces have documented extras: install spotapi[demo] for spotapi discover, or spotapi[studio] for spotapi studio. Account, library, and player commands require SPOTIFY_COOKIE in the environment. SpotAPI 2 is an async-first breaking release; synchronous projects can use SyncCatalogue, while existing v1 applications can pin spotapi==1.2.8 during migration.