MusicBrainz API/Examples: Difference between revisions
No edit summary |
|||
Line 16: | Line 16: | ||
<code> |
<code> |
||
{ |
{ |
||
"id": "5b11f4ce-a62d-471e-81fc-a69a8278c7da" |
|||
"artist": { |
|||
"name": "Nirvana", |
|||
"id": "5b11f4ce-a62d-471e-81fc-a69a8278c7da" |
|||
"sort-name": "Nirvana" |
|||
"type": "Group", |
|||
"country": "US", |
|||
"disambiguation": "90s US grunge band", |
|||
"life-span": { |
|||
"disambiguation": "90s US grunge band", |
|||
" |
"ended": true, |
||
"begin": "1988-02", |
|||
"end": "1994-04-05" |
|||
}, |
|||
"end": "1994-04-05" |
|||
"aliases": { "name": "Nirvana US", "sort-name": "Nirvana US" }, |
|||
}, |
|||
"aliases": { "name": "Nirvana US", "sort-name": "Nirvana US" }, |
|||
} |
|||
} |
} |
||
</code> |
</code> |
||
Line 38: | Line 36: | ||
<code> |
<code> |
||
{ |
{ |
||
"id": "05cbaf37-6dc2-4f71-a0ce-d633447d90c3", |
|||
"artist": { |
|||
"name": "\u6771\u65b9\u795e\u8d77", |
|||
"sort-name": "TVXQ", |
|||
"type": "Group", |
|||
" |
"life-span": { "ended": false, "begin": "2003" }, |
||
"aliases": [ |
|||
" |
{ "name": "DBSK", "sort-name": "DBSK" }, |
||
{ "name": "Tohoshinki", "sort-name": "Tohoshinki", "locale": "ja", "primary": true }, |
|||
"begin": "2003" |
|||
{ "name": "\ub3d9\ubc29\uc2e0\uae30", "sort-name": "\ub3d9\ubc29\uc2e0\uae30", "locale": "ko_KR", "primary": true } |
|||
}, |
|||
], |
|||
"tags": [ |
|||
{ "name": "DBSK", "sort-name": "DBSK" }, |
|||
{ "count": 1, "name": "kpop" }, |
|||
{ "count": 1, "name": "jpop" }, |
|||
{ "count": 1, "name": "cpop" } |
|||
], |
|||
"rating": { "votes-count": 8, "value": 3.9 } |
|||
{ "count": 1, "name": "jpop" }, |
|||
{ "count": 1, "name": "cpop" } |
|||
], |
|||
"rating": { "votes-count": 8, "value": 3.9 } |
|||
} |
|||
} |
} |
||
</code> |
</code> |
||
Line 69: | Line 62: | ||
<code> |
<code> |
||
{ |
{ |
||
"id": "46f0f4cd-8aab-4b33-b698-f459faf64190", |
|||
"label": { |
|||
"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" } ] |
||
"ended": false, |
|||
"begin": "1989" |
|||
}, |
|||
"tags": [ { "count": 2, "name": "electronic" } ] |
|||
} |
|||
} |
} |
||
</code> |
</code> |
||
Line 90: | Line 78: | ||
<code> |
<code> |
||
{ |
{ |
||
"id": "f49e877d-df8d-4a28-bbe1-689d12fc7d91" |
|||
"label": { |
|||
"name": "AVEX ENTERTAINMENT INC.", |
|||
"id": "f49e877d-df8d-4a28-bbe1-689d12fc7d91" |
|||
"sort-name": "AVEX ENTERTAINMENT INC.", |
|||
"type": "Production", |
|||
"country": "JP", |
|||
"disambiguation": "avex's Japanese music production", |
|||
"country": "JP", |
|||
"life-span": { "ended": false }, |
|||
"disambiguation": "avex's Japanese music production", |
|||
"aliases": [ |
|||
{ "name": "AVEX MARKETING", "sort-name": "AVEX MARKETING" }, |
|||
"aliases": [ |
|||
{ "name": "avex marketing", "sort-name": "avex marketing" }, |
|||
{ |
|||
{ "name": "avex marketing", "sort-name": "avex marketing" }, |
|||
"name": "\u30a8\u30a4\u30d9\u30c3\u30af\u30b9\u30fb\u30a8\u30f3\u30bf\u30c6\u30a4\u30f3\u30e1\u30f3\u30c8", |
|||
{ |
|||
"sort-name": "\u30a8\u30a4\u30d9\u30c3\u30af\u30b9\u30fb\u30a8\u30f3\u30bf\u30c6\u30a4\u30f3\u30e1\u30f3\u30c8" |
|||
} |
|||
"sort-name": "\u30a8\u30a4\u30d9\u30c3\u30af\u30b9\u30fb\u30a8\u30f3\u30bf\u30c6\u30a4\u30f3\u30e1\u30f3\u30c8" |
|||
] |
|||
] |
|||
} |
|||
} |
} |
||
</code> |
</code> |
||
Line 117: | Line 103: | ||
<code> |
<code> |
||
{ |
{ |
||
"id": "fcbcdc39-8851-4efc-a02a-ab0e13be224f", |
|||
"recording": { |
|||
"title": "LAST ANGEL" |
|||
"id": "fcbcdc39-8851-4efc-a02a-ab0e13be224f", |
|||
"disambiguation": "video" |
|||
"artist-credit": [ |
|||
{ |
|||
"name": "\u6771\u65b9\u795e\u8d77", |
|||
"joinphrase": " feat. ", |
|||
"artist": { |
|||
" |
"id": "455641ea-fff4-49f6-8fb4-49f961d8f1ac", |
||
"name": "\u6771\u65b9\u795e\u8d77", |
|||
"sort-name": "Koda, Kumi" |
|||
} |
|||
}, |
|||
{ |
|||
"name": "\u5016\u7530\u4f86\u672a", |
|||
"artist": { |
|||
" |
"id": "05cbaf37-6dc2-4f71-a0ce-d633447d90c3", |
||
"name": "\u5016\u7530\u4f86\u672a", |
|||
"sort-name": "TVXQ" |
|||
} |
|||
} |
|||
], |
|||
], |
"isrcs": [ "JPB600760301" ], |
||
"length": 228106, |
|||
"releases": [ |
|||
{ |
|||
"id": "abcd76db-7d5f-3eb7-b386-051c97bfe2e4", |
|||
"title": "Kingdom", |
|||
/* some properties omitted to keep this example shorter. */ |
|||
} |
|||
/* some properties omitted to keep this example shorter. */ |
|||
], |
|||
], |
|||
} |
|||
} |
} |
||
</code> |
</code> |
||
Line 160: | Line 144: | ||
<code> |
<code> |
||
{ |
{ |
||
"id": "59211ea4-ffd2-4ad9-9a4e-941d3148024a", |
|||
"release": { |
|||
"title": "\u00e6\u00b3o & h\u00b3\u00e6", |
|||
"date": "2003-12-04", |
|||
" |
"text-representation": { "language": "eng", "script": "Latn" }, |
||
"country": "GB", |
|||
"text-representation": { "language": "eng", "script": "Latn" }, |
|||
"status": "Official", |
|||
"release-group": { |
|||
"id": "bb5622c1-65b2-3bc4-83e6-0dcaa56abaf2", |
|||
"release-group": { |
|||
"primary-type": "EP" |
|||
}, |
|||
"primary-type": "EP" |
|||
"artist-credit": [ |
|||
{ |
|||
"joinphrase": " & ", |
|||
"name": "Autechre", |
|||
"artist": { |
|||
" |
"id": "410c9baf-5469-44f6-9852-826524b80c61", |
||
"name": "Autechre", |
|||
"sort-name": "Autechre" |
|||
} |
|||
}, |
|||
{ |
|||
"name": "The Hafler Trio", |
|||
"artist": { |
|||
" |
"id": "146c01d0-d3a2-44c3-acb5-9208bce75e14", |
||
"sort-name": "Hafler Trio, The", |
|||
"name": "The Hafler Trio" |
|||
} |
|||
} |
|||
], |
|||
"labels": [ |
|||
{ |
|||
{ |
"label": { |
||
" |
"id": "a0759efa-f583-49ea-9a8d-d5bbce55541c", |
||
"name": "Phonometrography" |
|||
}, |
|||
"catalog-number": "pgram002" |
|||
} |
|||
], |
|||
"media": [ |
|||
{ |
|||
"title": "\u00e6\u00b3o", |
|||
"format": "CD", |
|||
"discids": [ |
|||
" |
{ "id": "nN2g3a0ZSjovyIgK3bJl6_.j8C4-", "sectors": 73241 } |
||
], |
|||
{ "id": "nN2g3a0ZSjovyIgK3bJl6_.j8C4-", "sectors": 73241 } |
|||
"tracks": [ |
|||
{ |
|||
"number": "1", |
|||
"length": 974546, |
|||
"title": "\u00e6\u00b3o", |
|||
"recording": { /* recording data omitted for this example. */ }, |
|||
"artist-credit": [ /* as on release, not repeated in this example. */ ] |
|||
} |
|||
"artist-credit": [ /* as on release, not repeated in this example. */ ] |
|||
] |
|||
}, |
|||
{ |
|||
"title": "h\u00b3\u00e6", |
|||
"format": "CD", |
|||
"discids": [ |
|||
" |
{ "id": "aSHvkMnq2jZVFEK.DmSPbvN_f54-", "sectors": 69341 } |
||
], |
|||
{ "id": "aSHvkMnq2jZVFEK.DmSPbvN_f54-", "sectors": 69341 } |
|||
"tracks": [ |
|||
{ |
|||
"number": "1", |
|||
"length": 922546, |
|||
"title": "h\u00b3\u00e6", |
|||
"recording": { /* recording data omitted for this example. */ }, |
|||
"artist-credit": [ /* as on release, not repeated in this example. */ ] |
|||
} |
|||
"artist-credit": [ /* as on release, not repeated in this example. */ ] |
|||
] |
|||
} |
|||
] |
|||
] |
|||
} |
|||
} |
} |
||
</code> |
</code> |
||
Line 244: | Line 226: | ||
<code> |
<code> |
||
{ |
{ |
||
"id": "c9fdb94c-4975-4ed6-a96f-ef6d80bb7738", |
|||
"release-group": { |
|||
"title": "The Lost Tape", |
|||
"artist-credit": [ |
|||
" |
"name": "50 Cent", |
||
"artist": { |
|||
" |
"id": "8e68819d-71be-4e7d-b41d-f1df81b01d3f", |
||
"name": "50 Cent" |
|||
"sort-name": "50 Cent", |
|||
} |
|||
], |
|||
"primary-type": "Album", |
|||
"secondary-type": [ "Mixtape/Street" ], |
|||
"releases": [ |
|||
{ |
|||
"id": "2ec84eb6-ab92-4ac3-9720-32ad84c34f11", |
|||
"title": "The Lost Tape", |
|||
/* some properties omitted to keep this example shorter. */ |
|||
} |
|||
/* some properties omitted to keep this example shorter. */ |
|||
] |
|||
] |
|||
} |
|||
} |
} |
||
</code> |
</code> |
||
Line 271: | Line 251: | ||
Request: http://musicbrainz.org/ws/2/work/b1df2cf3-69a9-3bc0-be44-f71e79b27a22<br /> |
Request: http://musicbrainz.org/ws/2/work/b1df2cf3-69a9-3bc0-be44-f71e79b27a22<br /> |
||
Response: |
Response: |
||
<code> |
<code> |
||
{ |
{ |
||
"id": "b1df2cf3-69a9-3bc0-be44-f71e79b27a22", |
|||
"work": { |
|||
"title": "HELLO! \u307e\u305f\u4f1a\u304a\u3046\u306d", |
|||
"id": "b1df2cf3-69a9-3bc0-be44-f71e79b27a22", |
|||
"language": "jpn", |
|||
"title": "HELLO! \u307e\u305f\u4f1a\u304a\u3046\u306d", |
|||
"iswcs": [ "T-101.690.320-9" ] |
|||
"iswcs": [ "T-101.690.320-9" ] |
|||
} |
|||
} |
} |
||
</code> |
</code> |
||
Line 286: | Line 264: | ||
==Browse Requests== |
==Browse Requests== |
||
Browse requests return a toplevel object with offset and count properties to |
|||
Request: http://musicbrainz.org/ws/2/release?label=47e718e1-7ee4-460c-b1cc-1192a841c6e5<br /> |
|||
help with paging, and a property for the requested entity. |
|||
Response: |
|||
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<br /> |
|||
Response: |
|||
<code> |
<code> |
||
{ |
{ |
||
"releases": [ |
"releases": [ |
||
{ |
{ |
||
"id": " |
"id": "0b405ea7-8785-402f-bcf7-d55f5000dc3e", |
||
"title": " |
"title": "Wintertunes" |
||
/* some properties omitted to keep this example shorter. */ |
/* some properties omitted to keep this example shorter. */ |
||
}, |
}, |
||
Line 302: | Line 286: | ||
/* some properties omitted to keep this example shorter. */ |
/* some properties omitted to keep this example shorter. */ |
||
} |
} |
||
], |
|||
/* many releases omitted to keep this example shorter. */ |
|||
"offset": 12, |
|||
"count": 48 |
|||
} |
} |
||
</code> |
Revision as of 09:02, 6 July 2012
This document describes the proposed JSON output, using example queries and the responses I am proposing. Getting a JSON response will require setting the Accept header to "application/json".
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.
Some of the responses below have some fields omitted to keep the examples shorter, in the actual webservice obviously this data will be included.
Lookup requests
Artist
Request: http://musicbrainz.org/ws/2/artist/5b11f4ce-a62d-471e-81fc-a69a8278c7da?inc=aliases
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
Response:
{
"id": "05cbaf37-6dc2-4f71-a0ce-d633447d90c3",
"name": "\u6771\u65b9\u795e\u8d77",
"sort-name": "TVXQ",
"type": "Group",
"life-span": { "ended": false, "begin": "2003" },
"aliases": [
{ "name": "DBSK", "sort-name": "DBSK" },
{ "name": "Tohoshinki", "sort-name": "Tohoshinki", "locale": "ja", "primary": true },
{ "name": "\ub3d9\ubc29\uc2e0\uae30", "sort-name": "\ub3d9\ubc29\uc2e0\uae30", "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
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" } ]
}
Request: http://musicbrainz.org/ws/2/label/f49e877d-df8d-4a28-bbe1-689d12fc7d91?inc=aliases
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": "\u30a8\u30a4\u30d9\u30c3\u30af\u30b9\u30fb\u30a8\u30f3\u30bf\u30c6\u30a4\u30f3\u30e1\u30f3\u30c8",
"sort-name": "\u30a8\u30a4\u30d9\u30c3\u30af\u30b9\u30fb\u30a8\u30f3\u30bf\u30c6\u30a4\u30f3\u30e1\u30f3\u30c8"
}
]
}
Recording
Request: http://musicbrainz.org/ws/2/recording/fcbcdc39-8851-4efc-a02a-ab0e13be224f?inc=artist-credits+isrcs+releases
Response:
{
"id": "fcbcdc39-8851-4efc-a02a-ab0e13be224f",
"title": "LAST ANGEL"
"disambiguation": "video"
"artist-credit": [
{
"name": "\u6771\u65b9\u795e\u8d77",
"joinphrase": " feat. ",
"artist": {
"id": "455641ea-fff4-49f6-8fb4-49f961d8f1ac",
"name": "\u6771\u65b9\u795e\u8d77",
"sort-name": "Koda, Kumi"
}
},
{
"name": "\u5016\u7530\u4f86\u672a",
"artist": {
"id": "05cbaf37-6dc2-4f71-a0ce-d633447d90c3",
"name": "\u5016\u7530\u4f86\u672a",
"sort-name": "TVXQ"
}
}
],
"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
Response:
{
"id": "59211ea4-ffd2-4ad9-9a4e-941d3148024a",
"title": "\u00e6\u00b3o & h\u00b3\u00e6",
"date": "2003-12-04",
"text-representation": { "language": "eng", "script": "Latn" },
"country": "GB",
"status": "Official",
"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"
}
},
{
"name": "The Hafler Trio",
"artist": {
"id": "146c01d0-d3a2-44c3-acb5-9208bce75e14",
"sort-name": "Hafler Trio, The",
"name": "The Hafler Trio"
}
}
],
"labels": [
{
"label": {
"id": "a0759efa-f583-49ea-9a8d-d5bbce55541c",
"name": "Phonometrography"
},
"catalog-number": "pgram002"
}
],
"media": [
{
"title": "\u00e6\u00b3o",
"format": "CD",
"discids": [
{ "id": "nN2g3a0ZSjovyIgK3bJl6_.j8C4-", "sectors": 73241 }
],
"tracks": [
{
"number": "1",
"length": 974546,
"title": "\u00e6\u00b3o",
"recording": { /* recording data omitted for this example. */ },
"artist-credit": [ /* as on release, not repeated in this example. */ ]
}
]
},
{
"title": "h\u00b3\u00e6",
"format": "CD",
"discids": [
{ "id": "aSHvkMnq2jZVFEK.DmSPbvN_f54-", "sectors": 69341 }
],
"tracks": [
{
"number": "1",
"length": 922546,
"title": "h\u00b3\u00e6",
"recording": { /* recording data omitted for this example. */ },
"artist-credit": [ /* as on release, not repeated in this example. */ ]
}
]
}
]
}
Release Group
Request: http://musicbrainz.org/ws/2/release-group/c9fdb94c-4975-4ed6-a96f-ef6d80bb7738?inc=artist-credits+releases
Response:
{
"id": "c9fdb94c-4975-4ed6-a96f-ef6d80bb7738",
"title": "The Lost Tape",
"artist-credit": [
"name": "50 Cent",
"artist": {
"id": "8e68819d-71be-4e7d-b41d-f1df81b01d3f",
"name": "50 Cent"
"sort-name": "50 Cent",
}
],
"primary-type": "Album",
"secondary-type": [ "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
Response:
{
"id": "b1df2cf3-69a9-3bc0-be44-f71e79b27a22",
"title": "HELLO! \u307e\u305f\u4f1a\u304a\u3046\u306d",
"language": "jpn",
"iswcs": [ "T-101.690.320-9" ]
}
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
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. */
}
],
"offset": 12,
"count": 48
}