Lookup
You can retrieve a playlist. If the playlist is not public, it must be owned by the user identified by the access token.
Endpoint URL
/api/playlists/:playlist_id
HTTP Method
GET
Authentication
OAuth 2.0: Access token required. See Authentication for examples and details.
Parameters
| Name | Required | Description | Example |
|---|---|---|---|
| playlist_id | required | The unique ID for the playlist. | pl151699877020041728 |
Response Elements
| Response | Description |
|---|---|
| code |
Beats API response code. OK if successful; otherwise an error code is returned. |
| data |
A container for the playlist object: |
|
type |
The entity type of the API object. |
|
id |
The unique ID of the playlist. |
|
name |
The name of the playlist. |
|
description |
The description of the playlist. |
|
user_display_name |
The name to use when displaying the playlist's author. |
|
total_tracks |
The number of tracks on the playlist, 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
One of the central activities for a user is creating playlists (see Create or the Tutorial). To retrieve and display an existing playlist, you will need the playlist ID and an access token.
Recall that when you first created the playlist, a response containing the playlist ID was returned:
{
"data": {
"type": "playlist",
"id": "pl151699877020041728",
"name": "My New Playlist",
"description": "",
...
},
"code": "OK"
}If you no longer have that playlist ID, retrieve the user's playlist collection by invoking the User API.
We will use the playlist ID (pl151699877020041728) to retrieve and display the existing playlist, "My Favorite Playlist". You will need to use your access token since you are invoking this API on behalf of a user.
The general form of this API is:
curl -X GET "https://partner.api.beatsmusic.com/v1/api/playlists/[YOUR_PLAYLIST_ID]?
access_token=[YOUR_ACCESS_TOKEN]"In this example we will retrieve My+New+Playlist:
curl -X GET "https://partner.api.beatsmusic.com/v1/api/playlists/pl151699877020041728?
access_token=[YOUR_ACCESS_TOKEN]"Example Response
Here is the API response indicating that you have successfully retrieved the playlist, which you may then display in your applications:
{
"data": {
"type": "playlist",
"id": "pl151699877020041728",
"name": "My Favorite Playlist",
"description": "My Favorite Tracks",
"user_display_name": "[YOUR_USER_DISPLAY_NAME]",
"access": "public",
"duration": 857,
"total_tracks": 2,
"total_subscribers": 0,
"created_at": 1393166469,
"updated_at": 1393793663,
"parental_advisory": false,
"refs": {
"tracks": [
{
"ref_type": "track",
"id": "tr56470885",
"display": "Blood On The Tracks"
},
{
"ref_type": "track",
"id": "tr51760477",
"display": "Blood On The Tracks"
}
],
"user": {
"ref_type": "user",
"display": "[YOUR_USER_NAME]",
"id": "150470956064702464"
},
"author": {
"ref_type": "user",
"display": "[YOUR_AUTHOR_NAME]",
"id": "150470956064702464"
}
}
},
"code": "OK"
}
