Chapter 2. Artist Service

Artist(s) by ID

/item/{ids}?appid=...&ratings=...&response=...&callback=...&format=...

GET

Returns detailed metadata for the specified artist(s).

Example: http://us.music.yahooapis.com/artist/v1/item/289282?appid=[yourapplicationidhere]

Responses: “Artist List Response (application/xml - ym:Artists)”

Required Parameters

Parameter	Value	Description
ids	string	Comma-separated list of artist IDs.
appid	string	YDN Application ID. See Application IDs for more information.

Optional Parameters

Parameter	Value	Default / Possible values	Description
ratings	long		Yahoo! Music User ID of the user whose ratings should be returned in the result. Requires BBAuth.
response	string	Any of: releases toptracks topsimilar radio events fans videos categories sorts	Comma-separated list of artist response chunks to return. If `format=rss` , the response parameter is ignored. See “Artist List Response (application/xml - ym:Artists)” for possible values.
callback	string		If output is `json`, wraps the result in the specified callback function.
format	string	xml (default) json	Format of the result.

Artists for a given published list/chart

/list/published/{id}?appid=...&ratings=...&response=...&callback=...&format=...&start=...&count=...&intersectWith=...&flagWith=...&sort=...

GET

Returns artists for a given published artist list. These may include Yahoo!-published charts or editorial lists.

Example: http://us.music.yahooapis.com/artist/v1/list/published/popular?appid=[yourapplicationidhere]

Responses: “Artist List Response (application/xml - ym:Artists)”

Required Parameters

Parameter	Value	Default / Possible values	Description
id	string	popular	Published artist list ID. Possible values are "popular".
appid	string		YDN Application ID. See Application IDs for more information.

Optional Parameters

Parameter	Value	Default / Possible values	Description
ratings	long		Yahoo! Music User ID of the user whose ratings should be returned in the result. Requires BBAuth.
response	string	Any of: releases toptracks topsimilar radio events fans videos categories sorts	Comma-separated list of artist response chunks to return. If `format=rss` , the response parameter is ignored. See “Artist List Response (application/xml - ym:Artists)” for possible values.
callback	string		If output is `json`, wraps the result in the specified callback function.
format	string	xml (default) json rss	Format of the result. `format=rss` is RSS 2.0 feed. These may include Yahoo!-published charts or editorial lists. See “Artist RSS Response (application/xml - rss:rss)” for RSS output. If `format=rss` , the response parameter is ignored.
start	nonNegativeInteger	1	Start index in the list.
count	nonNegativeInteger	25	Max 100. Number of items to return from start.
intersectWith	string	Examples: `%2Flist%2FrecentlyPlayed%2F4596611` `%2Flist%2Fpublished%2Fpopular%3Bcount=20` `%2Flist%2Fsearch%2Fall%2Fmadonna`	A URL-encoded list URI to intersect results with, starting with "/list/". This is the relative URI path of the list. Results will only contain items in both lists.
flagWith	string		A list URI to flag results with (same format as `intersectWith`). If an item also exists in the `flagWith` list, that item will contain a `<FlaggedWith id=[listURI] />` element in the result.
sort	string	Example: `artistName+`	Sort order desired, with '+' or '-' suffix to indicate ascending or descending. For example, `artistName`+ Use `response=sorts` to get the available sort orders for the list

Artists for a category

/list/category/{id}?appid=...&ratings=...&response=...&callback=...&format=...&start=...&count=...&intersectWith=...&flagWith=...&sort=...

GET

Returns artists for a given category. For example, genre, theme and era.

Example: http://us.music.yahooapis.com/artist/v1/list/category/7318647?appid=[yourapplicationidhere]

Responses: “Artist List Response (application/xml - ym:Artists)”

Required Parameters

Parameter	Value	Description
id	string	Category ID
appid	string	YDN Application ID. See Application IDs for more information.

Optional Parameters

Parameter	Value	Default / Possible values	Description
ratings	long		Yahoo! Music User ID of the user whose ratings should be returned in the result. Requires BBAuth.
response	string	Any of: releases toptracks topsimilar radio events fans videos categories sorts	Comma-separated list of artist response chunks to return. For `format=rss` response parameter is ignored. See “Artist List Response (application/xml - ym:Artists)” for possible values.
callback	string		If output is `json`, wraps the result in the specified callback function.
format	string	xml (default) json rss	Format of the result. `format=rss` specifies an RSS 2.0 feed. These may include Yahoo!-published charts or editorial lists. See “Artist RSS Response (application/xml - rss:rss)” for RSS output. If `format=rss` , the response parameter is ignored.
start	nonNegativeInteger	1	Start index in the list.
count	nonNegativeInteger	25	Max 100. Number of items to return from start.
intersectWith	string	Examples: `%2Flist%2FrecentlyPlayed%2F4596611` `%2Flist%2Fpublished%2Fpopular%3Bcount=20` `%2Flist%2Fsearch%2Fall%2Fmadonna`	A URL-encoded list URI to intersect results with, starting with "/list/". This is the relative URI path of the list.
flagWith	string		A list URI to flag results with the same format as `intersectWith`. If an item also exists in the `flagWith` list, that item will contain a `<FlaggedWith id=[listURI] />` element in the result.
sort	string	Example: `artistName+`	Sort order desired, with '+' or '-' suffix to indicate ascending or descending. For example, `artistName+`. Use `response=sorts` to get the available sort orders for the list.

