close
The Wayback Machine - https://web.archive.org/web/20140813162915/https://developer.beatsmusic.com/docs/read/playlists/User

User

You can retrieve a user's playlist collection. If the playlists are not public, they must be owned by the user identified by the access token.

Endpoint URL

/api/users/:user_id/playlists

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
offset optional A zero-based integer offset into the results. Default 0. 0
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 sorted.
Values:
name asc Order alphabetically by name. This is the default value.
name Equivalent to name asc.
name desc Sort in in reverse alphabetical order by name.
created_at asc Equivalent to created_at.
created_at desc Sort in in reverse alphabetical order by created_at
updated_at asc Order by updated_at.
updated_at Equivalent to updated_at asc.
updated_at desc Sort in in reverse order by updated_at.
duration asc Order by duration.
duration Equivalent to duration asc.
duration desc Sort in in reverse order by duration.
total_tracks asc Order by total_tracks.
total_tracks Equivalent to total_tracks asc.
total_tracks desc Sort in in reverse order by total_tracks.
total_subscribers asc Sort by total_subscribers.
name

Response Elements

ResponseDescription
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.

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.
ref_type
The API object type of the referenced item.
id
The unique ID of the referenced item.
display
Text to be displayed when displaying a link to the referenced item.
 

Example Request

One of the central activities for a user is creating playlists (see Create or the Tutorial). To retrieve and display a user's playlists, you will need the user's ID and an access token.

Recall that when you first created the playlist for a user, a response containing the user ID was returned:

{
    "data": {
        ...
    },
    "refs": {
        ...
        "user": {
            "ref_type": "user",
            "display": "[YOUR_USER_NAME]",
            "id": "150470956064702464"
        },
        ...
    }
    "code": "OK"
}

Another way you can get a user ID is by retrieving a list of subscribers for a given playlist by invoking the Subscribers API.

We will use the user ID (150470956064702464) to retrieve and display that user's playlists in reverse alphabetical order. You will need to specify order_by=name+desc to sort the results in reverse alphabetical order, and 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/users/[YOUR_USER_ID]/playlists?
    &access_token=[YOUR_ACCESS_TOKEN]"

In this example we will retrieve the user's playlists and sort them in reverse alphabetical order by specifying the optional order_by parameter:

curl -X GET "https://partner.api.beatsmusic.com/v1/api/users/150470956064702464/playlists?
    order_by=name+desc
    &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": "pl151697954665660416",
            "name": "Young Mula",
            "description": "",
            "user_display_name": "[YOUR_USER_DISPLAY_NAME]",
            "access": "public",
            "duration": 0,
            "total_tracks": 0,
            "total_subscribers": 0,
            "created_at": 1393166010,
            "updated_at": 1393166010,
            "parental_advisory": false,
            "refs": {
                "tracks": [],
                "user": {
                    "ref_type": "user",
                    "display": "[YOUR_USER_NAME]",
                    "id": "150470956064702464"
                },
                "author": {
                    "ref_type": "user",
                    "display": "[YOUR_AUTHOR_NAME]",
                    "id": "150470956064702464"
                }
            }
        },
        {
            "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"
                }
            }
        }
    ],
    "info": {
        "offset": 0,
        "count": 2,
        "total": 2
    },
    "code": "OK"
}

version 5 as of 2 months ago by Robin

Docs Navigation