XML Web Service / Version 2 / 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; you can find a detailed guide at Lucene Search Syntax. For example, you can set conditions while searching for a name with the AND operator.
Example: http://www.musicbrainz.org/ws/2/recording?query=%22we%20will%20rock%20you%22%20AND%20arid:0383dadf-2a4e-4d10-a46a-e9e041da8eb3 will find any recordings of "We Will Rock You" by Queen.
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
Most other textual fields can be searched on by looking for value - (need escaping to \-)
Example: http://musicbrainz.org/ws/2/release/?query=format:\-
Numeric count based fields can be searched for by looking for 0
Example: http://musicbrainz.org/ws/2/release-group/?query=releases:0
Contents |
Artist
Example: http://www.musicbrainz.org/ws/2/artist/?query=artist:fred
Search Fields
The artist index contains the following fields you can search:
| Field | Description |
|---|---|
| arid | MBID of the artist |
| artist | name of the artist |
| artistaccent | name of the artist with any accent characters retained |
| alias | the aliases/misspellings for the artist |
| begin | artist birth date/band founding date |
| comment | artist comment to differentiate similar artists |
| country | the two letter country code for the artist country or 'unknown' |
| end | artist death date/band dissolution date |
| ended | true if know ended even if do not know end date |
| gender | gender of the artist (“male”, “female”, “other”) |
| ipi | IPI code for the artist |
| sortname | artist sortname |
| tag | a tag applied to the artist |
| type | artist type (“person”, “group”, "other" or “unknown”) |
Artist search terms with no fields specified search the artist, sortname and alias fields.
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
Example: http://www.musicbrainz.org/ws/2/release-group/?query=release:Tenance
Search Fields
The release group index contains the following fields you can search:
| Field | Description |
|---|---|
| arid | MBID of the release group’s artist |
| artist | release group artist as it appears on the cover (Artist Credit) |
| artistname | “real name” of any artist that is included in the release group’s artist credit |
| comment | release group comment to differentiate similar release groups |
| creditname | name of any artist in multi-artist credits, as it appears on the cover. |
| primarytype | primary type of the release group (album, single, ep, other) |
| rgid | MBID of the release group |
| releasegroup | name of the release group |
| releasegroupaccent | name of the releasegroup with any accent characters retained |
| releases | number of releases in this release group |
| release | name of a release that appears in the release group |
| reid | MBID of a release that appears in the release group |
| secondarytype | secondary type of the release group (audiobook, compilation, interview, live, remix soundtrack, spokenword) |
| status | status of a release that appears within the release group |
| tag | a tag that appears on the release group |
| type | type of the release group, old type mapping for when we did not have separate primary and secondary types |
Release group search terms with no fields search the releasegroup field only.
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="1">
<release-group ext:score="100" type="Single" id="70664047-2545-4e46-b75f-4556f2a7b83e">
<title>Main Tenance</title>
<artist-credit>
<name-credit>
<artist id="a8fa58d8-f60b-4b83-be7c-aea1af11596b">
<name>Fred Giannelli</name>
<sort-name>Giannelli, Fred</sort-name>
<disambiguation>US electronic artist</disambiguation>
</artist>
</name-credit>
</artist-credit>
<release-list count="1">
<release id="9168f4cc-a852-4ba5-bf85-602996625651">
<title>Main Tenance</title>
</release>
</release-list>
</release-group>
</release-group-list>
</metadata>
Release
Example: http://www.musicbrainz.org/ws/2/release/?query=release:Schneider
Search Fields
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 |
| primarytype | primary type of the release group (album, single, ep, other) |
| puid | The release contains recordings with these puids |
| reid | release id |
| release | release name |
| releaseaccent | name of the release with any accent characters retained |
| rgid | release group id |
| script | The 4 character script code (e.g. latn) used for this release |
| secondarytype | secondary type of the release group (audiobook, compilation, interview, live, remix soundtrack, spokenword) |
| 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 | type of the release group, old type mapping for when we did not have separate primary and secondary types |
Release search terms with no fields search the release field only.
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
Example: http://www.musicbrainz.org/ws/2/recording/?query=Fred
Search Fields
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 |
| number | free text track number |
| position | the medium that the recording should be found on, first medium is position 1 |
| primarytype | primary type of the release group (album, single, ep, other) |
| puid | PUID of recording |
| qdur | quantized duration (duration / 2000) |
| recording | name of recording or a track associated with the recording |
| recordingaccent | name of the recording with any accent characters retained |
| reid | release id |
| release | release name |
| rgid | release group id |
| rid | recording id |
| secondarytype | secondary type of the release group (audiobook, compilation, interview, live, remix soundtrack, spokenword) |
| 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 |
| tag | folksonomy tag |
| type | type of the release group, old type mapping for when we did not have separate primary and secondary types |
Recording search terms with no fields search the recording field only
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
Example: http://www.musicbrainz.org/ws/2/label/?query=Devils
Search Fields
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 |
| ended | true if know ended even if do not know end date |
| ipi | ipi |
| label | label name |
| labelaccent | name of the label with any accent characters retained |
| sortname | label sortname |
| type | label type |
| tag | folksonomy tag |
Label search terms with no fields specified search the label, sortname and alias fields.
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
Example http://www.musicbrainz.org/ws/2/work/?query=Devils
Search Fields
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 |
| lang | Lyrics language of work |
| tag | folksonomy tag |
| type | work type |
| wid | work id |
| work | name of work |
| workaccent | name of the work with any accent characters retained |
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>