User's recommended artists

/list/recommended/{ymid}?appid=...&category=...&ratings=...&response=...&callback=...&format=...&start=...&count=...&intersectWith=...&flagWith=...&sort=...

GET

Returns the user's recommended artists.

Requires BBAuth for authentication

Example: http://us.music.yahooapis.com/artist/v1/list/recommended/1905196?appid=[yourapplicationidhere]

Responses: “Artist List Response (application/xml - ym:Artists)”

Required Parameters

Parameter	Value	Description
ymid	long	Yahoo! Music User ID
appid	string	YDN Application ID. See Application IDs for more information.

Optional Parameters

Parameter	Value	Default / Possible values	Description
category	int		Category ID with which to filter recommendations
ratings	long		Yahoo! Music User ID of the user whose ratings should be returned in the result. Requires BBAuth.
response	string	Any of: releases toptracks topsimilar radio events fans videos categories sorts	Comma-separated list of artist response chunks to return. For `format=rss` response parameter is ignored. See “Artist List Response (application/xml - ym:Artists)” for possible values.
callback	string		If output is `json`, wraps the result in the specified callback function.
format	string	xml (default) json rss	Format of the result. `format=rss` is RSS 2.0 feed. These may include Yahoo!-published charts or editorial lists. See “Artist RSS Response (application/xml - rss:rss)” for RSS output. For `format=rss` response parameter is ignored.
start	nonNegativeInteger	1	Start index in the list.
count	nonNegativeInteger	25	Max 100. Number of items to return from start.
intersectWith	string	Examples: `%2Flist%2FrecentlyPlayed%2F4596611` `%2Flist%2Fpublished%2Fpopular%3Bcount=20` `%2Flist%2Fsearch%2Fall%2Fmadonna`	A URL-encoded list URI to intersect results with, starting with "/list/". This is the relative URI path of the list.
flagWith	string		A list URI to flag results in same format as `intersectWith`. If an item also exists in the flagWith list, that item will contain a `<FlaggedWith id=[listURI] />` element in the result.
sort	string	Example: `artistName+`	Sort order desired, with '+' or '-' suffix to indicate ascending or descending. For example, `artistName+`. Use `response=sorts` to get the available sort orders for the list.

Similar artists

/list/similar/{id}?appid=...&obscurity=...&ratings=...&response=...&callback=...&format=...&start=...&count=...&intersectWith=...&flagWith=...&sort=...

GET

Returns artists similar to the given artist.

Example: http://us.music.yahooapis.com/artist/v1/list/similar/256352?appid=[yourapplicationidhere]

Responses: “Artist List Response (application/xml - ym:Artists)”

Required Parameters

Parameter	Value	Description
id	int	Artist ID to return similar artists for.
appid	string	YDN Application ID. See Application IDs for more information.

Optional Parameters

Parameter	Value	Default / Possible values	Description
obscurity	string	One of: mainstream default obscure all (default)	Specifies the level of artist obscurity desired.
ratings	long		Yahoo! Music User ID of the user whose ratings should be returned in the result. Requires BBAuth.
response	string	Any of: releases toptracks topsimilar radio events fans videos categories sorts	Comma-separated list of artist response chunks to return. For `format=rss` response parameter is ignored. See “Artist List Response (application/xml - ym:Artists)” for possible values.
callback	string		If output is json, wraps the result in the specified callback function.
format	string	xml (default) json rss	Format of the result. `format=rss` is RSS 2.0 feed. These may include Yahoo!-published charts or editorial lists. See “Artist RSS Response (application/xml - rss:rss)” for RSS output. For `format=rss` response parameter is ignored.
start	nonNegativeInteger	1	Start index in the list.
count	nonNegativeInteger	25	Max 100. Number of items to return from start.
intersectWith	string	Examples: %2Flist%2FrecentlyPlayed%2F4596611 %2Flist%2Fpublished%2Fpopular%3Bcount=20 %2Flist%2Fsearch%2Fall%2Fmadonna	A URL-encoded list URI to intersect results with, starting with "/list/". This is the relative URI path of the list.
flagWith	string		A list URI to flag results with (same format as intersectWith). If an item also exists in the flagWith list, that item will contain a <FlaggedWith id=[listURI] /> element in the result.
sort	string	Example: artistName+	Sort order desired, with '+' or '-' suffix to indicate ascending or descending. Ex: artistName+ Use response=sorts to get the available sort orders for the list

User's rated artists

/list/rated/{ymid}?appid=...&minRating=...&maxRating=...&ratings=...&response=...&callback=...&format=...&start=...&count=...&intersectWith=...&flagWith=...&sort=...

GET

Returns artists that the user has rated.

Requires BBAuth for authentication

