Metadata¶

The metadata API looks up MusicBrainz metadata for recordings

GET /1/metadata/recording/¶

This endpoint takes in a list of recording_mbids and returns an array of dicts that contain recording metadata suitable for showing in a context that requires as much detail about a recording and the artist. Using the inc parameter, you can control which portions of metadata to fetch.

The data returned by this endpoint can be seen here:

{
   "e97f805a-ab48-4c52-855e-07049142113d" : {
      "tag" : {
         "recording" : [
            {
               "genre_mbid" : "45eb1d9c-588c-4dc8-9394-a14b7c8f02bc",
               "tag" : "trip hop",
               "count" : 6
            },
            {
               "count" : 1,
               "tag" : "pop",
               "genre_mbid" : "911c7bbb-172d-4df8-9478-dbff4296e791"
            },
            {
               "count" : 1,
               "genre_mbid" : "608b0471-7531-4854-a348-e698c69cb699",
               "tag" : "ambient"
            },
            {
               "count" : 3,
               "tag" : "trip-hop"
            },
            {
               "count" : 1,
               "genre_mbid" : "cc38aba3-48ed-439a-83b9-f81a34a66598",
               "tag" : "downtempo"
            },
            {
               "count" : 3,
               "genre_mbid" : "89255676-1f14-4dd8-bbad-fca839d6aff4",
               "tag" : "electronic"
            },
            {
               "genre_mbid" : "b7864789-29e6-4965-84e4-463baaa869df",
               "tag" : "chanson fran�aise",
               "count" : 1
            },
            {
               "genre_mbid" : "7dc2b20f-3953-4874-b9bf-41b8ba06d20c",
               "tag" : "acid jazz",
               "count" : 1
            }
         ],
         "artist" : [
            {
               "artist_mbid" : "8f6bd1e4-fbe1-4f50-aa9b-94c450ec0f11",
               "tag" : "uk",
               "count" : 1
            },
            {
               "genre_mbid" : "ba318056-9ddf-46cd-8b95-61fc993b962d",
               "artist_mbid" : "8f6bd1e4-fbe1-4f50-aa9b-94c450ec0f11",
               "tag" : "krautrock",
               "count" : 2
            },
            {
               "count" : 4,
               "tag" : "electronic",
               "genre_mbid" : "89255676-1f14-4dd8-bbad-fca839d6aff4",
               "artist_mbid" : "8f6bd1e4-fbe1-4f50-aa9b-94c450ec0f11"
            },
            {
               "count" : 2,
               "artist_mbid" : "8f6bd1e4-fbe1-4f50-aa9b-94c450ec0f11",
               "genre_mbid" : "65c97e89-b42b-45c2-a70e-0eca1b8f0ff7",
               "tag" : "experimental rock"
            },
            {
               "genre_mbid" : "ec5a14c7-7793-46dc-b858-470183eb63f7",
               "artist_mbid" : "8f6bd1e4-fbe1-4f50-aa9b-94c450ec0f11",
               "tag" : "folktronica",
               "count" : 1
            },
            {
               "count" : 8,
               "tag" : "trip hop",
               "genre_mbid" : "45eb1d9c-588c-4dc8-9394-a14b7c8f02bc",
               "artist_mbid" : "8f6bd1e4-fbe1-4f50-aa9b-94c450ec0f11"
            },
            {
               "count" : 3,
               "artist_mbid" : "8f6bd1e4-fbe1-4f50-aa9b-94c450ec0f11",
               "tag" : "british"
            },
            {
               "artist_mbid" : "8f6bd1e4-fbe1-4f50-aa9b-94c450ec0f11",
               "genre_mbid" : "cc38aba3-48ed-439a-83b9-f81a34a66598",
               "tag" : "downtempo",
               "count" : 5
            },
            {
               "tag" : "trip-hop",
               "artist_mbid" : "8f6bd1e4-fbe1-4f50-aa9b-94c450ec0f11",
               "count" : 8
            },
            {
               "count" : 1,
               "tag" : "electro-industrial",
               "artist_mbid" : "8f6bd1e4-fbe1-4f50-aa9b-94c450ec0f11",
               "genre_mbid" : "6e2e809f-8c54-4e0f-aca0-0642771ab3cf"
            }
         ]
      },
      "recording" : {
         "rels" : [
            {
               "artist_name" : "Beth Gibbons",
               "instrument" : null,
               "artist_mbid" : "5adcb9d9-5ea2-428d-af46-ef626966e106",
               "type" : "vocal"
            },
            {
               "artist_mbid" : "5082a11f-7203-4ff3-ae04-2a0150d3bbb6",
               "type" : "instrument",
               "instrument" : "Rhodes piano",
               "artist_name" : "Geoff Barrow"
            },
            {
               "type" : "instrument",
               "artist_mbid" : "619b1116-740e-42e0-bdfe-96af274f79f7",
               "instrument" : "guitar",
               "artist_name" : "Adrian Utley"
            },
            {
               "artist_name" : "Clive Deamer",
               "instrument" : "drums (drum set)",
               "type" : "instrument",
               "artist_mbid" : "d576e6be-03d1-489c-8c3e-692c6fbfb7ca"
            }
         ]
      },
      "release" : {
         "caa_id" : 829521842,
         "mbid" : "76df3287-6cda-33eb-8e9a-044b5e15ffdd"
      },
      "artist" : [
         {
            "rels" : {
               "official homepage" : "http://www.portishead.co.uk/",
               "youtube" : "https://www.youtube.com/channel/UC243a5RnwmItLvwhl0YOxbg",
               "purchase for download" : "https://itunes.apple.com/us/artist/id853090",
               "wikidata" : "https://www.wikidata.org/wiki/Q191352",
               "free streaming" : "https://open.spotify.com/artist/6liAMWkVf5LH7YR9yfFy1Y",
               "social network" : "https://www.facebook.com/portishead",
               "lyrics" : "https://muzikum.eu/en/122-6105/portishead/lyrics.html"
            },
            "begin_year" : 1991,
            "area" : "United Kingdom",
            "type" : "Group"
         }
      ]
   }
}

