MusicBrainz API/Search

From MusicBrainz Wiki
Jump to navigationJump to 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


Artist

Search Fields

The Artist index contains the following fields you can search

Field Description
alias (part of) any alias attached to the artist (diacritics are ignored)
primary_alias (part of) any primary alias attached to the artist (diacritics are ignored)
area (part of) the name of the artist's main associated area
arid the artist's MBID
artist (part of) the artist's name (diacritics are ignored)
artistaccent (part of) the artist's name (with the specified diacritics)
begin the artist's begin date (e.g. "1980-01-22")
beginarea (part of) the name of the artist's begin area
comment (part of) the artist's disambiguation comment
country the 2-letter code (ISO 3166-1 alpha-2) for the artist's main associated country
end the artist's end date (e.g. "1980-01-22")
endarea (part of) the name of the artist's end area
ended a boolean flag (true/false) indicating whether or not the artist has ended (is dissolved/deceased)
gender the artist's gender (“male”, “female”, “other” or “not applicable”)
ipi an IPI code associated with the artist
isni an ISNI code associated with the artist
sortname (part of) the artist's sort name
tag (part of) a tag attached to the artist
type the artist's type (“person”, “group”, etc.)

If you don't specify a field, the terms will be searched for in the alias, artist and sortname fields.

Xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<metadata created="2017-03-12T16:54:57.165Z" xmlns="http://musicbrainz.org/ns/mmd-2.0#" xmlns:ext="http://musicbrainz.org/ns/ext#-2.0">
  <artist-list count="11" offset="0">
    <artist id="e56fd97e-c18f-4e5e-9b4d-f9fc21b4973f" type="Group" ext:score="100">
      <name>Fred</name>
      <sort-name>Fred</sort-name>
      <country>US</country>
      <area id="489ce91b-6658-3307-9877-795b68554c98">
        <name>United States</name>
        <sort-name>United States</sort-name>
      </area>
      <begin-area id="489ce91b-6658-3307-9877-795b68554c98">
        <name>United States</name>
        <sort-name>United States</sort-name>
      </begin-area>
      <disambiguation>US progressive rock band</disambiguation>
      <life-span>
        <begin>1969</begin>
        <end>1974</end>
        <ended>true</ended>
      </life-span>
    </artist>
    <artist id="4a024fd4-305e-4fea-9d3f-4ec858766e6e" type="Group" ext:score="100">
      <name>Fred</name>
      <sort-name>Fred</sort-name>
      <country>US</country>
      <area id="489ce91b-6658-3307-9877-795b68554c98">
        <name>United States</name>
        <sort-name>United States</sort-name>
      </area>
      <disambiguation>US comic barbershop quartet</disambiguation>
      <life-span>
        <ended>false</ended>
      </life-span>
    </artist>
    <artist id="1065e6e0-b6b3-4224-9121-4502e52b9f9e" type="Group" ext:score="61">
      <name>A Halo Called Fred</name>
      <sort-name>A Halo Called Fred</sort-name>
      <country>US</country>
      <area id="489ce91b-6658-3307-9877-795b68554c98">
        <name>United States</name>
        <sort-name>United States</sort-name>
      </area>
      <life-span>
        <ended>false</ended>
      </life-span>
    </artist>
    <artist id="6c843bf3-a854-47ea-b1cf-ba40675710b7" type="Group" ext:score="61">
      <name>Fred Sherry String Quartet</name>
      <sort-name>Fred Sherry String Quartet</sort-name>
      <country>US</country>
      <area id="489ce91b-6658-3307-9877-795b68554c98">
        <name>United States</name>
        <sort-name>United States</sort-name>
      </area>
      <life-span>
        <ended>false</ended>
      </life-span>
    </artist>
    <artist id="be136e58-ccf5-47f0-a000-6e8d7eb3bae0" type="Group" ext:score="61">
      <name>The Color Fred</name>
      <sort-name>Color Fred, The</sort-name>
      <country>US</country>
      <area id="489ce91b-6658-3307-9877-795b68554c98">
        <name>United States</name>
        <sort-name>United States</sort-name>
      </area>
      <life-span>
        <begin>2003</begin>
        <ended>false</ended>
      </life-span>
    </artist>
    <artist id="2cea1456-daef-4bb1-b63c-4b6df03ebbd5" type="Group" ext:score="61">
      <name>The Fred Hersch Group</name>
      <sort-name>Hersch, Fred, The, Group</sort-name>
      <country>US</country>
      <area id="489ce91b-6658-3307-9877-795b68554c98">
        <name>United States</name>
        <sort-name>United States</sort-name>
      </area>
      <life-span>
        <ended>false</ended>
      </life-span>
    </artist>
    <artist id="28b020fa-d9b8-4d92-805c-54cd1b0197b7" type="Group" ext:score="61">
      <name>Jacob Fred Jazz Odyssey</name>
      <sort-name>Jacob Fred Jazz Odyssey</sort-name>
      <country>US</country>
      <area id="489ce91b-6658-3307-9877-795b68554c98">
        <name>United States</name>
        <sort-name>United States</sort-name>
      </area>
      <life-span>
        <begin>1994</begin>
        <ended>false</ended>
      </life-span>
      <alias-list>
        <alias sort-name="JFJO">JFJO</alias>
      </alias-list>
      <tag-list>
        <tag count="1">
          <name>jazz</name>
        </tag>
        <tag count="1">
          <name>jazz fusion</name>
        </tag>
        <tag count="1">
          <name>free jazz</name>
        </tag>
        <tag count="1">
          <name>oklahoma</name>
        </tag>
        <tag count="1">
          <name>us</name>
        </tag>
        <tag count="1">
          <name>tulsa</name>
        </tag>
      </tag-list>
    </artist>
    <artist id="4a903390-4381-4c32-90d0-803bd4f9ce34" type="Group" ext:score="56">
      <name>Fred Waring & His Pennsylvanians</name>
      <sort-name>Waring, Fred & His Pennsylvanians</sort-name>
      <country>US</country>
      <area id="489ce91b-6658-3307-9877-795b68554c98">
        <name>United States</name>
        <sort-name>United States</sort-name>
      </area>
      <life-span>
        <ended>false</ended>
      </life-span>
      <alias-list>
        <alias sort-name="Fred Waring and the Pennsylvanians">Fred Waring and the Pennsylvanians</alias>
        <alias sort-name="Fred Waring & Pennsylvanians">Fred Waring & Pennsylvanians</alias>
        <alias sort-name="Fred Waring's Pennsylvanians">Fred Waring's Pennsylvanians</alias>
        <alias sort-name="Fred Waring's Pennyslvanians">Fred Waring's Pennyslvanians</alias>
        <alias sort-name="Fred Waring & the Pennsylvanians">Fred Waring & the Pennsylvanians</alias>
        <alias sort-name="Waring, Fred & Pennsylvanians, The">Fred Waring & The Pennsylvanians</alias>
        <alias sort-name="Fred Warring & His Pennsylvanians">Fred Warring & His Pennsylvanians</alias>
        <alias sort-name="Waring's Pensylvanians">Waring's Pensylvanians</alias>
      </alias-list>
    </artist>
    <artist id="0980008b-f9cd-412e-b062-84212b756f4a" type="Group" ext:score="51">
      <name>Fred Williams & The Jewels Band</name>
      <sort-name>Williams, Fred & Jewels Band, The</sort-name>
      <country>US</country>
      <area id="489ce91b-6658-3307-9877-795b68554c98">
        <name>United States</name>
        <sort-name>United States</sort-name>
      </area>
      <life-span>
        <ended>false</ended>
      </life-span>
    </artist>
    <artist id="985bdbe7-ebf2-42b1-8ad6-5bb619385e67" type="Group" ext:score="51">
      <name>Fred Wesley and The J.B.’s</name>
      <sort-name>Wesley, Fred and J.B.’s, the</sort-name>
      <country>US</country>
      <area id="489ce91b-6658-3307-9877-795b68554c98">
        <name>United States</name>
        <sort-name>United States</sort-name>
      </area>
      <life-span>
        <ended>false</ended>
      </life-span>
      <alias-list>
        <alias sort-name="Fred and the New J.B.'s">Fred and the New J.B.'s</alias>
        <alias sort-name="Fred Wesley & The J.B.'s">Fred Wesley & The J.B.'s</alias>
        <alias sort-name="Fred Wesley & The JB's">Fred Wesley & The JB's</alias>
        <alias sort-name="Fred Wesley & The New J.B.'s">Fred Wesley & The New J.B.'s</alias>
        <alias sort-name="Fred Wesley & The New JB's">Fred Wesley & The New JB's</alias>
      </alias-list>
    </artist>
    <artist id="05cfb5c7-0152-41f4-a9c9-622e8f710dfa" type="Group" ext:score="51">
      <name>John Fred & His Playboy Band</name>
      <sort-name>Fred, John & His Playboy Band</sort-name>
      <country>US</country>
      <area id="489ce91b-6658-3307-9877-795b68554c98">
        <name>United States</name>
        <sort-name>United States</sort-name>
      </area>
      <begin-area id="34f02dc4-3173-4c68-86d1-c82504759342">
        <name>Baton Rouge</name>
        <sort-name>Baton Rouge</sort-name>
      </begin-area>
      <life-span>
        <begin>1956</begin>
        <end>1969</end>
        <ended>true</ended>
      </life-span>
      <alias-list>
        <alias sort-name="John Fred">John Fred</alias>
        <alias sort-name="John Fred and His Playboyband">John Fred and His Playboyband</alias>
        <alias sort-name="John Fred and His Play Boy Band">John Fred and His Play Boy Band</alias>
        <alias sort-name="John Fred And His Playboy Band">John Fred And His Playboy Band</alias>
        <alias sort-name="John Fred and His Playboys">John Fred and His Playboys</alias>
        <alias sort-name="John Fred and the Play Boy Band">John Fred and the Play Boy Band</alias>
        <alias sort-name="John Fred and the Playboys">John Fred and the Playboys</alias>
        <alias sort-name="John Fred & His Playboyband">John Fred & His Playboyband</alias>
        <alias sort-name="John Fred & His Playboys">John Fred & His Playboys</alias>
        <alias sort-name="John Fred & Hiss Playboy Band">John Fred & Hiss Playboy Band</alias>
        <alias sort-name="John Fred & Playboyband">John Fred & Playboyband</alias>
        <alias sort-name="John Fred & Playboy Band">John Fred & Playboy Band</alias>
        <alias sort-name="John Fred & the Play Boy Band">John Fred & the Play Boy Band</alias>
        <alias sort-name="John Fred & The Playboyband">John Fred & The Playboyband</alias>
        <alias sort-name="John Fred & The Playboy Band">John Fred & The Playboy Band</alias>
        <alias sort-name="John Fred & The Playboys">John Fred & The Playboys</alias>
      </alias-list>
    </artist>
  </artist-list>
</metadata>

Release Group

Search Fields

The release group index contains the following fields you can search:

Field Description
alias (part of) any alias attached to the release group (diacritics are ignored)
arid the MBID of any of the release group artists
artist (part of) the combined credited artist name for the release group, including join phrases (e.g. "Artist X feat.")
artistname (part of) the name of any of the release group artists
comment (part of) the release group's disambiguation comment
creditname (part of) the credited name of any of the release group artists on this particular release group
firstreleasedate the release date of the earliest release in this release group (e.g. "1980-01-22")
primarytype the primary type of the release group
reid the MBID of any of the releases in the release group
release (part of) the title of any of the releases in the release group
releasegroup (part of) the release group's title (diacritics are ignored)
releasegroupaccent (part of) the release group's title (with the specified diacritics)
releases the number of releases in the release group
rgid the release group's MBID
secondarytype any of the secondary types of the release group
status the status of any of the releases in the release group
tag (part of) a tag attached to the release group
type legacy release group type field that predates the ability to set multiple types (see calculation code)

If you don't specify a field, the terms will be searched for in the releasegroup field.

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>
              <first-release-date>1998</first-release-date>
              <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

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>