MusicBrainz API/Examples: Difference between revisions
Reosarevok (talk | contribs) No edit summary |
Reosarevok (talk | contribs) No edit summary |
||
Line 1: | Line 1: | ||
The main web service is the [[Development/XML Web Service/Version_2|XML Web Service]]. This page is about the (beta) '''JSON''' format of that web service. |
The main web service is the [[Development/XML Web Service/Version_2|XML Web Service]]. This page is about the (beta) '''JSON''' format of that web service. For shared documentation, like the available inc= parameters, do follow the [[Development/XML Web Service/Version_2|info at the XML web service docs]]. To get a JSON response from the web service, you can either set the Accept header to "application/json" or add fmt=json to the query string (if both are set, fmt= takes precedence). |
||
This document describes the proposed JSON output, using example queries and the responses I am proposing. To get a JSON response you can either set the Accept header to "application/json" or add fmt=json to the query string (if both are set, fmt= takes precedence). |
|||
Some notable differences compared to the JSON response currently used internally by the search server: |
|||
# all "-list" elements are replaced with javascript arrays, using an english plural as the key. So { "tag-list": { "tag": [ ... ] } } becomes { "tags": [ ... ] }. |
|||
# the "name-credit" key inside an "artist-credit" is removed. |
|||
⚫ | |||
==Beta== |
==Beta== |
||
WARNING: This web service is available on the production server (musicbrainz.org/ws/2/), but |
WARNING: This web service is available on the production server (musicbrainz.org/ws/2/) and mostly stable, but is still considered a beta, and while we do our best to avoid breaking changes, we may eventually need to make some before officially marking it as stable. If you find any issues, don't hesitate to [[https://tickets.metabrainz.org/secure/Dashboard.jspa open a ticket] or contact us on IRC. |
||
==Lookup requests== |
==Lookup requests== |
||
⚫ | |||
===Artist=== |
===Artist=== |
||
Revision as of 19:18, 5 March 2020
The main web service is the XML Web Service. This page is about the (beta) JSON format of that web service. For shared documentation, like the available inc= parameters, do follow the info at the XML web service docs. To get a JSON response from the web service, you can either set the Accept header to "application/json" or add fmt=json to the query string (if both are set, fmt= takes precedence).
Beta
WARNING: This web service is available on the production server (musicbrainz.org/ws/2/) and mostly stable, but is still considered a beta, and while we do our best to avoid breaking changes, we may eventually need to make some before officially marking it as stable. If you find any issues, don't hesitate to [open a ticket or contact us on IRC.
Lookup requests
Some of the responses below have some fields omitted to keep the examples shorter, in the actual response the data will obviously be included.
Artist
Request: http://musicbrainz.org/ws/2/artist/5b11f4ce-a62d-471e-81fc-a69a8278c7da?inc=aliases&fmt=json
Response:
{
"id": "5b11f4ce-a62d-471e-81fc-a69a8278c7da",
"name": "Nirvana",
"sort-name": "Nirvana"
"type": "Group",
"country": "US",
"disambiguation": "90s US grunge band",
"life-span": {
"ended": true,
"begin": "1988-02",
"end": "1994-04-05"
},
"aliases": [ { "name": "Nirvana US", "sort-name": "Nirvana US" } ]]
}
Request: http://musicbrainz.org/ws/2/artist/05cbaf37-6dc2-4f71-a0ce-d633447d90c3?inc=aliases+tags+ratings&fmt=json
Response:
{
"id": "05cbaf37-6dc2-4f71-a0ce-d633447d90c3",
"name": "東方神起",
"sort-name": "TVXQ",
"country": null,
"disambiguation": null,
"type": "Group",
"life-span": { "ended": false, "begin": "2003" },
"aliases": [
{ "name": "DBSK", "sort-name": "DBSK" },
{ "name": "Tohoshinki", "sort-name": "Tohoshinki", "locale": "ja", "primary": false },
{ "name": "동방신기", "sort-name": "동방신기", "locale": "ko_KR", "primary": true }
],
"tags": [
{ "count": 1, "name": "kpop" },
{ "count": 1, "name": "jpop" },
{ "count": 1, "name": "cpop" }
],
"rating": { "votes-count": 8, "value": 3.9 }
}
Label
Request: http://musicbrainz.org/ws/2/label/46f0f4cd-8aab-4b33-b698-f459faf64190?inc=aliases&fmt=json
Response:
{
"id": "46f0f4cd-8aab-4b33-b698-f459faf64190",
"name": "Warp Records",
"sort-name": "Warp Records",
"label-code": 2070,
"type": "Original Production",
"country": "GB",
"life-span": { "ended": false, "begin": "1989" },
"tags": [ { "count": 2, "name": "electronic" } ],
"disambiguation": null,
}
Request: http://musicbrainz.org/ws/2/label/f49e877d-df8d-4a28-bbe1-689d12fc7d91?inc=aliases&fmt=json
Response:
{
"id": "f49e877d-df8d-4a28-bbe1-689d12fc7d91"
"name": "AVEX ENTERTAINMENT INC.",
"sort-name": "AVEX ENTERTAINMENT INC.",
"type": "Production",
"country": "JP",
"disambiguation": "avex's Japanese music production",
"life-span": { "ended": false },
"aliases": [
{ "name": "AVEX MARKETING", "sort-name": "AVEX MARKETING" },
{ "name": "avex marketing", "sort-name": "avex marketing" },
{
"name": "エイベックス・エンタテインメント",
"sort-name": "エイベックス・エンタテインメント"
}
]
}
Recording
Request: http://musicbrainz.org/ws/2/recording/fcbcdc39-8851-4efc-a02a-ab0e13be224f?inc=artist-credits+isrcs+releases&fmt=json
Response:
{
"id": "fcbcdc39-8851-4efc-a02a-ab0e13be224f",
"title": "LAST ANGEL",
"disambiguation": "video",
"artist-credit": [
{
"name": "倖田來未",
"joinphrase": " feat. ",
"artist": {
"id": "455641ea-fff4-49f6-8fb4-49f961d8f1ac",
"name": "倖田來未",
"sort-name": "Koda, Kumi",
"disambiguation": null
}
},
{
"name": "東方神起",
"artist": {
"id": "05cbaf37-6dc2-4f71-a0ce-d633447d90c3",
"name": "東方神起",
"sort-name": "TVXQ",
"disambiguation": null
},
"joinphrase": ""
}
],
"isrcs": [ "JPB600760301" ],
"length": 228106,
"releases": [
{
"id": "abcd76db-7d5f-3eb7-b386-051c97bfe2e4",
"title": "Kingdom",
/* some properties omitted to keep this example shorter. */
}
]
}
Release
Request: http://musicbrainz.org/ws/2/release/59211ea4-ffd2-4ad9-9a4e-941d3148024a?inc=artist-credits+labels+discids+recordings&fmt=json
Response:
{
"id": "59211ea4-ffd2-4ad9-9a4e-941d3148024a",
"title": "æ³o & h³æ",
"date": "2003-12-04",
"text-representation": { "language": "eng", "script": "Latn" },
"country": "GB",
"status": "Official",
"quality": "normal",
"release-group": {
"id": "bb5622c1-65b2-3bc4-83e6-0dcaa56abaf2",
"primary-type": "EP"
},
"artist-credit": [
{
"joinphrase": " & ",
"name": "Autechre",
"artist": {
"id": "410c9baf-5469-44f6-9852-826524b80c61",
"name": "Autechre",
"sort-name": "Autechre",
"disambiguation": null
}
},
{
"name": "The Hafler Trio",
"joinphrase": "",
"artist": {
"id": "146c01d0-d3a2-44c3-acb5-9208bce75e14",
"sort-name": "Hafler Trio, The",
"name": "The Hafler Trio",
"disambiguation": null
}
}
],
"label-info": [
{
"label": {
"id": "a0759efa-f583-49ea-9a8d-d5bbce55541c",
"name": "Phonometrography",
"sort-name": "Phonometrography",
"label-code": null,
"disambiguation": null
},
"catalog-number": "pgram002"
}
],
"media": [
{
"track-offset": 0,
"track-count": 1,
"title": "æ³o",
"format": "CD",
"discids": [
{ "id": "nN2g3a0ZSjovyIgK3bJl6_.j8C4-", "sectors": 73241 }
],
"tracks": [
{
"number": "1",
"length": 974546,
"title": "æ³o",
"recording": { /* recording data omitted for this example. */ },
"artist-credit": [ /* as on release, not repeated in this example. */ ]
}
]
},
{
"track-offset": 0,
"track-count": 1,
"title": "h³æ",
"format": "CD",
"discids": [
{ "id": "aSHvkMnq2jZVFEK.DmSPbvN_f54-", "sectors": 69341 }
],
"tracks": [
{
"number": "1",
"length": 922546,
"title": "h³æ",
"recording": { /* recording data omitted for this example. */ },
"artist-credit": [ /* as on release, not repeated in this example. */ ]
}
]
}
],
"barcode": null,
"disambiguation": null,
"packaging": null,
"asin": null
}
Release Group
Request: http://musicbrainz.org/ws/2/release-group/c9fdb94c-4975-4ed6-a96f-ef6d80bb7738?inc=artist-credits+releases&fmt=json
Response:
{
"id": "c9fdb94c-4975-4ed6-a96f-ef6d80bb7738",
"first-release-date": "2012-05-22",
"title": "The Lost Tape",
"artist-credit": [
"name": "50 Cent",
"joinphrase": "",
"artist": {
"id": "8e68819d-71be-4e7d-b41d-f1df81b01d3f",
"name": "50 Cent",
"sort-name": "50 Cent",
"disambiguation": null
}
],
"primary-type": "Album",
"disambiguation": null,
"secondary-types": [ "Mixtape/Street" ],
"releases": [
{
"id": "2ec84eb6-ab92-4ac3-9720-32ad84c34f11",
"title": "The Lost Tape",
/* some properties omitted to keep this example shorter. */
}
]
}
Work
Request: http://musicbrainz.org/ws/2/work/b1df2cf3-69a9-3bc0-be44-f71e79b27a22?fmt=json
Response:
{
"id": "b1df2cf3-69a9-3bc0-be44-f71e79b27a22",
"title": "HELLO! また会おうね",
"language": "jpn",
"iswcs": [ "T-101.690.320-9" ]
}
Genre
Request: http://musicbrainz.org/ws/2/genre/f66d7266-eb3d-4ef3-b4d8-b7cd992f918b?fmt=json
Response:
{
disambiguation: "",
name: "crust punk",
id: "f66d7266-eb3d-4ef3-b4d8-b7cd992f918b"
}
Browse Requests
Browse requests return a toplevel object with offset and count properties to help with paging, and a property for the requested entity. The key for this property will be the english plural of the entity, so: artists, labels, recordings, releases, release-groups or works.
Request: http://musicbrainz.org/ws/2/release?label=47e718e1-7ee4-460c-b1cc-1192a841c6e5&offset=12&limit=2&fmt=json
Response:
{
"releases": [
{
"id": "0b405ea7-8785-402f-bcf7-d55f5000dc3e",
"title": "Wintertunes"
/* some properties omitted to keep this example shorter. */
},
{
"id": "7eb37a3a-646d-4501-a373-e9071186b88d",
"title": "Adventure Magic Supreme Journey Music"
/* some properties omitted to keep this example shorter. */
}
],
"release-offset": 12,
"release-count": 48
}
Relationships
Request: http://musicbrainz.org/ws/2/release/275b01eb-8551-47ff-bd6b-2d142b4bf422?inc=url-rels&fmt=json
Response:
{
"id": "275b01eb-8551-47ff-bd6b-2d142b4bf422",
"title": "Kraftwerk Kover Kollection, Volume 1",
"quality": "normal",
"text-representation": { "language": "eng", "script": "Latn" },
"date": "2012",
"relations": [
{
"direction": "backward",
"type": "download for free",
"url": "http://soundcloud.com/strictly/kraftwerk-kover-kollection-vol"
}
],
"country": null,
"status": null,
"barcode": null,
"disambiguation": null,
"packaging": null,
"asin": null
}
Request: http://musicbrainz.org/ws/2/work/b1df2cf3-69a9-3bc0-be44-f71e79b27a22?inc=artist-rels+recording-rels&fmt=json
Response:
{
"id": "b1df2cf3-69a9-3bc0-be44-f71e79b27a22",
"title": "HELLO! また会おうね",
"language": "jpn",
"iswcs": [ "T-101.690.320-9" ],
"relations": [
{
"direction": "backward",
"type": "composer",
"artist": {
"id": "d997d399-355e-4c49-9c7b-75a93d76bc0e",
"name": "つんく♂",
"sort-name": "Tsunku",
"disambiguation": null
}
},
{
"direction": "backward",
"type": "lyricist",
"artist": {
"id": "d997d399-355e-4c49-9c7b-75a93d76bc0e",
"name": "つんく♂",
"sort-name": "Tsunku",
"disambiguation": null
}
},
{
"direction": "backward",
"type": "performance",
"recording": {
"id": "487cac92-eed5-4efa-8563-c9a818079b9a",
"title": "HELLO! また会おうね (7人祭 version)",
"length": 283600,
"disambiguation": null
}
},
{
"type": "performance",
"direction": "backward",
"recording": {
"id": "fd3061c1-cb9a-4698-bc5f-f6e0e6a36272",
"title": "HELLO! また会おうね (20人祭 version)",
"length": 283600,
"disambiguation": "PV"
}
}
]
}