Parameters

recording_mbids (str) – A comma separated list of recording_mbids
inc (str) – A space separated list of “artist”, “tag” and/or “release” to indicate which portions of metadata you’re interested in fetching. We encourage users to only fetch the data they plan to consume.

Status Codes

200 OK – you have data!
400 Bad Request – invalid recording_mbid arguments

GET /1/metadata/lookup/¶

This endpoint looks up mbid metadata for the given artist and recording name.

Parameters

artist_name (str) – artist name of the listen
recording_name – track name of the listen
metadata (bool) – should extra metadata be also returned if a match is found, see /metadata/recording for details.
inc (str) – same as /metadata/recording endpoint

Status Codes

200 OK – lookup succeeded, does not indicate whether a match was found or not
400 Bad Request – invalid arguments

POST /1/metadata/submit_manual_mapping/¶

Submit a manual mapping of a recording messybrainz ID to a musicbrainz recording id.

The format of the JSON to be POSTed to this endpoint is:

{
    "recording_msid": "d23f4719-9212-49f0-ad08-ddbfbfc50d6f",
    "recording_mbid": "8f3471b5-7e6a-48da-86a9-c1c07a0f47ae"
}

Request Headers

Authorization – Token <user token>
Content-Type – application/json

Status Codes

200 OK – Mapping added, or already exists.
400 Bad Request – invalid JSON sent, see error message for details.
401 Unauthorized – invalid authorization. See error message for details.

Response Headers

Content-Type – application/json

GET /1/metadata/get_manual_mapping/¶

Get the manual mapping of a recording messybrainz ID that a user added.

Request Headers

Authorization – Token <user token>
Content-Type – application/json

Status Codes

200 OK – The response of the mapping.
404 Not Found – No such mapping for this user/recording msid

Response Headers

Content-Type – application/json