Example: http://us.music.yahooapis.com/artist/v1/list/rated/1905196?appid=[yourapplicationidhere]

Responses: “Artist List Response (application/xml - ym:Artists)”

Required Parameters

Parameter	Value	Description
ymid	string	Yahoo music Id.
appid	string	YDN Application ID. See Application IDs for more information.

Optional Parameters

Parameter	Value	Default / Possible values	Description
minRating	int	0	All ratings returned will be equal or higher than this value (0-100).
maxRating	int	100	All ratings returned will be equal or lower than this value (0-100).
ratings	long		Yahoo! Music User ID of the user whose ratings should be returned in the result. Requires BBAuth.
response	string	Any of: releases toptracks topsimilar radio events fans videos categories sorts	Comma-separated list of artist response chunks to return. For `format=rss` response parameter is ignored. See “Artist List Response (application/xml - ym:Artists)” for possible values.
callback	string		If output is json, wraps the result in the specified callback function.
format	string	xml (default) json rss	Format of the result. `format=rss` is RSS 2.0 feed. These may include Yahoo!-published charts or editorial lists. See “Artist RSS Response (application/xml - rss:rss)” for RSS output. For `format=rss` response parameter is ignored.
start	nonNegativeInteger	1	Start index in the list.
count	nonNegativeInteger	25	Max 100. Number of items to return from start.
intersectWith	string	Examples: %2Flist%2FrecentlyPlayed%2F4596611 %2Flist%2Fpublished%2Fpopular%3Bcount=20 %2Flist%2Fsearch%2Fall%2Fmadonna	A URL-encoded list URI to intersect results with, starting with "/list/". This is the relative URI path of the list.
flagWith	string		A list URI to flag results with (same format as intersectWith). If an item also exists in the flagWith list, that item will contain a <FlaggedWith id=[listURI] /> element in the result.
sort	string	Example: artistName+	Sort order desired, with '+' or '-' suffix to indicate ascending or descending. Ex: artistName+ Use response=sorts to get the available sort orders for the list

Search for artists

/list/search/{searchmode}/{keyword}?appid=...&ratings=...&response=...&callback=...&format=...&start=...&count=...&intersectWith=...&flagWith=...&clientid=...&censor=...&spelltoken=...

GET

Returns artists matching a search keyword on a given field.

Example: http://us.music.yahooapis.com/artist/v1/list/search/artist/Madonna?appid=[yourapplicationidhere]

Example: http://wsapi.us.music.yahoo.com/artist/v1/list/search/artist/Madonna

Responses:

Required Parameters

Parameter	Value	Default / Possible values	Description
searchmode	string	One of: artist all (default)	Field to search on.
keyword	string		Keyword to search for (must be properly URL-encoded).
appid	string		YDN Application ID. See Application IDs for more information.

Optional Parameters

Parameter	Value	Default / Possible values	Description
ratings	long		Yahoo! Music User ID of the user whose ratings should be returned in the result. Requires BBAuth.
response	string	Any of: releases toptracks topsimilar radio events fans videos categories sorts	Comma-separated list of artist response chunks to return. For `format=rss` response parameter is ignored. See “Artist List Response (application/xml - ym:Artists)” for possible values.
callback	string		If output is `json`, wraps the result in the specified callback function.
format	string	xml (default) json rss	Format of the result. `format=rss` is RSS 2.0 feed. These may include Yahoo!-published charts or editorial lists. See “Artist RSS Response (application/xml - rss:rss)” for RSS output. For `format=rss` response parameter is ignored.
start	nonNegativeInteger	1	Start index in the list.
count	nonNegativeInteger	25	Max 100. Number of items to return from start.
intersectWith	string	Examples: %2Flist%2FrecentlyPlayed%2F4596611 %2Flist%2Fpublished%2Fpopular%3Bcount=20 %2Flist%2Fsearch%2Fall%2Fmadonna	A URL-encoded list URI to intersect results with, starting with "/list/". This is the relative URI path of the list.
flagWith	string		A list URI to flag results with (same format as intersectWith). If an item also exists in the `flagWith` list, that item will contain a `<FlaggedWith id=[listURI] />` element in the result.
censor	boolean		If 1, returns only 'Family Friendly' results. Otherwise, it returns all results.
spelltoken	string		Spell token only comes into picture when there are spelling suggestions. Spelling token is passed to client when ever there are spelling suggestions. There could be multiple suggestions. When client search for keyword and get back SpellResult. Out of these results client request one of them back. Client needs to pass the "token" as "spelltoken" when firing query with spelling suggestions. Example Client searched for "madona"(/artist/v1/list/search/artist/madona). As this is a incorrect spelling client gets back the SpellResult and attribute token="n-839755038_q-M.qxPBEeiZrVMvYwKwTLIAAAAA@@". Out of these suggestions client select "madonna" as correct spelling suggestion. It must pass token, for example`/artist/v1/list/search/artist/madonna?spelltoken=n-839755038_qM.qxPBEeiZrVMvYwKwTLIAAAAA@@`

Yahoo! Music API Guide