Collection
You can retrieve the specified public playlists in Beats, as well as any private playlists belonging to the user represented by the access token.
Endpoint URL
/api/playlists
HTTP Method
GET
Authentication
OAuth 2.0: Access token required. See Authentication for examples and details.
Parameters
| Name | Required | Description | Example | ||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ids | required | An array of playlist IDs. | ids=pl649915&ids=pl568234 | ||||||||||||||||||||||||||||
| limit | optional | Specifies the maximum number of records to retrieve. The number of results returned will be less than or equal to this value. No results are returned if it is set to zero or less. The maximum permitted value is 200. If a value higher than 200 is specified, no more 200 results will be returned. Default 20. | 20 | ||||||||||||||||||||||||||||
| order_by | optional | Indicates how the results set should be ordered.
|
name |
Response Elements
| Response | Description |
|---|---|
| code |
Beats API response code. OK if successful; otherwise an error code is returned. |
| data |
List of playlists matching the request. Each element is a playlist object: |
|
type |
The entity type of the API object. |
|
id |
The unique ID of the playlist. |
|
name |
The name of the playlist.y |
|
description |
The description of the playlist. |
|
total_tracks |
The number of tracks on the album, including unstreamable tracks. |
|
total_subscribers |
The number of users subscribed to the playlist. |
|
duration |
Total duration of the audio, in seconds. |
|
created_at |
Epoch creation timestamp for the playlist. |
|
updated_at |
Epoch timestamp for the last update of the playlist. |
|
parental_advisory |
Indicates whether the item has a parental advisory (explicit) warning. |
|
refs |
Object with keys corresponding to referenced object types, and values providing the information needed for linking to the objects. |
Example Request
Suppose you would like to retrieve complete information for playlists you will find based on a search using the term "Born to Run". You can begin by using the Search API to look up the playlist IDs:
curl -X GET "https://partner.api.beatsmusic.com/v1/api/search?
q=born+to+run
&type=playlist
&client_id=[YOUR_CLIENT_ID]"Here is the response:
{
"data":[
{
"type":"search_result",
"result_type":"playlist",
"id":"pl130560517973607168",
"display":"Born to Run",
"detail":"Beats Classic Rock",
"related":{
"ref_type":"playlist",
"id":"pl130560517973607168",
"display":"Born to Run"
}
},
{
"type":"search_result",
"result_type":"playlist",
"id":"pl2753971",
"display":"Born to Run: Songs about Leaving",
"detail":"Beats Classic Rock",
"related":{
"ref_type":"playlist",
"id":"pl2753971",
"display":"Born to Run: Songs about Leaving"
}
},
{
"type":"search_result",
"result_type":"playlist",
"id":"pl63835226865926144",
"display":"Intro to Run-D.M.C.",
"detail":"Beats Hip-Hop",
"related":{
"ref_type":"playlist",
"id":"pl63835226865926144",
"display":"Intro to Run-D.M.C."
}
},
...
],
"info":{
"offset":0,
"count":20,
"total":6354
},
"code":"OK"
}We will use the playlist IDs we found in the response above (pl130560517973607168, pl2753971, pl63835226865926144) to retrieve the complete information for those playlists. You will need to use your access token. The general form of this API is:
curl -X GET "https://partner.api.beatsmusic.com/v1/api/playlists/?
ids=[VALID_PLAYLIST_ID]
&access_token=[YOUR_ACCESS_TOKEN]"In this example we will retrieve 3 of the subscribers by specifying the limit parameter:
curl -X GET "https://partner.api.beatsmusic.com/v1/api/playlists/?
ids=pl130560517973607168
&ids=pl2753971
&ids=pl63835226865926144
&access_token=[YOUR_ACCESS_TOKEN]"Example Response
Here is the API response indicating that you have successfully retrieved the playlists:
{
"data":[
{
"type":"playlist",
"id":"pl130560517973607168",
"name":"Born to Run",
"description":"Head out for a run ...",
"user_display_name":"Beats Classic Rock",
"access":"public",
"duration":3696,
"total_tracks":15,
"total_subscribers":131,
"created_at":1388126453,
"updated_at":1392947048,
"parental_advisory":false,
"refs":{
"tracks":[
{
"ref_type":"track",
"id":"tr45856473",
"display":"1969"
},
{
"ref_type":"track",
"id":"tr3443979",
"display":"Skin & Bone"
},
...
],
"user":{
"ref_type":"genre",
"display":"beatsclassicrock",
"id":"eg97079905791115776"
},
"author":{
"ref_type":"user",
"display":"Greg Miller",
"id":"111564721198596608"
}
}
},
{
"type":"playlist",
"id":"pl2753971",
"name":"Born to Run: Songs about Leaving",
"description":"Sometimes you feel ...",
"user_display_name":"Beats Classic Rock",
"access":"public",
"duration":3381,
"total_tracks":14,
"total_subscribers":47,
"created_at":1370995200,
"updated_at":1393270748,
"parental_advisory":false,
"refs":{
"tracks":[
{
"ref_type":"track",
"id":"tr30359165",
"display":"Born To Run"
},
{
"ref_type":"track",
"id":"tr15063243",
"display":"Movin' Out (Anthony's Song)"
},
...
],
"user":{
"ref_type":"genre",
"display":"beatsclassicrock",
"id":"eg97079905791115776"
},
"author":{
"ref_type":"genre",
"display":"Beats Classic Rock",
"id":"eg97079905791115776"
}
}
},
{
"type":"playlist",
"id":"pl63835226865926144",
"name":"Intro to Run-D.M.C.",
"description":"Run-D.M.C. were ...",
"user_display_name":"Beats Hip-Hop",
"access":"public",
"duration":4038,
"total_tracks":17,
"total_subscribers":153,
"created_at":1372217904,
"updated_at":1393271592,
"parental_advisory":true,
"refs":{
"tracks":[
{
"ref_type":"track",
"id":"tr30007805",
"display":"Sucker M.C.'S (Krush-Groove 1)"
},
{
"ref_type":"track",
"id":"tr27841605",
"display":"Peter Piper"
},
...
}
}
],
"info":{
"offset":0,
"count":3,
"total":3
},
"code":"OK"
}
