MusicBrainz API/Search
The Web Service provides a way to search for MusicBrainz Entities, the results are returned in Xml format matching the MMD. The results are provided By a Search Server built using Lucene technology.
This sections lists the parameters common to all resource.
type | Selects the index to be searched, artist, release, release-group, recording, work, label (track is supported but maps to recording) |
query | Lucene search query, this is mandatory |
limit | An integer value defining how many entries should be returned. Only values between 1 and 100 (both inclusive) are allowed. If not given, this defaults to 25. |
offset | Return search results starting at a given offset. Used for paging through more than one page of results. |
The query field supports the full Lucene Search syntax, more details at http://lucene.apache.org/java/3_4_0/queryparsersyntax.html
When searching fields that come from a defined set of possible values such as country and gender find matches where these fields have not been set by searching for unknown.
Example: http://musicbrainz.org/ws/2/release/?query=country:unknown
Artist
The artist index contains the following fields you can search:
field | Description |
alias | the aliases/misspellings/artist credits for this artist |
arid | artist id |
artist | artist name |
begin | artist birth date/band founding date (format: YYYY-MM-DD) |
comment | artist comment to differentiate similar artists |
country | country associated with artist |
end | artist death date/band dissolution date (format: YYYY-MM-DD) |
gender | gender of artist |
ipi | artist ipi code |
sortname | artist sortname |
tag | folksonomy tag |
type | artist type (person or group) |
Artist search terms with no fields specified search the artist, sortname and alias fields.
Example: http://www.musicbrainz.org/ws/2/artist/?query=artist:fred
Xml
<metadata xmlns="http://musicbrainz.org/ns/mmd-2.0#" xmlns:ext="http://musicbrainz.org/ns/ext#-2.0"> <artist-list offset="0" count="1"> <artist type="group" id="8538e728-ca0b-4321-b7e5-cff6565dd4c0" ext:score="100" > <name>Depeche Mode</name> <sort-name>Depeche Mode</sort-name> <life-span> <begin>1980</begin> </life-span> <alias-list> <alias>Depech Mode</alias> </alias-list> </artist> </artist-list> </metadata>
Release Group
The release group index contains these fields you can search:
field | Description |
arid | artist id |
artist | complete artist name(s) as it appears on the release group |
artistname | an artist on the release group, each added as a separate field |
comment | disambuguation comment |
creditname | name credit on the release group, each added as a separate field |
reid | release id of release that is part of this release group |
releasegroup | name of release group |
release | name of release that is part of this release group |
releases | number of releases in this release group |
rgid | release group id |
tag | folksonomy tag |
type | release group type (e.g album) |
Release group search terms with no fields search the releasegroup field only.
Example: http://www.musicbrainz.org/ws/2/release-group/?query=release:fred
Xml
<metadata xmlns="http://musicbrainz.org/ns/mmd-2.0#" xmlns:ext="http://musicbrainz.org/ns/ext#-2.0"> <release-group-list offset="0" count="2"> <release-group type="compilation" id="765675cc-070b-36e0-829c-69c7634e92ff" ext:score="100"> <title>The History of John Fred and the Playboys</title> <artist-credit> <name-credit> <artist id="05cfb5c7-0152-41f4-a9c9-622e8f710dfa"> <name>John Fred & His Playboy Band</name> <sort-name>Fred, John & His Playboy Band</sort-name></artist> </name-credit> </artist-credit> <release-list count="1> <release id="9cddae0c-1764-41d2-a1c4-0af2a8404e57"> <title>The History of John Fred and the Playboys</title> </release> </release-list> </release-group> <release-group type="live" id="9856e177-6a63-3141-96da-00b80d08c66e" ext:score="100" xmlns:ext="http://musicbrainz.org/ns/ext#-2.0"> <title>An Evening With John Kander & Fred Ebb</title> <artist-credit> <name-credit> <artist id="0f1d3e45-b3a4-4a93-b29b-06ee9c6e94a8"><name>John Kander & Fred Ebb</name><sort-name>Kander, John & Ebb, Fred</sort-name></artist> </name-credit> </artist-credit> <release-list count="1> <release id="a204adf8-2bc7-46cf-b4af-b773bf803a89"> <title>An Evening With John Kander & Fred Ebb</title> </release> </release-list> </release-group> </release-group-list> </metadata>
Release
The release index contains these fields you can search:
field | Description |
arid | artist id |
artist | complete artist name(s) as it appears on the release |
artistname | an artist on the release, each artist added as a seperate field |
asin | the Amazon ASIN for this release |
barcode | The barcode of this release |
catno | The catalog number for this release, can have multiples when major using an imprint |
comment | Disambiguation comment |
country | The two letter country code for the release country |
creditname | name credit on the release, each artist added as a seperate field |
date | The release date (format: YYYY-MM-DD) |
discids | total number of cd ids over all mediums for the release |
discidsmedium | number of cd ids for the release on a medium in the release |
format | release format |
label | The name of the label for this release, can have multiples when major using an imprint |
lang | The language for this release. Use the three character ISO 639 codes to search for a specific language. (e.g. lang:eng) |
mediums | number of mediums in the release |
puid | The release contains recordings with these puids |
reid | release id |
release | release name |
rgid | release group id |
script | The 4 character script code (e.g. latn) used for this release |
status | release status (e.g official) |
tracks | total number of tracks over all mediums on the release |
tracksmedium | number of tracks on a medium in the release |
type | release group type (e.g album) |
Release search terms with no fields search the release field only.
Example: http://www.musicbrainz.org/ws/2/release/?query=release:Schneider
Xml
<metadata xmlns="http://musicbrainz.org/ns/mmd-2.0#" xmlns:ext="http://musicbrainz.org/ns/ext#-2.0"> <release-list offset="0" count="1"> <release id="9ab1b03e-6722-4ab8-bc7f-a8722f0d34c1" ext:score="100"> <title>Fred Schneider & The Shake Society</title> <status>official</status> <text-representation> <language>eng</language> <script>latn</script> </text-representation> <artist-credit> <name-credit> <artist id="43bcca8b-9edc-4997-8343-122350e790bf"> <name>Fred Schneider</name> <sort-name>Schneider, Fred</sort-name> </artist> </name-credit> </artist-credit> <release-group type="Album"/> <date>1991-04-30</date> <country>us</country> <barcode>075992659222</barcode> <asin>075992659222</asin> <label-info-list> <label-info> <catalog-number>9 26592-2</catalog-number> <label> <name>Reprise Records</name> </label> </label-info> </label-info-list> <medium-list> <medium><format>cd</format> <disc-list count="2"/> <track-list count="9"/> </medium> </medium-list> </release> </release-list> </metadata>
Recording
Recording searches can contain you can search:
field | Description |
arid | artist id |
artist | artist name is name(s) as it appears on the recording |
artistname | an artist on the recording, each artist added as a seperate field |
creditname | name credit on the recording, each artist added as a seperate field |
comment | recording disambuguation comment |
country | recording release country |
date | recording release date |
dur | duration of track in milliseconds |
format | recording release format |
isrc | ISRC of recording |
position | the medium that the recording should be found on, first medium is position 1 |
qdur | quantized duration (duration / 2000) |
recording | name of recording or a track associated with the recording |
reid | release id |
release | release name |
rid | recording id |
status | Release status (official, promotion, Bootleg, Pseudo-Release) |
tnum | track number on medium |
tracks | number of tracks in the medium on release |
tracksrelease | number of tracks on release as a whole |
type | Release Group type (album, single, ep, compilation, soundtrack, spokenword, interview, audiobook, live, remix, other) |
tag | folksonomy tag |
Recording search terms with no fields search the recording field only
Example: http://www.musicbrainz.org/ws/2/recording/?query=Fred
Xml
<metadata xmlns="http://musicbrainz.org/ns/mmd-2.0#" xmlns:ext="http://musicbrainz.org/ns/ext#-2.0"> <recording-list offset="0" count="1"> <recording id="0b382a13-32f0-4743-9248-ba5536a6115e" ext:score="100"> <title>King Fred</title> <length>160000</length> <artist-credit> <name-credit> <artist id="f52f7a92-d495-4d32-89e7-8b1e5b8541c8"> <name>Too Much Joy</name> <sort-name>Too Much Joy</sort-name> </artist> </name-credit> </artist-credit> <release-list> <release id="8442e42b-c40a-4817-89a0-dbe663c94d2d"> <title>Green Eggs and Crack</title> <release-group type="album"/> <medium-list> <medium> <position>1</position> <track-list offset="13" count="19"> <track> <title>King Fred</title> </track> </track-list> </medium> </medium-list> </release> </release-list> <puid-list> <puid id="1d9e8ed6-3893-4d3b-aa7d-72e79609e386"/> </puid-list> </recording> </recording-list> </metadata>
If the recording belongs to a release that is a Various Artist compilation then the release will show the artist credit to allow differenitation between this and a single artist compilation.
<release id="d9127de1-ec22-4dd2-859b-c326e146fbe5"> <title>Rock Hits</title> <status>Official</status> <artist-credit> <name-credit> <artist id="89ad4ac3-39f7-470e-963a-56509c546377"> <name>Various Artists</name> </artist> </name-credit> </artist-credit> <release-group type="Compilation"/> <medium-list> <track-count>10</track-count> <medium> <position>1</position> <track-list offset="0" count="10"> <track> <title>Jurk</title> </track> </track-list> </medium> </medium-list> </release>
Label
The label index contains the following fields you can search:
field | Description |
alias | the aliases/misspellings for this label |
begin | label founding date |
code | label code (only the figures part, i.e. without "LC") |
comment | label comment to differentiate similar labels |
country | The two letter country code of the label country |
end | label dissolution date |
ipi | ipi |
label | label name |
sortname | label sortname |
type | label type |
tag | folksonomy tag |
Label search terms with no fields specified search the label, sortname and alias fields.
Example: http://www.musicbrainz.org/ws/2/label/?query=Devils
Xml
<metadata xmlns="http://musicbrainz.org/ns/mmd-2.0#" xmlns:ext="http://musicbrainz.org/ns/ext#-2.0"> <label-list offset="0" count="1"> <label type="original production" id="d2c296e3-10a4-4ba9-97b9-5620ff8a3ce0"> <name>Devil's Records</name> <sort-name>Devil's Records</sort-name> <alias-list> <alias>Devils Records</alias> <alias>Devil Records</alias> </alias-list> </label> </label-list> </metadata>
Work
The work index contains these fields you can search:
field | Description |
alias | the aliases/misspellings for this work |
arid | artist id |
artist | artist name, an atist in the context of a work is an artist-work relation such as composer or performer |
comment | disambuguation comment |
iswc | ISWC of work |
tag | folksonomy tag |
type | work type |
wid | work id |
work | name of work |
Work search terms with no fields specified search the work and alias fields.
Example http://www.musicbrainz.org/ws/2/work/?query=Devils
Xml
<metadata xmlns="http://musicbrainz.org/ns/mmd-2.0#" xmlns:ext="http://musicbrainz.org/ns/ext#-2.0"> <work-list offset="0" count="1"> <work ext:score="100" id="10c1a66a-8166-32ec-a00f-540f111ce7a3"> <title>Frozen Fred</title> <relation-list> <relation type="composer"> <artist id="4c006444-ccbf-425e-b3e7-03a98bab5997"> <name>Michiel Peters</name> <sort-name>Peters, Michiel</sort-name> </artist> </relation> </relation-list> </work> </work-list> </metadata>