MusicBrainz

Implementation notes

When to use MusicBrainz

MusicBrainz is the open music metadata database and, more importantly, the ID space the rest of the open music ecosystem is keyed on. Artists, release groups, releases, recordings, works, labels, and the relationships between all of them, with no key and no signup. Use it when you need canonical identity for music entities rather than one vendor's view of them — deduplicating a library, matching a scraped tracklist to real releases, or building anything that will later want cover art, listening history, or audio fingerprinting. The API is deliberately slow and strict because a nonprofit foundation runs it on donated hardware, which makes it a poor fit for per-request user-facing lookups and an excellent fit for a background enrichment job whose results you store permanently. Search uses Lucene syntax, which is genuinely powerful and worth ten minutes of reading before you write your first query rather than after.

Common pitfalls

• A missing or generic User-Agent gets you blocked, not throttled. MusicBrainz requires a header identifying your application with a version and a contact, in the form my-app/1.0 ([email protected]). Default library user agents — python-requests, axios, Go-http-client — are blocked outright, so the very first request from a fresh integration often 403s and people blame their query syntax.
• One request per second per IP, enforced, with no burst allowance worth planning around. Looping over 500 recordings takes eight minutes at minimum. Use the browse endpoints instead — /ws/2/recording?artist=MBID&limit=100 returns 100 linked entities in one call — and use the inc parameter to pull relationships in the same request rather than following them one at a time.
• MBIDs are the entire point. They are the join key for Cover Art Archive (cover art by release MBID), ListenBrainz, AcoustID, and most open music tooling. Store the MBID next to every artist, release, and recording from your first migration, even if you have no use for it yet — retrofitting MBIDs onto a table of free-text artist names later is a fuzzy matching problem, and those never have clean answers.
• The API returns XML by default. Append fmt=json to every request or you will spend your first half hour wondering why the JSON parser is throwing. An Accept header for application/json also works, but the query parameter is what every example uses and it survives proxies and redirects that strip headers.

Quick start (bash)

curl -s -H 'User-Agent: my-app/1.0 ([email protected])' 'https://musicbrainz.org/ws/2/artist?query=artist:Radiohead&fmt=json&limit=1' | jq '.artists[0].id, .artists[0].name'
# that id is the MBID - store it; it joins to Cover Art Archive, ListenBrainz and AcoustID
# 1 req/s enforced: browse 100 releases in one call instead of looping
curl -s -H 'User-Agent: my-app/1.0 ([email protected])' 'https://musicbrainz.org/ws/2/release?artist=a74b1b7f-71a5-4011-9441-d0b5e4122711&limit=100&fmt=json' | jq '.releases | length'

Embed this badge

Add a live status badge to your README, docs, or website.

Markdown

[![MusicBrainz Status](https://api.freeapi.watch/badge/musicbrainz.svg)](https://freeapi.watch/musicbrainz)

HTML

<a href="https://freeapi.watch/musicbrainz"><img src="https://api.freeapi.watch/badge/musicbrainz.svg" alt="MusicBrainz Status"/></a>