Subscriptions: User

You can retrieve a user's playlist subscriptions.

Endpoint URL

/api/users/:user_id/playlist_subscriptions

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.

order_by

optional

Indicates how the results set should be ordered.

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.

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.
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 subscribing to playlists (see Subscribe and Bulk Subscribe). To retrieve and display a user's playlist subscriptions, you will need an access token.

Suppose you have retrieved a list of subscribers for the playlist "Born to Run" (see Subscribers), and you would like to find out more about one of the subscribers listed in the response:

{
    "data": [
        {
            "type": "user",
            "id": "150470956064702464",
            "username": "[USER_NAME]",
            "full_name": "[USER_FULL_NAME]",
            "total_followed_by": 0,
            "total_follows": 0
        },
        ...
    ],
    ...
    "code": "OK"
}

We will use the user's ID (150470956064702464) to retrieve and display their subscriptions, which you may then conveniently use to find out what tracks and other information those playlists contain (see the Subscriptions: Fetch API). You will need to use your access token since you are invoking this API on behalf of the user.

The general form of this API is:

curl -X GET "https://partner.api.beatsmusic.com/v1/api/users/[USER_ID]/playlist_subscriptions?
    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?
    access_token=[YOUR_ACCESS_TOKEN]"

Example Response

Here is the API response indicating that you have successfully retrieved the playlist subscriptions, which you may then conveniently use to find out what tracks and other information those playlists contain (see the Subscriptions: Fetch API):

{
    "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": "tr27841605",
                        "display": "Peter Piper"
                    },
                    {
                        "ref_type": "track",
                        "id": "tr30007789",
                        "display": "Hard Times"
                    },
                    {
                        "ref_type": "track",
                        "id": "tr31042511",
                        "display": "It's Like That"
                    }
                    ...
                ],
                "user": {
                    "ref_type": "genre",
                    "display": "beatshiphop",
                    "id": "eg97074088215970048"
                },
                "author": {
                    "ref_type": "user",
                    "display": "Rob Markman",
                    "id": "61012263301021696"
                }
            }
        },
        {
            "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": 51,
            "created_at": 1370995200,
            "updated_at": 1394012479,
            "parental_advisory": false,
            "refs": {
                "tracks": [
                    {
                        "ref_type": "track",
                        "id": "tr30359165",
                        "display": "Born To Run"
                    },
                    {
                        "ref_type": "track",
                        "id": "tr8104283",
                        "display": "I Feel Like Going Home"
                    },
                    {
                        "ref_type": "track",
                        "id": "tr6772395",
                        "display": "Free Bird"
                    }
                    ...
                ],
                "user": {
                    "ref_type": "genre",
                    "display": "beatsclassicrock",
                    "id": "eg97079905791115776"
                },
                "author": {
                    "ref_type": "user",
                    "display": "Andrew Woloz",
                    "id": "10675"
                }
            }
        }
    ],
    "info": {
        "offset": 0,
        "count": 2,
        "total": 2
    },
    "code": "OK"
}

version 6 as of 2 months ago by Robin

Jul	AUG	Sep
	13
2013	2014	2015