SDK · Python
Spotify API Python SDK — checkleaked-spotify-api
The official typed Python client for this API, Python 3.8 or newer: the same 110 methods and 25 namespaces as the npm package, snake_case names with camelCase aliases, and no Spotify OAuth credentials anywhere.
Install and first call
| pip install checkleaked-spotify-api |
Methods return the API's unwrapped data payload; client.request_raw(...) returns the complete envelope. The key may be omitted when SPOTIFY_API_KEY or RAPIDAPI_KEY is set.
What the package does for you
Same surface as the npm package
110 methods in 25 namespaces, snake_case with exact camelCase aliases (spotify.artists.top_tracks and spotify.artists.topTracks both work).
Ids, URIs and URLs interchangeably
Pass a bare id, a spotify: URI or an open.spotify.com URL anywhere an id is expected; multi-id methods take comma-separated strings or sequences. normalize_id and normalize_ids are exported.
Per-call overrides
Every method accepts request_timeout, request_retries, request_headers and an extra_query mapping; POST methods take a free-form body mapping.
Pagination
collect() gathers any offset/limit endpoint up to max_items, with a get_items callable pointing at the page's array.
Typed errors
AuthError, RateLimitError (with retry_after_ms), TimeoutError, HttpError and the SpotifyApiError base class carry status, code and url.
Hooks and debugging
on_request, on_response and on_retry callables plus a debug flag; the client is a context manager.
Providers and errors
| from spotify_api_sdk import ( |
| AuthError, |
| RateLimitError, |
| SpotifyApiClient, |
| SpotifyApiError, |
| ) |
| # RapidAPI is the default; the direct portal exposes the same methods and paths. |
| spotify = SpotifyApiClient( |
| api_key="your-direct-proxy-key", |
| provider="proxy", # rapidapi (default) | proxy |
| timeout=30, |
| retries=2, |
| retry_delay=0.5, |
| ) |
| try: |
| spotify.search.search("daft punk") |
| except RateLimitError as error: |
| print(error.retry_after_ms) |
| except AuthError: |
| print("Invalid or unsubscribed API key") |
| except SpotifyApiError as error: |
| print(error.status, error.code, error.url) |
| # The client is also a context manager |
| with SpotifyApiClient(api_key="...") as spotify: |
| markets = spotify.markets.get() |
Namespaces
One namespace per endpoint group, mirroring the reference. Each links to the group's page with every operation, its parameters and a runnable example.
- spotify.ai24
- spotify.artists10
- spotify.tracking9
- spotify.health8
- spotify.charts6
- spotify.partner6
- spotify.webhooks6
- spotify.batch5
- spotify.browse5
- spotify.concerts5
- spotify.search5
- spotify.tracks4
- spotify.albums3
- spotify.analysis3
- spotify.audiobooks3
- spotify.playlists3
- spotify.shows3
- spotify.cache2
- spotify.credentials2
- spotify.downloads2
- spotify.episodes2
- spotify.lookups2
- spotify.snapshots2
- spotify.users2
- spotify.markets1
FAQ
Does it need Spotify OAuth credentials?
No. It is a data API client that sends one API key header; there is no client id, no token exchange and no refresh loop.
Which Python versions?
3.8 or newer, per the package metadata.
Is this the same API as the RapidAPI spotify81 listing?
Yes. RapidAPI is the default provider and the client adds the x-rapidapi-host header for you; provider="proxy" points the same methods at the direct portal with a key from there.
How do I get the raw envelope with metadata?
Call client.request_raw(...); ordinary methods return the unwrapped data payload.
Is it open source?
MIT-licensed, published on PyPI as checkleaked-spotify-api (1.0.0); the source is on GitHub.
Get a key, then pip install
Free tier on RapidAPI; direct keys from $9 a month.