Home | Index

Yahoo! Music API Guide

Prev — Responses
Responses — Next

Chapter 8. Track Service

Table of Contents

Services
Track(s) by ID
User's favorite tracks (read)
User's favorite tracks (write)
User's favorite tracks (delete)
Tracks for a given published list/chart
User's recommended tracks
Artist's tracks
Tracks for a category
User's recently played tracks
User's rated tracks
Search for tracks
Responses
Track List Response (application/xml - ym:Tracks)
main
artists
releases
categories
fans
sorts
mappings
videos
Tracks Spelling Response (application/xml - ym:Artists)
SpellResults
Track RSS Response (application/xml - rss:rss)
RSS

Services

Track(s) by ID

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

GET

Returns detailed metadata for the specified track(s).

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

Responses: “Track List Response (application/xml - ym:Tracks)”

Required Parameters

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

Optional Parameters

Parameter Value Default / Possible values Description
catalog int 123 Catalog ID to use for resolving the track IDs. Defaults to using the Yahoo Music catalog ID (123)
ratings long   Yahoo! Music User ID of the user whose ratings should be returned in the result. Requires BBAuth.
response string artists,releases,categories Comma-separated list of track response chunks to return. Default is artists,releases,categories. For format=rss the response parameter is ignored. See “Track List Response (application/xml - ym:Tracks)” 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. See “Track RSS Response (application/xml - rss:rss)” for RSS output. For format=rss, response and verboseLevel parameters are ignored.

User's favorite tracks (read)

/list/favorites/{ymid}/{ids}?appid=...&ratings=...&response=...&callback=...&format=...&start=...&count=...&intersectWith=...&flagWith=...&sort=...&incrementalDate=...&incrementalID=...

GET

Returns the user's favorite tracks (i.e. bookmarks).

Requires BBAuth for authentication

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

Responses: “Track List Response (application/xml - ym:Tracks)”

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
ids string   Comma-separated list of track IDs to be added or deleted. Required for POST and DELETE. May not appear for GET.
ratings long   Yahoo! Music User ID of the user whose ratings should be returned in the result. Requires BBAuth.
response string artists,releases,categories Comma-separated list of track response chunks to return. Default is artists,releases,categories. For format=rss response parameter is ignored. See “Track List Response (application/xml - ym:Tracks)” 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 “Track RSS Response (application/xml - rss:rss)” for RSS output. For format=rss, response and verboseLevel parameters are 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, above. 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
incrementalDate dateTime Example: "2005-12-03T07:35:02Z" Return only results that are newer than this date. Must be a GMT date/time, of the format "yyyy-MM-dd'T'HH:mm:ss'Z'". Example: "2005-12-03T07:35:02Z"
incrementalID int   Requires incrementalDate. ID of the last item retrieved in a previous incremental call. The first item retrieved in this call will be the item immediately following that one.

User's favorite tracks (write)

/list/favorites/{ymid}/{ids}?appid=...

POST

Saves the specified track(s) to the user's favorite tracks.

Requires BBAuth for authentication

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

Required Parameters

Parameter Value Description
ymid long Yahoo! Music User ID
ids string Comma-separated list of track IDs to be added or deleted. Required for POST and DELETE. May not appear for GET.
appid string YDN Application ID. See Application IDs for more information.

User's favorite tracks (delete)

/list/favorites/{ymid}/{ids}?appid=...

DELETE

Deletes the specified track(s) from the user's favorite tracks.

Requires BBAuth for authentication

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

Responses: None

Required Parameters

Parameter Value Description
ymid long Yahoo! Music User ID
ids string Comma-separated list of track IDs to be added or deleted. Required for POST and DELETE. May not appear for GET.
appid string YDN Application ID. See Application IDs for more information.

Tracks for a given published list/chart

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

GET

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

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

Responses: “Track List Response (application/xml - ym:Tracks)”

Required Parameters

Parameter Value Default / Possible values Description
id string popular Published track 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   Comma-separated list of track response chunks to return. Default is artists,releases,categories. For format=rss response parameter is ignored. See “Track List Response (application/xml - ym:Tracks)” 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 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. Use response=sorts to get the available sort orders for the list

User's recommended tracks

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

GET

Returns the user's recommended tracks.

Requires BBAuth for authentication

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

Responses: “Track List Response (application/xml - ym:Tracks)”

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
maxAge int >=2 Maximum number of days since a song or album was released in order for it to be eligible for inclusion in the results. Must be at least 2.
maxYahooAge int >=2 Maximum number of days since a song or album was added to the Yahoo! Music library in order for it to be eligible for inclusion in the results. Must be at least 2.
ratings long   Yahoo! Music User ID of the user whose ratings should be returned in the result. Requires BBAuth.
response string artists,releases,categories Comma-separated list of track response chunks to return. Default is artists,releases,categories. For format=rss response parameter is ignored. See “Track List Response (application/xml - ym:Tracks)” 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 “Track RSS Response (application/xml - rss:rss)” for RSS output. For format=rss, response and verboseLevel parameters are 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. Use response=sorts to get the available sort orders for the list

