Subscriptions: Fetch
You can retrieve one of the playlists contained in a user's subscriptions.
Endpoint URL
/api/users/:user_id/playlist_subscriptions/:playlist_id
HTTP Method
GET
Authentication
OAuth 2.0: Access token required. See Authentication for examples and details.
Parameters
| Name | Required | Description | Example |
|---|---|---|---|
| user_id | required | The unique ID for the user. | 150470956064702464 |
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 subscribing to playlists (see Subscribe and Bulk Subscribe). Suppose you have retrieved and stored a list of the user's playlist subscriptions (see the Subscriptions: User API) and would later like to get more detail about one of those playlists:
{
"data": [
{
"type": "playlist",
"id": "pl63835226865926144",
"name": "Intro to Run-D.M.C.",
"description": "Run-D.M.C. were ... in 2009.",
...
},
{
"type": "playlist",
"id": "pl2753971",
"name": "Born to Run: Songs about Leaving",
"description": "Sometimes you feel ...",
...
}
],
"info": {
"offset": 0,
"count": 2,
"total": 2
},
"code": "OK"
}From the response we can see that the user is subscribed to "Intro to Run-D.B.C.". To retrieve and display more complete information about this particular playlist subscription, you will need the user ID you used to retrieve the list of subscriptions for that user (150470956064702464), the playlist ID (pl63835226865926144), and an access token.
The general form of this API is:
curl -X GET "https://partner.api.beatsmusic.com/v1/api/users/[USER_ID]/playlist_subscriptions/[PLAYLIST_ID]?
access_token=[YOUR_ACCESS_TOKEN]"In this example we will retrieve the playlist subscriptions for user ID 150470956064702464:
curl -X GET "https://partner.api.beatsmusic.com/v1/api/users/150470956064702464/playlist_subscriptions/pl63835226865926144?
access_token=[YOUR_ACCESS_TOKEN]"Example Response
Here is the API response indicating that you have successfully retrieved the user's subscribed playlist, "Intro to Run-D.B.C.". You can now associate the user with the playlist detail in your applications:
{
"data": {
"type": "playlist",
"id": "pl63835226865926144",
"name": "Intro to Run-D.M.C.",
"description": "Run-D.M.C. were ... in 2009.",
"user_display_name": "Beats Hip-Hop",
"access": "public",
"duration": 4038,
"total_tracks": 17,
"total_subscribers": 164,
"created_at": 1372217904,
"updated_at": 1394012478,
"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"
},
{
"ref_type": "track",
"id": "tr30008003",
"display": "Run's House"
},
...
],
"user": {
"ref_type": "genre",
"display": "beatshiphop",
"id": "eg97074088215970048"
},
"author": {
"ref_type": "user",
"display": "Rob Markman",
"id": "61012263301021696"
}
}
},
"code": "OK"
}
