MusicBrainz API/Search
This is the output currently returned from the Search Server, this has to match the 2.0 schema. Note this is NOT the webservice but is used by the webservice to perform searches, and is also used by the Web Interface to perform searches. The webservice will return the xml exactly as shown on this page, the webpage will receive a JSON'd version of the XML which it will render as Html.
Some of these entities are currently only returned by the webpage and not the web service, these are annotation, tags, cdstubs and freedb. But it is expected that at least annotations and tags will be added to the web service in future.
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) |
format | Selects the representation of the resource. Defaults to xml, but can also be json (for parsing to html) |
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. |
version | MMD version, defaults to 2, can be set to 1 for backwards compatibility. |
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 searchng 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>
Json
{"artist-list":{"offset":0,"count":1,"artist":[{"type":"group","id":"8538e728-ca0b-4321-b7e5-cff6565dd4c0","score":"100", "name":"Depeche Mode","sort-name":"Depeche Mode","life-span":{"begin":"1980"},"alias-list":{"alias":["Depech Mode"]}}]}}
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>
Json
{"release-group-list":{"offset":0,"count":1,"release-group":[{"type":["compilation"],"id":"765675cc-070b-36e0-829c-69c7634e92ff","score":"100","title" :"The History of John Fred and the Playboys","artist-credit":{"name-credit":[{"artist":{"id":"05cfb5c7-0152-41f4-a9c9-622e8f710dfa","name": "John Fred & His Playboy Band","sort-name":"Fred, John & His Playboy Band"}}]},"release-list":{"count":1,"release":[{"id":"9cddae0c-1764-41d2-a1c4-0af2a8404e57", "title":"The History of John Fred and the Playboys"}]}}]}}
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>
Json
{"release-list":{"offset":0,"count":1,"release":[{"id":"9ab1b03e-6722-4ab8-bc7f-a8722f0d34c1","score":"100","title":"Fred Schneider & The Shake Society","status":"official", "text-representation":{"language":"eng","script":"latn"},"artist-credit":{"name-credit":[{"artist":{"id":"43bcca8b-9edc-4997-8343-122350e790bf","name":"Fred Schneider", "sort-name":"Schneider, Fred"}}]},"release-group":{"type":["album"]},"date":"1991-04-30","country":"us","barcode":"075992659222","asin":"075992659222", "label-info-list":{"label-info":[{"catalog-number":"9 26592-2","label":{"name":"Reprise Records"}}]},"medium-list":{"medium":[{"format":"cd","disc-list":{"count":2}, "track-list":{"count":9}}]}}]}}
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
TODO Add track pos instead of tracklist offset because a recording could match two tracks on the same release, or would it be shown within another release block?
<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>
Json
{"recording-list":{"offset":0,"count":1,"recording":[{"id":"0b382a13-32f0-4743-9248-ba5536a6115e","score":"100","title":"King Fred","length":160000,"artist-credit" :{"name-credit":[{"artist":{"id":"f52f7a92-d495-4d32-89e7-8b1e5b8541c8","name":"Too Much Joy","sort-name":"Too Much Joy"}}]},"release-list":{"release" :[{"id":"8442e42b-c40a-4817-89a0-dbe663c94d2d","title":"Green Eggs and Crack","release-group":{"type":["album"]},"medium-list":{"medium":[{"position":1, "track-list":{"offset":13,"count":19,"track":[{"title":"King Fred"}]}}]}}]}}]}}
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>
Json
{"label-list":{"offset":0,"count":1,"label":[{"type":"original production","id":"d2c296e3-10a4-4ba9-97b9-5620ff8a3ce0","score":"100", "name":"Devil's Records","sort-name":"Devil's Records","alias-list":{"alias":["Devils Records","Devil Records"]}}]}}}
</nowiki>
Work
The work index contains these fields you can search:
field | Description |
wid | work id |
work | name of work |
iswc | ISWC of work |
type | work type |
arid | artist id |
artist | artist name, an atist in the context of a work is an artist-work relation such as composer or performer |
alias | the aliases/misspellings for this work |
tag | folksonomy tag |
Work search terms with no fields specified search the work and alias fields.
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>
Annotation
The annotation index contains the following fields you can search:
field | Description |
entity | musicbrainz id of the entity that this annotation is about |
name | artist name |
text | the annotation itself |
type | the type of entity the annotation relates to (artist, release, label, track, releasegroup) |
Annotation search terms with no fields specified search the text field.
Example: http://localhost:8080/ws/2/annotation/?query=mbid:bdb24cb5-404b-4f60-bba4-7b730325ae47
Xml
<metadata xmlns="http://musicbrainz.org/ns/mmd-2.0#" xmlns:ext="http://musicbrainz.org/ns/ext#-2.0"> <annotation-list offset="0" count="1"> <annotation type="release"> <entity>bdb24cb5-404b-4f60-bba4-7b730325ae47</entity> <text>EAN: 0828768226629 - DiscID: TWj6cLku360MfFYAq_MEaT_stgc-</text> </annotation> </annotation-list> </metadata>
Json
{"annotation-list":{"offset":0,"count":1,"annotation":[{"type":"release","entity":"bdb24cb5-404b-4f60-bba4-7b730325ae47", "text":"EAN: 0828768226629 - DiscID: TWj6cLku360MfFYAq_MEaT_stgc-"}]}}
CdStub
The cdstub index contains these fields you can search:
field | Description |
artist | main artist of the CD |
title | title of the CD |
barcode | barcode of the CD |
comment | comment |
discid | CD discid |
tracks | total tracks on the CD |
CdStub index search terms with no fields search the artist and title fields only.
Example: Doo http://localhost:8080/ws/2/cdstub/?query=title:Doo Doo
Xml
<metadata xmlns="http://musicbrainz.org/ns/mmd-2.0#" xmlns:ext="http://musicbrainz.org/ns/ext#-2.0"> <cdstub-list offset="0" count="1"> <cdstub id="qA87dKURKperVfmckD5b_xo8BO8-"> <title>Doo Doo First</title> <artist>Doo Doo</artist> <barcode>837101029193</barcode> <comment>CD Baby id:vozzolo</comment> <track-list count="2"/> </cdstub> </cdstub-list> </metadata>
Json
{"cdstub-list":{"offset":0,"count":1,"cdstub":[{"id":"qA87dKURKperVfmckD5b_xo8BO8-","title":"Doo Doo First", "artist":"Doo Doo","barcode":"837101029193","comment":"CD Baby id:vozzolo","track-list":{"count":2}}]}}
FreeDB
The FreeDB index contains these fields you can search:
field | Description |
artist | main artist of the this freedb release |
title | title of the freedb release |
discid | disc |
category | category |
year | year of release |
tracks | number of tracks on the release |
FreeDB index search terms with no fields search the artist and title fields only.
Example: http://localhost:8080/ws/2/freedb/?query=artist:Ska-P
Xml
<metadata xmlns="http://musicbrainz.org/ns/mmd-2.0#" xmlns:ext="http://musicbrainz.org/ns/ext#-2.0"> <freedb-disc-list offset="0" count="1"> <freedb-disc id="c20c4b0d"> <title>Lágrimas & Gozos</title> <artist>Ska-P</artist> <category>folk</category> <year>2008</year> <track-list count="13"/> </freedb-disc> </freedb-disc-list> </metadata>
Json
{"freedb-disc-list":{"offset":0,"count":1,"freedb-disc":[{"id":"c20c4b0d","title":"Lágrimas & Gozos","artist":"Ska-P", "category":"folk","year":"2008","track-list":{"count":13}}]}}
Tag
The Tag index contains these fields you can search:
field | Description |
tag | tag |
Example: http://localhost:8080/ws/2/tag?query=tag:rock
Xml
<metadata xmlns="http://musicbrainz.org/ns/mmd-2.0#" xmlns:ext="http://musicbrainz.org/ns/ext#-2.0"> <tag-list offset="0" count="2"> <tag ext:score="100"><name>rock</name></tag> <tag ext:score="62"><name>classic rock</name></tag> </tag-list></metadata>
Json
{"tag-list":{"offset":0,"count":2,"tag":[{"score":"100","name":"rock"},{"score":"62","name":"classic rock"}]}}