Artist's tracks

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

GET

Returns tracks for a given artist.

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

Responses: “Track List Response (application/xml - ym:Tracks)”

Required Parameters

Parameter Value Description
id int Artist 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 artists,releases,categories Comma-separated list of track response chunks to return. Default is artists,releases,categories. For format=rss response parameter is ignored. See “Track List Response (application/xml - ym:Tracks)” 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 “Track RSS Response (application/xml - rss:rss)” for RSS output. For format=rss, response and verboseLevel parameters are 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

Tracks for a category

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

GET

Returns tracks for a given category.

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

Responses: “Track List Response (application/xml - ym:Tracks)”

Required Parameters

Parameter Value Description
id int 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   Comma-separated list of track response chunks to return. Default is artists,releases,categories,prices. For format=rss response parameter is ignored. See “Track List Response (application/xml - ym:Tracks)” 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 “Track RSS Response (application/xml - rss:rss)” for RSS output. For format=rss, response and verboseLevel parameters are 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. Use response=sorts to get the available sort orders for the list.

User's recently played tracks

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

GET

Returns the user's recently played tracks. For yahoo logged in users, the Y/T cookie authentication needs to match the ymid on the URL. This call may set the YMT cookie if it isn't passed on the request, needs to be updated or is passed but not valid (or not in sync with the Y/T cookies).

Requires BBAuth for authentication

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

Responses: “Track List Response (application/xml - ym:Tracks)”

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
history string 100 Calls the play history for specified time period. For example 30d indicates all plays in last 30 days. A m, h, d suffix may follow where m is minutes, h is hours, and d is days. A number without a suffix like 100 will be treated as an absolute, returning 100 recently played items.
ratings long   Yahoo! Music User ID of the user whose ratings should be returned in the result. Requires BBAuth.
response string artists,releases,categories Comma-separated list of track response chunks to return. Default is artists,releases,categories. For format=rss response parameter is ignored. See “Track List Response (application/xml - ym:Tracks)” 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 “Track RSS Response (application/xml - rss:rss)” for RSS output. For format=rss, response and verboseLevel parameters are 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. Use response=sorts to get the available sort orders for the list.

User's rated tracks

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

GET

Returns tracks that user has rated.

Requires BBAuth for authentication

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

Responses: “Track List Response (application/xml - ym:Tracks)”

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
minRating int 0 All ratings returned will be equal or higher than this value
maxRating int 100 All ratings returned will be equal or lower than this value
ratings long   Yahoo! Music User ID of the user whose ratings should be returned in the result. Requires BBAuth.
response string artists,releases,categories Comma-separated list of track response chunks to return. Default is artists,releases,categories. For format=rss response parameter is ignored. See “Track List Response (application/xml - ym:Tracks)” 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 “Track RSS Response (application/xml - rss:rss)” for RSS output. For format=rss, response and verboseLevel parameters are 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. Use response=sorts to get the available sort orders for the list.

Search for tracks

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

GET

Returns tracks matching a search keyword on a given field.

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

Responses:

Required Parameters

Parameter Value Default / Possible values Description
searchmode string track, all Field to search on (only all is currently supported).
keyword string track, all 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 artists,releases,categories Comma-separated list of track response chunks to return. Default is artists,releases,categories. For format=rss response parameter is ignored. See “Track List Response (application/xml - ym:Tracks)” 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 “Track RSS Response (application/xml - rss:rss)” for RSS output. For format=rss, response and verboseLevel parameters are 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, will return only 'Family Friendly' results. Else, it will return all results. It is legacy parameter.
spelltoken string   Passed to client when there are spelling suggestions, including multiple suggestions, when client searches for keyword and SpellResult is returned. Out of these results, the client request one of them back. Client needs to pass the "token" as "spelltoken" when sending query with spelling suggestions. For example, if the client searches for "madona"(/artist/v1/list/search/artist/madona), an incorrect spelling, the client gets back the SpellResult and attribute token="n-839755038_q-M.qxPBEeiZrVMvYwKwTLIAAAAA@@". Out of these suggestions, the client selects "madonna" as correct spelling suggestion. It must pass the token such as /artist/v1/list/search/artist/madonna?spelltoken=n-839755038_qM.qxPBEeiZrVMvYwKwTLIAAAAA@@
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.