sonovault 1.0.0

Python client for the SonoVault music metadata API — ISRC, ISWC, genre, labels, release dates, and cross-platform IDs for 90M+ tracks.

sonovault

Python client for the SonoVault music metadata API — 90M+ tracks with ISRC, ISWC, genre, record label, canonical release dates, and cross-platform IDs for Spotify, Apple Music, Tidal, Beatport, Discogs, and MusicBrainz, resolved in a single call.

• One key, no OAuth — a single x-api-key header, no approval queue.
• Free tier — 1,000 requests/month, no credit card: get an API key.
• Docs — full API reference at sonovault.now/docs.

Install

pip install sonovault

Python 3.9+.

Quickstart

from sonovault import SonoVault

sv = SonoVault(api_key="YOUR_API_KEY")

# Find a track's ISRC from artist + title
page = sv.tracks.search(artist="Daft Punk", title="One More Time")
track = page["results"][0]
print(track["isrc"])   # "GBDUW0000053"
print(track["genre"], track["releases"][0]["label"]["name"])

# Resolve that ISRC to its ID on every platform
links = sv.tracks.links(isrc=track["isrc"])
for link in links["links"]:
    print(link["source"], link["url"])  # spotify https://open.spotify.com/track/…

# Recording → composition (ISWC), for royalty/publishing workflows
work = sv.tracks.iswc(isrc=track["isrc"])

Bulk resolve

Resolve up to 100 lines — track names, ISRCs, or platform IDs — in one request (great for enriching play logs and library exports):

batch = sv.tracks.resolve(
    input_type="track_name",
    items=[
        {"artist": "Daft Punk", "title": "Harder, Better, Faster, Stronger"},
        {"artist": "Daft Punk", "title": "Around the World"},
    ],
)
for row in batch["results"]:
    print(row["status"], row["track"] and row["track"]["isrc"])

Pagination

List endpoints return {"results": [...], "next_cursor": ...} — pass the cursor back for the next page (next_cursor is None on the last page):

cursor = None
while True:
    page = sv.artists.releases(42, cursor=cursor)
    # …use page["results"]
    cursor = page.get("next_cursor")
    if not cursor:
        break

Error handling

Non-2xx responses raise SonoVaultError:

from sonovault import SonoVaultError

try:
    sv.tracks.browse(genre="House")  # paid-tier endpoint
except SonoVaultError as err:
    print(err.status, err.is_forbidden, err)

Rate-limited responses that carry a Retry-After header are retried automatically (twice by default; configure with max_retries).

API coverage

Namespace	Methods
sv.tracks	search, get, by_isrc, iswc, by_iswc, links, resolve, identify, identify_audio, browse
sv.artists	search, get, releases
sv.labels	search, get, releases, artists
sv.releases	search, get, latest
sv.genres	list
sv.suggestions	submit, list
sv.streams	create, list, get, update, history, report, live, stop
sv.webhooks	create, list, update, delete, test, deliveries

Some endpoints (audio identify, browse, charts, stream monitoring) need a paid tier — see pricing. Everything else works on the free tier.

Related

• SonoVault API docs — full endpoint reference with examples in 8 languages
• sonovault-js — the TypeScript/Node client
• Free ISRC lookup · ISWC lookup — browser tools built on the same API

License

MIT