MusicBrainz API

From MusicBrainz Wiki
Revision as of 19:23, 7 July 2020 by Reosarevok (talk | contribs)
Jump to navigationJump to search

The API discussed here is an interface to the MusicBrainz Database. It is aimed at developers of media players, CD rippers, taggers, and other applications requiring music metadata. The service's architecture follows the REST design principles. Interaction with the API is done using HTTP and all content is served in a simple but flexible format, be it XML or JSON.

General FAQ

What can I do with the MusicBrainz API?
You can look up information about a particular MusicBrainz entity ("give me info about The Beatles"), browse the data to find entities connected to a particular entity ("show me all releases by The Beatles"), or search for entities matching a specific query ("show me all artists matching the query 'Beatles' so I can find the one I want and ask for more data").
Who can use the MusicBrainz API? Is it free?
Non-commercial use of this web service is free; please see our commercial plans or contact us if you would like to use this service commercially.
Do I need an API key?
Currently, no. But you must have a meaningful user-agent string.
Do I need to provide authentication?
Data submission, as well as requests that involve user information, require digest authentication.
Which formats can I get the data in?
The API was originally written to return XML, but nowadays it can also return JSON.
Is there any significant difference between the XML and JSON APIs?
For requesting data, the XML and JSON API are effectively equivalent. The XML API is the only one that allows submitting data to MusicBrainz (but keep in mind only ratings, tags, barcodes and ISRCs can be submitted via the API at all; for most data additions you should use the website instead).
Is there a limit to the number of requests I can make per second?
Yes. See our rate limiting rules.
This seems very complicated, can I see some examples?
Yes, we have an example page showcasing some queries and showing the returned format you can expect for each.
Are there language bindings for the API?
Yes, in many different languages. See our list of external libraries.
What should I do if I encounter unexpected behaviour not covered in these docs?
You can ask question in IRC or in the forums.
Check to see if a ticket has been filed in the bug tracker, and if not consider writing one.
What else should I know before I start using the API?
It'd probably be helpful to know:
So you're on version 2 of the API then? What happened to version 1?
The version 1 of the API was designed with the data structure of the original (pre-2011) version of the MusicBrainz database in mind. It was deprecated in 2011 when we changed to our current data schema, and after running (without further updates) for several years to avoid breaking any tools using it, it was finally taken down in 2019.
Do you ever make breaking changes?
We try to avoid that, but sometimes we might need to do so. In those cases, they will be announced on our blog, so consider following that!

Introduction

The API root URL is https://musicbrainz.org/ws/2/.

We have 13 resources on our API which represent core entities in our database:

 area, artist, event, genre, instrument, label, place, recording, release, release-group, series, work, url

We also provide an API interface for the following non-core resources:

 rating, tag, collection

And we allow you to perform lookups based on other unique identifiers with these resources:

 discid, isrc, iswc

On each entity resource, you can perform three different GET requests:

 lookup:   /<ENTITY_TYPE>/<MBID>?inc=<INC>
 browse:   /<RESULT_ENTITY_TYPE>?<BROWSING_ENTITY_TYPE>=<MBID>&limit=<LIMIT>&offset=<OFFSET>&inc=<INC>
 search:   /<ENTITY_TYPE>?query=<QUERY>&limit=<LIMIT>&offset=<OFFSET>

... except that browse and search are not implemented for genre entities at this time.

Of these:

  • Lookups, non-MBID lookups and browse requests are documented in following sections.
  • Searches are more complex and are documented on the search documentation page.

Lookups

You can perform a lookup of an entity when you have the MBID for that entity:

 lookup:   /<ENTITY_TYPE>/<MBID>?inc=<INC>

Note that unless you have provided an MBID in exactly the format listed, you are not performing a lookup request. If your URL includes something like artist=<MBID>, then please see the Browse section. If it includes query=<QUERY>, please see the Search page.

Subqueries

The inc= parameter allows you to request more information to be included about the entity. Any of the entities directly linked to the entity can be included.

 /ws/2/area
 /ws/2/artist            recordings, releases, release-groups, works
 /ws/2/collection        user-collections (includes private collections, requires authentication)
 /ws/2/event
 /ws/2/genre
 /ws/2/instrument
 /ws/2/label             releases
 /ws/2/place
 /ws/2/recording         artists, releases, isrcs, url-rels
 /ws/2/release           artists, collections, labels, recordings, release-groups
 /ws/2/release-group     artists, releases
 /ws/2/series
 /ws/2/work
 /ws/2/url

In addition, Relationships are available for all entity types except genres via inc parameters.

To include more than one subquery in a single request, separate the arguments to inc= with a + (plus sign), like inc=recordings+labels.

All lookups which include release-groups allow a type= argument to filter the release-groups by a specific type. All lookups which include releases also allow the type= argument, and a status= argument is allowed.

Note that the number of linked entities returned is always limited to 25. If you need the remaining results, you will have to perform a browse request.

Linked entities are always ordered alphabetically by gid.

Note Note: In the XML API, when including recordings with a release entity, tracks listed in media have no title if that doesn’t differ from recording’s title, to reduce the size of the response.

inc= arguments which affect subqueries

Some additional inc= parameters are supported to specify how much of the data about the linked entities should be included:

 - discids           include discids for all media in the releases
 - media             include media for all releases, this includes the # of tracks on each medium and its format.
 - isrcs             include isrcs for all recordings
 - artist-credits    include artists credits for all releases and recordings
 - various-artists   include only those releases where the artist appears on one of the tracks, 
                     but not in the artist credit for the release itself (this is only valid on a
                     /ws/2/artist?inc=releases request).

