SpotAPI

Async Spotify for Python. No API key for public data.

Quickstart · Try Studio · Build with it · Guides

Search Spotify from your terminal or build a Python app with typed async results. Start with the public catalogue, then connect your account for saved music, playlist editing and live player events.

SpotAPI 2 is a breaking async release. Synchronous projects can pin spotapi==1.2.8. Migration guide · Release checks

Sponsor SpotAPI · Monthly placements with category exclusivity available.

Quickstart

Requires Python 3.11 or newer.

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

To try an unreleased checkout, run python -m pip install -e . from its root.

spotapi get SPOTIFY_URL prints details as JSON. Both commands work anonymously.

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

No login is needed. Search ten categories, resolve Spotify links, or stream tracks from a public playlist. Public cleans up its connections for you.

Try this next

From the checkout, run either example with the same install:

python -m examples.credit_trail
python -m examples.mix_map

Credit trail connects One More Time, Harder, Better, Faster, Stronger, and Starboy through shared contributor IDs. It shows where the same person is credited as a producer, writer, or lyricist. Mix map finds harmonically compatible transitions in a public playlist and tells you how far to shift the incoming track's tempo. Pass your own Spotify links to either script.

Studio

Explore a track's credits, follow links into artists and albums, or expand the typed data behind each view. Studio can also show public lyrics and seek to a timed line on a connected Spotify player.

python -m pip install -e ".[studio]"
python -m examples.studio

Use Connect Spotify to sign in through Spotify's normal login window, or set SPOTIFY_COOKIE in a local .env. Cookies stay in Python. Playback controls an existing Spotify device; Studio does not provide an audio renderer.

Studio guide · Terminal inspector · Small examples

For a keyboard-driven catalogue browser, run these commands from the checkout:

python -m pip install -e ".[demo]"
python -m examples.discover "Daft Punk"

Build with it

For several operations, reuse a Catalogue context. Inside your async application:

from spotapi import Catalogue

async with Catalogue() as spotify:
    results = await spotify.search("Daft Punk")
    artist = await spotify.get_artist(results.artists[0].uri)

For your own account, Private opens and closes the authenticated session:

import os

from spotapi import Private

async with Private.from_cookies(os.environ["SPOTIFY_COOKIE"]) as spotify:
    favorites = await spotify.stats.get(time_range="medium_term", limit=5)
    for track in favorites.tracks:
        print(track.name)

See sign-in setup for Studio login or a local cookie. Use AsyncClient directly to share transports and configure connection options.

Import result types from spotapi.models. Optional metadata stays optional, and reading a model never makes hidden HTTP requests. Catch SpotAPIError for library failures. See the guides for ownership, cancellation and explicit mutations.

Guides

Catalogue · Account · Player · API layout · Migration from v1

Contributing · Tests · Release review · Legal notice · GPL-3.0

If SpotAPI helps you build something, a star helps other developers find it.

Sponsorship

Sponsor SpotAPI's maintenance and development. Monthly placements include a labeled spot above Quickstart and, where relevant, a link in the guide your customers would use. Category exclusivity is available by agreement.

Contact aran.inbox.personal@gmail.com to discuss a placement and arrange payment directly through PayPal. See sponsorship details.