Misc inc= arguments

 - aliases                   include artist, label, area or work aliases; treat these as a set, as they are not deliberately ordered
 - annotation                include annotation
 - tags, ratings             include tags and/or ratings for the entity
 - user-tags, user-ratings   same as above, but only return the tags and/or ratings submitted by the specified user
 - genres, user-genres       include genres (tags in the genres list): either all or the ones submitted by the user, respectively

Requests with user-tags, user-genres and user-ratings require authentication. You can authenticate using HTTP Digest, use the same username and password used to access the main https://musicbrainz.org website.

Relationships

 - area-rels
 - artist-rels
 - event-rels
 - instrument-rels
 - label-rels
 - place-rels
 - recording-rels
 - release-rels
 - release-group-rels
 - series-rels
 - url-rels
 - work-rels

By default, these 'inc=' arguments will only load relationship for the requested entity. When you are loading a release, you might want to load relationships for all its recordings and also works linked to the recordings. This is useful to get full release credits. There are additional arguments that can be used only on release and (for work-level-rels) recording requests and allow you to specify for which entities to load relationships:

 - recording-level-rels
 - work-level-rels

With relationships included, entities will have <relation-list> nodes for each target entity type. As an example, requesting inc=series-rels for a work might produce the following relation-list as a child of the work:

<relation-list target-type="series">
    <relation type="part of" type-id="b0d44366-cdf0-3acb-bee6-0f65a77a6ef0">
        <target>59c5f4e8-1308-4eff-8845-aa90b92ddc86</target>
        <ordering-key>26</ordering-key>
        <direction>backward</direction>
        <attribute-list>
            <attribute type-id="a59c5830-5ec7-38fe-9a21-c7ea54f6650a" value="op. 26">number</attribute>
        </attribute-list>
        <series id="59c5f4e8-1308-4eff-8845-aa90b92ddc86" type="Catalogue" type-id="49482ff0-fc9e-3b8c-a2d0-30e84d9df002">
            <name>Works of Jean Sibelius by opus number</name>
        </series>
    </relation>
</relation-list>

The <attribute-list> nodes will contain any attributes specified on a relationship. (Here, there's an attribute for the number of the work in a series.) Note that an <attribute> node's text value is the name of the attribute type (here "number"), and the 'type-id' XML attribute (conflicting terminology!) is the UUID of the relationship attribute type ("number"). Relationship attributes always have a type, and some may have an associated value ("op. 26" here). They may also have a 'credited-as' XML attribute indicating a user-entered name. As an example, the attribute below specifies that the piano being played was a Steinway.

<attribute-list>
    <attribute credited-as="Steinway piano" type-id="b3eac5f9-7859-4416-ac39-7154e2e8d348">piano</attribute>
</attribute-list>

Non-MBID Lookups

Instead of MBIDs, you can also perform lookups using several other unique identifiers. However, because clashes sometimes occur, each of these lookups return a list of entities (there is no limit, all linked entities will be returned, paging is not supported).

discid

 lookup: /discid/<discid>?inc=<INC>&toc=<TOC>

A discid lookup returns a list of associated releases, the 'inc=' arguments supported are identical to a lookup request for a release.

If there are no matching releases in MusicBrainz, but a matching CD stub exists, it will be returned. This is the default behaviour. If you do not want to see CD stubs, pass 'cdstubs=no.' CD stubs are contained within a <cdstub> element, and otherwise have the same form as a release. Note that CD stubs do not have artist credits, just artists.

If you provide the "toc" query parameter, and if the provided disc ID is not known by MusicBrainz, a fuzzy lookup will done to find matching MusicBrainz releases. Note that if CD stubs are found this will not happen. If you do want TOC fuzzy lookup, but not CD stub searching, specify "cdstubs=no". For example:

  /ws/2/discid/I5l9cCSFccLKFEKS.7wqSZAorPU-?toc=1+12+267257+150+22767+41887+58317+72102+91375+104652+115380+132165+143932+159870+174597

Will look for the disc id first, and if it fails, will try to find tracklists that are within a similar distance to the one provided.

It's also possible to perform a fuzzy TOC search without a discid. Passing "-" (or any invalid placeholder) as the discid will cause it to be ignored if a valid TOC is present:

  /ws/2/discid/-?toc=1+12+267257+150+22767+41887+58317+72102+91375+104652+115380+132165+143932+159870+174597

By default, fuzzy TOC searches only return mediums whose format is set to "CD." If you want to search all mediums regardless of format, add 'media-format=all' to the query:

  /ws/2/discid/-?toc=1+12+267257+150+22767+41887+58317+72102+91375+104652+115380+132165+143932+159870+174597&media-format=all

The TOC consists of the following:

  • First track (always 1)
  • total number of tracks
  • sector offset of the leadout (end of the disc)
  • a list of sector offsets for each track, beginning with track 1 (generally 150 sectors)

isrc

 lookup: /isrc/<isrc>?inc=<INC>

An isrc lookup returns a list of recordings, the 'inc=' arguments supported are identical to a lookup request for a recording.

iswc

 lookup: /iswc/<iswc>?inc=<INC>

An iswc lookup returns a list of works, the 'inc=' arguments supported are identical to a lookup request for a work.