Back to top

CURIOMusic API v2

CURIOMusic API v2 provides programmatic access to PlayNetwork’s continuously curated audio and content meta data. In order to access this API, client credentials (clientId and clientSecret) are required. The Authentication Tokens section describes the process for generating a refresh token for use with with this API.

API Endpoints

The following endpoints are available for interaction with CURIOMusic API:

Error Responses

During interaction with the CURIOMusic API, the following error messages may be returned. Important Note: The HTTP status code will match the statusCode parameter defined in the message payload.

  • IncorrectConfigurationError This error may be returned from the API in the event that the content association with the client is not configured. This error outlines a scenario that requires direct PlayNetwork support to resolve.
{
  "name": "IncorrectConfigurationError",
  "message": "details regarding the error",
  "statusCode": 501
}
  • IncorrectParameterError This error is returned when a required parameter for an API resource is missing or is not formatted properly.
{
  "name": "IncorrectParameterError",
  "message": "details regarding the error",
  "statusCode": 409
}
  • InvalidAuthorizationError This error is most commonly returned when authentication token has expired. This message may also be returned in the event that the requested resource is not accessible due to security restrictions.
{
  "name": "InvalidAuthorizationError",
  "message": "details regarding the error",
  "statusCode": 401
}
  • InvalidBroadcastError This error can occur in the event that the parameters presented for generating a broadcast or a channel mix are incorrect or will result in the inability to generate a broadcast.
{
  "name": "InvalidBroadcastError",
  "message": "details regarding the error",
  "statusCode": 409
}
  • ModelNotFoundError When a requested station, collection, track or broadcast does not exist for the specified identifier, this error is returned.
{
  "name": "ModelNotFoundError",
  "message": "details regarding what was not found",
  "statusCode": 404
}

Authentication Tokens

Access to the resources exposed by the CURIOMusic API can be achieved by using the PlayNetwork provided Client ID and Secret Access Key to generate an authentication token. The PlayNetwork Key API generates authentication tokens that are required for all queries to the CURIOMusic API.

Tokens

Generate an authentication token for use in all subsequent PlayNetwork API requests. The tokens resource returns a single object in JSON format with the following properties:

  • tokenId - this value is supplied as the x-authentication-token header parameter required for all subsequent API requests to CURIOMusic API

  • expires - this denotes when the authentication token will expire

  • clientId - echo back of the supplied the client ID

  • modified - when the authentication token was last modified

  • created - when the authentication token was created

Create a token
POST/v0/tokens

An example request via the curl command looks as follows:

curl -XPOST \
  -H "x-client-id:xxxxxxxxxx" \
  -H "x-client-secret:xxxxxxxxxx" \
  https://key-api.apps.playnetwork.com/v0/tokens

Example URI

POST https://curio-music-api.apps.playnetwork.com/v0/tokens
Request
HideShow
Headers
Content-Type: application/json
x-client-id: required
x-client-secret: required
Response  201
HideShow
Headers
Content-Type: application/json
Body
{
  "token": {
    "tokenId": "xxxxxxxxxx",
    "expires": "2015-05-08T14:57:23.562Z",
    "clientId": "xxxxxxxxxx",
    "modified": "2015-05-06T14:57:23.562Z",
    "created": "2015-05-06T14:57:23.562Z"
  }
}

Stations

The stations resource provides access to channels where audio content from one or more collections is combined to follow a set of scheduling rules. These rules may include mixing, artist separation, collection podding and scheduled date parting.

All Stations

Search and retrieve a paginated, filtered and sorted list of stations from the API.

The search stations resource returns JSON with the following properties:

  • options

    • count - the number of results requested
    • filters - the filters applied
    • sort - the sorts applied
    • start - the starting index from which to retrieve results

  • results - an array of matching results with a length less than or equal to count

  • total - the total number of results matching the query

Search All Stations
GET/v2/stations{?start,count,filters,sort}

Example URI

GET https://curio-music-api.apps.playnetwork.com/v2/stations?start=0&count=100&filters=filters[mandatory][exact][title]=latin%20electronica&sort=sort[desc]=modified
URI Parameters
HideShow
start
number (optional) Example: 0

index of where to start when querying results

count
number (optional) Example: 100

number of results to retrieve

filters
object (optional) Example: filters[mandatory][exact][title]=latin%20electronica

a set of search filters supplied in bracket notation

sort
object (optional) Example: sort[desc]=modified

a set of sorting options supplied in bracket notation

Request
HideShow
Headers
Content-Type: application/json
x-client-id: required
x-authentication-token: required
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "options": {
    "count": 100,
    "filters": {},
    "sort": {},
    "start": 0
  },
  "results": [
    {
      "stationId": "a55f23a6887642bfb00f366fd5abb447",
      "title": "DECEMBER 2015 PLAYLIST",
      "modified": "2015-11-06T18:31:45.113Z",
      "created": "2015-11-02T12:24:54.999Z",
      "scheduledCollections": [
        {
          "collectionId": "3cec7277843643429c009e3685ad07dc",
          "endDate": "2015-11-26T23:59:59.000Z",
          "beginDate": "2015-11-23T00:00:00.000Z",
          "allowUserSelection": true
        },
        {
          "collectionId": "70a9ff7096454b8dac93937dbdc0682f",
          "endDate": "2015-11-09T23:59:59.000Z",
          "beginDate": "2015-11-09T00:00:00.000Z",
          "allowUserSelection": true
        },
        {
          "collectionId": "cc79596f73814d37af48738504a55a9a",
          "endDate": "2015-11-11T23:59:59.000Z",
          "beginDate": "2015-11-10T00:00:00.000Z",
          "allowUserSelection": true
        },
        // results abbreviated
      ]
    }
  ],
  "total": 1
}

Individual Stations

Retrieve a specific station from the API.

The stations resource returns JSON with the following properties:

  • stationId - this value uniquely identifies the station

  • title - this is the title for the station (which is non-unique)

  • modified - the date at which this station was last modified

  • created - the date at which this station was created

  • scheduledCollections - an array of collections that are used by the station during broadcast

    • collectionId - the unique identifier of the collection
    • endDate - the date at which this collection expires from the station and will no longer appear in a broadcast
    • beginDate - the date at which this collection may begin appearing in a broadcast
    • allowUserSelection - deprecated and will be removed in a subsequent version of the API

Station Details
GET/v2/stations/{stationId}

Retrieve a single station from the API.

Example URI

GET https://curio-music-api.apps.playnetwork.com/v2/stations/a55f23a6887642bfb00f366fd5abb447
URI Parameters
HideShow
stationId
string (required) Example: a55f23a6887642bfb00f366fd5abb447
Request
HideShow
Headers
Content-Type: application/json
x-client-id: required
x-authentication-token: required
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "stationId": "a55f23a6887642bfb00f366fd5abb447",
  "title": "DECEMBER 2015 PLAYLIST",
  "modified": "2015-11-06T18:31:45.113Z",
  "created": "2015-11-02T12:24:54.999Z",
  "scheduledCollections": [
    {
      "collectionId": "3cec7277843643429c009e3685ad07dc",
      "endDate": "2015-11-26T23:59:59.000Z",
      "beginDate": "2015-11-23T00:00:00.000Z",
      "allowUserSelection": true
    },
    {
      "collectionId": "70a9ff7096454b8dac93937dbdc0682f",
      "endDate": "2015-11-09T23:59:59.000Z",
      "beginDate": "2015-11-09T00:00:00.000Z",
      "allowUserSelection": true
    },
    {
      "collectionId": "cc79596f73814d37af48738504a55a9a",
      "endDate": "2015-11-11T23:59:59.000Z",
      "beginDate": "2015-11-10T00:00:00.000Z",
      "allowUserSelection": true
    },
    // results abbreviated
  ]
}

Broadcasts

Broadcasts are linear schedules created from stations. The broadcast represents an ordered queue of tracks that have been sorted, mixed and plucked from the collections associated to the station in accordance with the following rules (in order of priority):

  1. Start and duration - play from X start time for Y number of minutes

  2. Days of the week - play from this collection only on the defined days of the week

  3. Random or sequential - pluck the next song from this collection either randomly or sequentially

  4. Time insensitive podding - play a group of X tracks from this collection, even if that will exceed duration constraints defined in other time rules (i.e. day-parting)

  5. Day-parting for playback of collections within a station

  6. Time separation - play tracks from other collections for X time until playing from this collection again

  7. Time sensitive podding - play a group of X tracks from this collection, but break on previously defined time rules if applicable

  8. Collection separation - play X tracks from other collections prior to playing a track from this collection again

  9. Play a collection entirely (all tracks)

  10. Track title separation - play X number of tracks with other titles before playing a track with this title again

  11. Artist name Separation - play X number of tracks from other artists before play a track by this artist again

The mixer will break lower ranked rules, on occasion, in order to ensure a higher priority rule is followed.

All Broadcasts

Search and retrieve a paginated, filtered and sorted list of station broadcasts from the API.

The search broadcasts resource returns JSON with the following properties:

  • options

    • count - the number of results requested
    • filters - the filters applied
    • sort - the sorts applied
    • start - the starting index from which to retrieve results

  • results - an array of matching results with a length less than or equal to count

  • total - the total number of results matching the query

Search All Broadcasts
GET/v2/stations/{stationId}/broadcasts{?start,count,filters,sort}

Example URI

GET https://curio-music-api.apps.playnetwork.com/v2/stations/a55f23a6887642bfb00f366fd5abb447/broadcasts?start=0&count=50&filters=filters[mandatory][lte][beginDate]=2015-12-01&sort=sort[desc]=modified
URI Parameters
HideShow
stationId
string (required) Example: a55f23a6887642bfb00f366fd5abb447

the station for which broadcasts should be retrieved

start
number (optional) Example: 0

index of where to start when querying results

count
number (optional) Example: 50

number of results to retrieve

filters
object (optional) Example: filters[mandatory][lte][beginDate]=2015-12-01

a set of search filters supplied in bracket notation

sort
object (optional) Example: sort[desc]=modified

a set of sorting options supplied in bracket notation

Request
HideShow
Headers
Content-Type: application/json
x-client-id: required
x-authentication-token: required
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "options": {
    "count": 100,
    "filters": {},
    "sort": {},
    "start": 0
  },
  "results": [
    {
      "createdByClientId": "78055dd84d484818bda3f676a0c38246",
      "broadcastId": "2e58d3ee65294f85ac8d3426c61d5a93",
      "options": {
        "duration": 1440,
        "beginDate": "2015-11-10T19:58:15.546Z"
      },
      "modified": "2015-11-10T19:58:18.344Z",
      "created": "2015-11-10T19:58:18.344Z"
    },
    {
      "createdByClientId": "78055dd84d484818bda3f676a0c38246",
      "broadcastId": "0d932baec1b74af6b09eb646851ecb4f",
      "options": {
        "duration": 1440,
        "beginDate": "2015-11-10T20:33:25.899Z"
      },
      "modified": "2015-11-10T20:33:28.507Z",
      "created": "2015-11-10T20:33:28.507Z"
    },
    // results abbreviated
  ],
  "total": 80
}

Individual Broadcasts

Retrieve a specific broadcast from the API.

The broadcasts resource returns JSON with the following properties:

  • broadcastId - the unique identifier for the broadcast

  • createdByClientId - the clientId that was used to generate the broadcast

  • created - the date when the broadcast was created

  • modified - the date when the broadcast was modified - as the API does not allow for updating of broadcasts once created (they are treated as though they are immutable), this date will always match the created date

  • options - input data used to build the broadcast

    • beginDate - the starting time of the broadcast
    • duration - the duration, in minutes, of the broadcast

  • queue - the queue of tracks to be played in order

    • artist
      • name - the name of the artist
    • assetId - an identifier used for looking up track details from the content API
    • collectionId - the collection from which the track was plucked
    • duration - the duration of the track
    • legacy
      • trackToken - the internal track identifier (will generally always be present even if assetId is missing)
    • order - the order in which the track should be played with respect to all other tracks in the queue
    • title - the title of the track

Broadcast Details
GET/v2/stations/{stationId}/broadcasts/{broadcastId}

Retrieve a single broadcast from the API.

Example URI

GET https://curio-music-api.apps.playnetwork.com/v2/stations/a55f23a6887642bfb00f366fd5abb447/broadcasts/0d932baec1b74af6b09eb646851ecb4f
URI Parameters
HideShow
stationId
string (required) Example: a55f23a6887642bfb00f366fd5abb447

the station for which broadcasts should be retrieved

broadcastId
string (required) Example: 0d932baec1b74af6b09eb646851ecb4f

the identifier for the broadcast to retrieve

Request
HideShow
Headers
Content-Type: application/json
x-client-id: required
x-authentication-token: required
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "createdByClientId": "78055dd84d484818bda3f676a0c38246",
  "broadcastId": "0d932baec1b74af6b09eb646851ecb4f",
  "queue": [
    {
      "duration": 196,
      "title": "Ever Fallen In Love?",
      "collectionId": "cc79596f73814d37af48738504a55a9a",
      "order": 0,
      "legacy": {
        "trackToken": 645282
      },
      "artist": {
        "name": "Nouvelle Vague"
      }
    },
    {
      "duration": 264,
      "title": "Twin Peaks",
      "collectionId": "cc79596f73814d37af48738504a55a9a",
      "order": 1,
      "legacy": {
        "trackToken": 946162
      },
      "artist": {
        "name": "Alice Russell"
      }
    },
    // results abbreviated
  ],
  "options": {
    "duration": 1440,
    "beginDate": "2015-11-10T20:33:25.899Z"
  },
  "modified": "2015-11-10T20:33:28.507Z",
  "created": "2015-11-10T20:33:28.507Z"
}

Create Broadcast
POST/v2/stations/{stationId}/broadcasts/

Create a broadcast in the API.

To create a broadcast, the following parameters in the request body are supported:

  • beginDate - the starting time of the broadcast (this is defaulted to the time at which the request was made)

  • duration - the length, in minutes, for the playlist (this is defaulted to 1440 which is 24 hours)

Example URI

POST https://curio-music-api.apps.playnetwork.com/v2/stations/a55f23a6887642bfb00f366fd5abb447/broadcasts/
URI Parameters
HideShow
stationId
string (required) Example: a55f23a6887642bfb00f366fd5abb447

the station for which broadcasts should be created

Request
HideShow
Headers
Content-Type: application/json
x-client-id: required
x-authentication-token: required
Body
{
  "beginDate": "2015-11-10T20:33:25.899Z",
  "duration": 1440
}
Response  201
HideShow
Headers
Content-Type: application/json
Body
{
  "createdByClientId": "78055dd84d484818bda3f676a0c38246",
  "broadcastId": "0d932baec1b74af6b09eb646851ecb4f",
  "queue": [
    {
      "duration": 196,
      "title": "Ever Fallen In Love?",
      "collectionId": "cc79596f73814d37af48738504a55a9a",
      "order": 0,
      "legacy": {
        "trackToken": 645282
      },
      "artist": {
        "name": "Nouvelle Vague"
      }
    },
    {
      "duration": 264,
      "title": "Twin Peaks",
      "collectionId": "cc79596f73814d37af48738504a55a9a",
      "order": 1,
      "legacy": {
        "trackToken": 946162
      },
      "artist": {
        "name": "Alice Russell"
      }
    },
    // results abbreviated
  ],
  "options": {
    "duration": 1440,
    "beginDate": "2015-11-10T20:33:25.899Z"
  },
  "modified": "2015-11-10T20:33:28.507Z",
  "created": "2015-11-10T20:33:28.507Z"
}

Delete Broadcast
DELETE/v2/stations/{stationId}/broadcasts/{broadcastId}

Remove a single broadcast from the API.

Example URI

DELETE https://curio-music-api.apps.playnetwork.com/v2/stations/a55f23a6887642bfb00f366fd5abb447/broadcasts/0d932baec1b74af6b09eb646851ecb4f
URI Parameters
HideShow
stationId
string (required) Example: a55f23a6887642bfb00f366fd5abb447

the station for which broadcasts should be deleted

broadcastId
string (required) Example: 0d932baec1b74af6b09eb646851ecb4f
Request
HideShow
Headers
Content-Type: application/json
x-client-id: required
x-authentication-token: required
Response  204

Collections

The collections resource provides access to collections of audio content. Collections are playlists that they have been hand curated by a dedicated and knowledgeable group of music professionals. Collections represent a simple, unordered set of audio content.

All Collections

Search and retrieve a paginated, filtered and sorted list of collections from the API.

The search collections resource returns JSON with the following properties:

  • options

    • count - the number of results requested
    • filters - the filters applied
    • sort - the sorts applied
    • start - the starting index from which to retrieve results

  • results - an array of matching results with a length less than or equal to count

  • total - the total number of results matching the query

Search All Collections
GET/v2/collections{?start,count,filters,sort}

Example URI

GET https://curio-music-api.apps.playnetwork.com/v2/collections?start=0&count=100&filters=filters[mandatory][exact][title]=latin%20electronica&sort=sort[desc]=modified
URI Parameters
HideShow
start
number (optional) Example: 0

index of where to start when querying results

count
number (optional) Example: 100

number of results to retrieve

filters
object (optional) Example: filters[mandatory][exact][title]=latin%20electronica

a set of search filters supplied in bracket notation

sort
object (optional) Example: sort[desc]=modified

a set of sorting options supplied in bracket notation

Request
HideShow
Headers
Content-Type: application/json
x-client-id: required
x-authentication-token: required
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "options": {
    "count": 100,
    "filters": {},
    "sort": {},
    "start": 0
  },
  "results": [
    {
      "collectionId": "7d7d88e131dd45f986e01e0c843536ea",
      "title": "Spa",
      "modified": "2015-07-21T14:10:26.432Z",
      "created": "2015-07-20T17:54:28.402Z",
      "trackCount": 713
    },
    {
      "collectionId": "72fcab788d9a4bd8864c408ce99496ad",
      "title": "Baroque & Chamber",
      "modified": "2015-07-21T14:17:16.282Z",
      "created": "2015-07-13T18:42:24.803Z",
      "trackCount": 848
    },
    // results abbreviated
  ],
  "total": 80
}

Individual Collections

Retrieve a specific collection from the API.

The collections resource returns JSON with the following properties:

  • collectionId - the unique identifier for the collection

  • title - the title of the collection

  • modified - the date when the collection was last modified

  • created - the date of when the collection was created

  • trackCount - the number of tracks contained within the collection

Collection Details
GET/v2/collections/{collectionId}

Retrieve a single collection from the API.

Example URI

GET https://curio-music-api.apps.playnetwork.com/v2/collections/c114f4844e6240ef9f458194fd6c2b23
URI Parameters
HideShow
collectionId
string (required) Example: c114f4844e6240ef9f458194fd6c2b23
Request
HideShow
Headers
Content-Type: application/json
x-client-id: required
x-authentication-token: required
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  collectionId:"13e5a1d0e47f4043b99d9f5982c0dc47",
  title:"Latin Electronica",
  modified:"2015-04-29T20:22:02.262Z",
  created:"2015-04-29T20:22:02.262Z",
  trackCount: 124
}

Collection Mix

The contents of a collection can be mixed, in random order, with artist and title separation to create radio station like broadcast experience.

The resource returns a JSON payload containing the following properties:

  • options

    • artistSeparation - the number of songs to attempt to play by other artists before playing a song by the same artist again
    • beginDate - the begin date for the mix
    • duration - the minimum number of minutes the mix should be generated for
    • randomMix - when true, tracks are randomly selected and other mix rules (i.e. artistSeparation and titleSeparation) are applied
    • titleSeparation - the number of songs to attempt to play with other song titles before playing a song with the same title again

  • queue - an array of songs in the order generated by the mix algorithm

    • assetId - an optional identifier that is used for retrieval of track data from content-api
    • duration - the length, in seconds, of the track
    • title - the title of the track
    • collectionId - the collection from which the track was plucked during mixing
    • order - the order of the track within the queue
    • legacy
      • trackToken - the identifier for the track in the PlayNetwork Conductor CMS
    • artist
      • name - the name of the artist

Collection Mix
GET/v2/collections/mix{?artistSeparation,beginDate,duration,randomMix,titleSeparation}

Retrieve a mix for a specified collection (or playlist) via the API.

Example URI

GET https://curio-music-api.apps.playnetwork.com/v2/collections/mix?artistSeparation=5&beginDate=2015-11-16T20:10:31.083Z&duration=1440&randomMix=true&titleSeparation=5
URI Parameters
HideShow
artistSeparation
number (optional) Example: 5

defaults to 5, this is the number of songs to attempt to separate based on artist name when randomly mixing

beginDate
date (optional) Example: 2015-11-16T20:10:31.083Z

defaults to now, this is the date in terms of the start of the schedule

duration
number (optional) Example: 1440

defaults to 1440, this is the number of minutes for which the broadcast should be generated

randomMix
boolean (optional) Example: true

defaults to true, this is whether or not to randomly mix the tracks or use the order supplied for the collection

titleSeparation
number (optional) Example: 5

defaults to 5, this is the number of songs to attempt to separate based on song title when randomly mixing

Request
HideShow
Headers
Content-Type: application/json
x-client-id: required
x-authentication-token: required
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "options": {
    "artistSeparation": 5,
    "beginDate": "2015-11-16T20:10:31.083Z",
    "duration": 1440,
    "randomMix": true,
    "titleSeparation": 5
  },
  "queue": [
    {
      "title": "The Honey",
      "duration": 241,
      "collectionId": "49b26477c9a944989bdb64b67a37f336",
      "order": 0,
      "legacy": {
        "trackToken": 1115805
      },
      "artist": {
        "name": "Grace"
      }
    },
    {
      "title": "Over The Rainbow/What A Wonderful World",
      "duration": 285,
      "collectionId": "49b26477c9a944989bdb64b67a37f336",
      "assetId": "927f423ba2a8ae724b32a43446cdcbdc0f8683eb445682de33f26a7e484d14f7",
      "order": 1,
      "legacy": {
        "trackToken": 1054082
      },
      "artist": {
        "name": "Israel Kamakawiwo'ole"
      }
    },
    // results abbreviated
  ]
}

Bulk Collection Details

Retrieve one or more specified collections from the API.

The resource returns a JSON array with objects containing the following properties:

  • collectionId - the identifier for the collection

  • title - the title of the collection

  • modified - the date at which the collection was last modified

  • created - the date at which the collection was created

  • trackCount - the number of tracks contained within the collection

Bulk Collection Details
POST/v2/collections/collectionIds

Retrieve multiple collections from the API.

Example URI

POST https://curio-music-api.apps.playnetwork.com/v2/collections/collectionIds
Request
HideShow
Headers
Content-Type: application/json
x-client-id: required
x-authentication-token: required
Body
[
  "13e5a1d0e47f4043b99d9f5982c0dc47",
  "a713c1e0e47f4043b96f9f5982c0139a"
]
Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  {
    collectionId:"13e5a1d0e47f4043b99d9f5982c0dc47",
    title:"Latin Electronica",
    modified:"2015-04-29T20:22:02.262Z",
    created:"2015-04-29T20:22:02.262Z",
    trackCount: 124
  },
  {
    collectionId:"a713c1e0e47f4043b96f9f5982c0139a",
    title:"Dutch Electronica",
    modified:"2015-04-29T21:22:02.262Z",
    created:"2015-04-29T21:22:02.262Z",
    trackCount: 71
  }
]

Collection Tracks

The collection specific tracks resource provides access to the audio tracks that exist exclusively within a collection.

Collection Tracks

Search and retrieve a paginated and ordered list of tracks inside of a collection from the API. At this time, the collection does not fully support filtering.

The collections tracks resource returns JSON with the following properties:

  • options

    • count - the number of results requested
    • filters - the filters applied
    • sort - the sorts applied
    • start - the starting index from which to retrieve results

  • results - an array of matching results with a length less than or equal to count

  • total - the total number of results matching the query

Retrieve All Collection Tracks
GET/v2/collections/{collectionId}/tracks{?start,count,filters,sort}

Example URI

GET https://curio-music-api.apps.playnetwork.com/v2/collections/c114f4844e6240ef9f458194fd6c2b23/tracks?start=0&count=50&filters=filters[mandatory][startsWith][artist.name]=dj&sort=sort[desc]=modified
URI Parameters
HideShow
collectionId
string (required) Example: c114f4844e6240ef9f458194fd6c2b23
start
number (optional) Example: 0

index of where to start when querying results

count
number (optional) Example: 50

number of results to retrieve

filters
object (optional) Example: filters[mandatory][startsWith][artist.name]=dj

a set of search filters supplied in bracket notation

sort
object (optional) Example: sort[desc]=modified

a set of sorting options supplied in bracket notation

Request
HideShow
Headers
Content-Type: application/json
x-client-id: required
x-authentication-token: required
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "options": {
    "count": 100,
    "filters": {},
    "sort": {},
    "start": 0
  },
  "results": [
    {
      "title": "Have Some Fun (Steve Aoki Edit)",
      "primaryGenre": "DANCE",
      "isrc": "QMRSZ1401150",
      "duration": 621,
      "modified": "2015-05-06T14:56:05.674Z",
      "created": "2015-05-06T14:56:05.674Z",
      "spotify": {
        "uri": "spotify:track:3U4X8dKC6nRLL1Bct6RNgt",
        "lastSearchDate": "2015-05-06T14:56:03.723Z"
      },
      "licensing": [
        {
          "corporateName": "Sony Music",
          "recordCompany": "BMG"
        }
      ],
      "itunes": {
        "url": "https://itunes.apple.com/us/album/have-some-fun-feat.-cee-lo/id906802757?i=906805906&uo=4",
        "collectionName": "Have Some Fun (feat. Cee Lo, Pitbull & Juicy J) [Steve Aoki Edit] - Single",
        "lastSearchDate": "2015-05-06T14:56:03.814Z"
      },
      "echonest": {
        "lastSearchDate": "2015-05-06T14:56:04.079Z"
      },
      "artwork": {
        "cover600": "http://is2.mzstatic.com/image/pf/us/r30/Music4/v4/36/ea/5f/36ea5f86-0b1c-2fdd-6f79-8d6d001fb787/859381011842.600x600-75.jpg",
        "cover100": "http://is2.mzstatic.com/image/pf/us/r30/Music4/v4/36/ea/5f/36ea5f86-0b1c-2fdd-6f79-8d6d001fb787/859381011842.100x100-75.jpg"
      },
      "artist": {
        "artistId": "15031b8a50944f8fbdabc671427e2a73",
        "name": "DJ Felli Fel"
      },
      "amazon": {
        "lastSearchDate": "2015-05-06T14:56:03.961Z"
      },
      "album": {
        "albumId": "66b39939c08943fb8db6cb91333b5beb",
        "releaseYear": 2014,
        "name": "UK Commercial Dance July 14 #2"
      },
      "legacy": {
        "trackEntryDate": "2014-07-14T07:00:00.000Z",
        "trackToken": 1046487
      }
    },
    // results abbreviated
  ],
  "total": 11912
}

Individual Collection Track

Check For Collection Track
HEAD/v2/collections/{collectionId}/tracks/{alias}

Example URI

HEAD https://curio-music-api.apps.playnetwork.com/v2/collections/c114f4844e6240ef9f458194fd6c2b23/tracks/tracktoken:12345
URI Parameters
HideShow
collectionId
string (required) Example: c114f4844e6240ef9f458194fd6c2b23
alias
string (required) Example: tracktoken:12345
Request
HideShow
Headers
Content-Type: application/json
x-client-id: required
x-authentication-token: required
Response  200

Remove track from collection
DELETE/v2/collections/tracks/

Remove track from collection by alias

  • Options
    • order (optional, number) … index of where the track should appear in the track list

Example URI

DELETE https://curio-music-api.apps.playnetwork.com/v2/collections/tracks/
Request
HideShow
Headers
Content-Type: application/json
x-client-id: required
x-authentication-token: required
Response  204

Playlists

The playlists resource provides access to custom collections of audio content specified by consumers of the API. Playlists represent a simple, unordered set of audio content. Playlists are functionaly the same as collections except that they can be created, updated and deleted at will by consumers of the API whereas the collections resource stores hand curated collections of content that published exclusively by PlayNetwork.

All Playlists

Search and retrieve a paginated, filtered and sorted list of playlists from the API.

The search playlists resource returns JSON with the following properties:

  • options

    • count - the number of results requested
    • filters - the filters applied
    • sort - the sorts applied
    • start - the starting index from which to retrieve results

  • results - an array of matching results with a length less than or equal to count

  • total - the total number of results matching the query

Search All Playlists
GET/v2/playlists{?start,count,filters,sort}

Example URI

GET https://curio-music-api.apps.playnetwork.com/v2/playlists?start=0&count=50&filters=filters[mandatory][exact][title]=latin%20electronica&sort=sort[desc]=modified
URI Parameters
HideShow
start
number (optional) Example: 0

index of where to start when querying results

count
number (optional) Example: 50

number of results to retrieve

filters
object (optional) Example: filters[mandatory][exact][title]=latin%20electronica

a set of search filters supplied in bracket notation

sort
object (optional) Example: sort[desc]=modified

a set of sorting options supplied in bracket notation

Request
HideShow
Headers
Content-Type: application/json
x-client-id: required
x-authentication-token: required
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "options": {
    "count": 100,
    "filters": {},
    "sort": {},
    "start": 0
  },
  "results": [
    {
      "collectionId": "7d7d88e131dd45f986e01e0c843536ea",
      "title": "Spa",
      "modified": "2015-07-21T14:10:26.432Z",
      "created": "2015-07-20T17:54:28.402Z",
      "trackCount": 713
    },
    {
      "collectionId": "72fcab788d9a4bd8864c408ce99496ad",
      "title": "Baroque & Chamber",
      "modified": "2015-07-21T14:17:16.282Z",
      "created": "2015-07-13T18:42:24.803Z",
      "trackCount": 848
    },
    // results abbreviated
  ],
  "total": 80
}

Individual Playlists

Retrieve a specific collection from the API.

The playlists resource returns JSON with the following properties:

  • collectionId - the identifier for the playlist - this identifier is named collectionId because playlists are a special type of user defined collection

  • title - the title of the playlist

  • modified - the time at which the playlist was last modified

  • created - the time at which the playlist was created

  • trackCount - the number of tracks contained within the playlist

Playlist Details
GET/v2/playlists/{playlistId}

Retrieve a single playlist from the API.

Example URI

GET https://curio-music-api.apps.playnetwork.com/v2/playlists/c114f4844e6240ef9f458194fd6c2b23
URI Parameters
HideShow
playlistId
string (required) Example: c114f4844e6240ef9f458194fd6c2b23
Request
HideShow
Headers
Content-Type: application/json
x-client-id: required
x-authentication-token: required
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "collectionId": "13e5a1d0e47f4043b99d9f5982c0dc47",
  "title": "Latin Electronica",
  "modified": "2015-04-29T20:22:02.262Z",
  "created": "2015-04-29T20:22:02.262Z",
  "trackCount": 124
}

Create Playlist
POST/v2/playlists/

Create a single playlist in the API.

Example URI

POST https://curio-music-api.apps.playnetwork.com/v2/playlists/
Request
HideShow
Headers
Content-Type: application/json
x-client-id: required
x-authentication-token: required
Body
{
  "title": "Northern Lights Orchestra",
  "tracks": [
    {
      "legacy": {
        "trackToken": 12345
      }
    },
    {
      "legacy": {
        "trackToken": 54321
      }
    }
  ]
}
Response  201
HideShow
Headers
Content-Type: application/json
Body
{
  "collectionId": "13e5a1d0e47f4043b99d9f5982c0dc47",
  "title": "Latin Electronica",
  "modified": "2015-04-29T20:22:02.262Z",
  "created": "2015-04-29T20:22:02.262Z",
  "trackCount": 124
}

Delete Playlist
DELETE/v2/playlists/{playlistId}

Remove a single playlist from the API.

Example URI

DELETE https://curio-music-api.apps.playnetwork.com/v2/playlists/c114f4844e6240ef9f458194fd6c2b23
URI Parameters
HideShow
playlistId
string (required) Example: c114f4844e6240ef9f458194fd6c2b23
Request
HideShow
Headers
Content-Type: application/json
x-client-id: required
x-authentication-token: required
Response  204

Update Playlist
PUT/v2/playlists/

Update an individual playlist in the API.

Example URI

PUT https://curio-music-api.apps.playnetwork.com/v2/playlists/
Request
HideShow
Headers
Content-Type: application/json
x-client-id: required
x-authentication-token: required
Body
{
  "title": "d63a37b243ed4a248dc9b31663d34a00",
  "tracks": [
    {
      "legacy": {
        "trackToken": 12345
      }
    },
    {
      "legacy": {
        "trackToken": 54321
      }
    }
  ]
}
Response  202
HideShow
Headers
Content-Type: application/json
Body
{
  "collectionId": "13e5a1d0e47f4043b99d9f5982c0dc47",
  "title": "Latin Electronica",
  "modified": "2015-04-29T20:22:02.262Z",
  "created": "2015-04-29T20:22:02.262Z",
  "trackCount": 124
}

Playlist Tracks

The playlist specific tracks resource provides access to the audio tracks that exist exclusively within a playlist.

Playlist Tracks

Search and retrieve a paginated and ordered list of tracks inside of a playlist from the API. At this time, the playlist does not fully support filtering.

The playlists tracks resource returns JSON with the following properties:

  • options

    • count - the number of results requested
    • filters - the filters applied
    • sort - the sorts applied
    • start - the starting index from which to retrieve results

  • results - an array of matching results with a length less than or equal to count

  • total - the total number of results matching the query

Retrieve All Playlist Tracks
GET/v2/playlists/{playlistId}/tracks/{?start,count,filters,sort}

Example URI

GET https://curio-music-api.apps.playnetwork.com/v2/playlists/c114f4844e6240ef9f458194fd6c2b23/tracks/?start=0&count=50&filters=filters[mandatory][startsWith][artist.name]=dj&sort=sort[desc]=modified
URI Parameters
HideShow
playlistId
string (required) Example: c114f4844e6240ef9f458194fd6c2b23
start
number (optional) Example: 0

index of where to start when querying results

count
number (optional) Example: 50

number of results to retrieve

filters
object (optional) Example: filters[mandatory][startsWith][artist.name]=dj

a set of search filters supplied in bracket notation

sort
object (optional) Example: sort[desc]=modified

a set of sorting options supplied in bracket notation

Request
HideShow
Headers
Content-Type: application/json
x-client-id: required
x-authentication-token: required
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "options": {
    "count": 100,
    "filters": {},
    "sort": {},
    "start": 0
  },
  "results": [
    {
      "title": "Have Some Fun (Steve Aoki Edit)",
      "primaryGenre": "DANCE",
      "isrc": "QMRSZ1401150",
      "duration": 621,
      "modified": "2015-05-06T14:56:05.674Z",
      "created": "2015-05-06T14:56:05.674Z",
      "spotify": {
        "uri": "spotify:track:3U4X8dKC6nRLL1Bct6RNgt",
        "lastSearchDate": "2015-05-06T14:56:03.723Z"
      },
      "licensing": [
        {
          "corporateName": "Sony Music",
          "recordCompany": "BMG"
        }
      ],
      "itunes": {
        "url": "https://itunes.apple.com/us/album/have-some-fun-feat.-cee-lo/id906802757?i=906805906&uo=4",
        "collectionName": "Have Some Fun (feat. Cee Lo, Pitbull & Juicy J) [Steve Aoki Edit] - Single",
        "lastSearchDate": "2015-05-06T14:56:03.814Z"
      },
      "echonest": {
        "lastSearchDate": "2015-05-06T14:56:04.079Z"
      },
      "artwork": {
        "cover600": "http://is2.mzstatic.com/image/pf/us/r30/Music4/v4/36/ea/5f/36ea5f86-0b1c-2fdd-6f79-8d6d001fb787/859381011842.600x600-75.jpg",
        "cover100": "http://is2.mzstatic.com/image/pf/us/r30/Music4/v4/36/ea/5f/36ea5f86-0b1c-2fdd-6f79-8d6d001fb787/859381011842.100x100-75.jpg"
      },
      "artist": {
        "artistId": "15031b8a50944f8fbdabc671427e2a73",
        "name": "DJ Felli Fel"
      },
      "amazon": {
        "lastSearchDate": "2015-05-06T14:56:03.961Z"
      },
      "album": {
        "albumId": "66b39939c08943fb8db6cb91333b5beb",
        "releaseYear": 2014,
        "name": "UK Commercial Dance July 14 #2"
      },
      "legacy": {
        "trackEntryDate": "2014-07-14T07:00:00.000Z",
        "trackToken": 1046487
      }
    },
    // results abbreviated
  ],
   "total": 11912
}

Add Tracks to Playlist
POST/v2/playlists/{playlistId}/tracks/

Tracks can be added to the playlist individually or as a collection by using POST. The tracks added to the playlist must either contain the assetId property or the legacy.trackToken property - if either of these fields is missing from the supplied tracks, that track will be ignored when performing the add function.

Example URI

POST https://curio-music-api.apps.playnetwork.com/v2/playlists/c114f4844e6240ef9f458194fd6c2b23/tracks/
URI Parameters
HideShow
playlistId
string (required) Example: c114f4844e6240ef9f458194fd6c2b23
Request
HideShow
Headers
Content-Type: application/json
x-client-id: required
x-authentication-token: required
Body
[
  {
    "legacy": {
      "trackToken": 1093301
    }
  },
  {
    "legacy": {
      "trackToken": 846315
    }
  }
]
Response  201
HideShow
Body
[
    {
      "title": "Have Some Fun (Steve Aoki Edit)",
      "primaryGenre": "DANCE",
      "isrc": "QMRSZ1401150",
      "duration": 621,
      "modified": "2015-05-06T14:56:05.674Z",
      "created": "2015-05-06T14:56:05.674Z",
      "spotify": {
        "uri": "spotify:track:3U4X8dKC6nRLL1Bct6RNgt",
        "lastSearchDate": "2015-05-06T14:56:03.723Z"
      },
      "licensing": [
        {
          "corporateName": "Sony Music",
          "recordCompany": "BMG"
        }
      ],
      "itunes": {
        "url": "https://itunes.apple.com/us/album/have-some-fun-feat.-cee-lo/id906802757?i=906805906&uo=4",
        "collectionName": "Have Some Fun (feat. Cee Lo, Pitbull & Juicy J) [Steve Aoki Edit] - Single",
        "lastSearchDate": "2015-05-06T14:56:03.814Z"
      },
      "echonest": {
        "lastSearchDate": "2015-05-06T14:56:04.079Z"
      },
      "artwork": {
        "cover600": "http://is2.mzstatic.com/image/pf/us/r30/Music4/v4/36/ea/5f/36ea5f86-0b1c-2fdd-6f79-8d6d001fb787/859381011842.600x600-75.jpg",
        "cover100": "http://is2.mzstatic.com/image/pf/us/r30/Music4/v4/36/ea/5f/36ea5f86-0b1c-2fdd-6f79-8d6d001fb787/859381011842.100x100-75.jpg"
      },
      "artist": {
        "artistId": "15031b8a50944f8fbdabc671427e2a73",
        "name": "DJ Felli Fel"
      },
      "amazon": {
        "lastSearchDate": "2015-05-06T14:56:03.961Z"
      },
      "album": {
        "albumId": "66b39939c08943fb8db6cb91333b5beb",
        "releaseYear": 2014,
        "name": "UK Commercial Dance July 14 #2"
      },
      "legacy": {
        "trackToken": 1093301
      }
    },
    // results abbreviated
  ]

Delete Tracks From Playlist
DELETE/v2/playlists/{playlistId}/tracks/{alias}

In order to remove an individual track from a playlist, use this resource. The alias parameter supplied must either be the assetId of the track (with no prefix) or the legacy.trackToken of the track formatted as tracktoken:value where value is the value of the legacy.trackToken field.

Example URI

DELETE https://curio-music-api.apps.playnetwork.com/v2/playlists/c114f4844e6240ef9f458194fd6c2b23/tracks/tracktoken:12345
URI Parameters
HideShow
playlistId
string (required) Example: c114f4844e6240ef9f458194fd6c2b23
alias
string (required) Example: tracktoken:12345
Request
HideShow
Headers
Content-Type: application/json
x-client-id: required
x-authentication-token: required
Response  204

Check For Track in Playlist
HEAD/v2/playlists/{playlistId}/tracks/{alias}

Example URI

HEAD https://curio-music-api.apps.playnetwork.com/v2/playlists/c114f4844e6240ef9f458194fd6c2b23/tracks/tracktoken:12345
URI Parameters
HideShow
playlistId
string (required) Example: c114f4844e6240ef9f458194fd6c2b23
alias
string (required) Example: tracktoken:12345
Request
HideShow
Headers
Content-Type: application/json
x-client-id: required
x-authentication-token: required
Response  200

All Tracks

The tracks resource provides access to all audio tracks and the meta data that is available for each of these tracks.

All Tracks

Query and retrieve a paginated list of tracks from the API.

NOTE: The /v2/tracks resource does not support mandatory or optional filters and sort parameters. If mandatory/optional filters or sort parameters are specified, a status code of 409 with an error message will be returned inidicating this functionality is not supported. For filtering and sorting specific tracks, the /v2/collections/{collectionId}/tracks resource must be used instead.

The all tracks resource returns JSON with the following properties:

  • options

    • count - the number of results requested
    • filters - any internal filters applied
    • start - the starting index from which to retrieve results

  • results - an array of matching results with a length less than or equal to count

  • total - the total number of results matching the query

Search All Tracks
GET/v2/tracks{?start,count,filters}

Example URI

GET https://curio-music-api.apps.playnetwork.com/v2/tracks?start=0&count=50&filters=filters[field]=artist.name,title,legacy.trackToken
URI Parameters
HideShow
start
number (optional) Example: 0

index of where to start when querying results

count
number (optional) Example: 50

number of results to retrieve

filters
object (optional) Example: filters[field]=artist.name,title,legacy.trackToken

a set of search filters supplied in bracket notation

Request
HideShow
Headers
Content-Type: application/json
x-client-id: required
x-authentication-token: required
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "options": {
    "count": 100,
    "filters": {},
    "sort": {},
    "start": 0
  },
  "results": [
    {
      "title": "Have Some Fun (Steve Aoki Edit)",
      "primaryGenre": "DANCE",
      "isrc": "QMRSZ1401150",
      "duration": 621,
      "modified": "2015-05-06T14:56:05.674Z",
      "created": "2015-05-06T14:56:05.674Z",
      "spotify": {
        "uri": "spotify:track:3U4X8dKC6nRLL1Bct6RNgt",
        "lastSearchDate": "2015-05-06T14:56:03.723Z"
      },
      "licensing": [
        {
          "corporateName": "Sony Music",
          "recordCompany": "BMG"
        }
      ],
      "itunes": {
        "url": "https://itunes.apple.com/us/album/have-some-fun-feat.-cee-lo/id906802757?i=906805906&uo=4",
        "collectionName": "Have Some Fun (feat. Cee Lo, Pitbull & Juicy J) [Steve Aoki Edit] - Single",
        "lastSearchDate": "2015-05-06T14:56:03.814Z"
      },
      "echonest": {
        "lastSearchDate": "2015-05-06T14:56:04.079Z"
      },
      "artwork": {
        "cover600": "http://is2.mzstatic.com/image/pf/us/r30/Music4/v4/36/ea/5f/36ea5f86-0b1c-2fdd-6f79-8d6d001fb787/859381011842.600x600-75.jpg",
        "cover100": "http://is2.mzstatic.com/image/pf/us/r30/Music4/v4/36/ea/5f/36ea5f86-0b1c-2fdd-6f79-8d6d001fb787/859381011842.100x100-75.jpg"
      },
      "artist": {
        "name": "DJ Felli Fel"
      },
      "amazon": {
        "lastSearchDate": "2015-05-06T14:56:03.961Z"
      },
      "album": {
        "releaseYear": 2014,
        "name": "UK Commercial Dance July 14 #2"
      },
      "legacy": {
        "trackEntryDate": "2014-07-14T07:00:00.000Z",
        "trackToken": 1046487
      }
    },
    // results abbreviated
  ],
  "total": 11912
}

Individual Tracks

Retrieve a specific track from the API.

The tracks resource returns JSON with several properties. Within the properties, the sub elements for spotify, itunes, echonest and amazon may not always be fully populated if no suitable association has been found to those 3rd party catalogs.

  • title - the title of the track

  • primaryGenre - the primary genre determined for the track - this is not always populated

  • isrc - the International Standard Recording Code for the track - this is not always populated

  • duration - the duration, in seconds, of the track

  • modified - the last point in time that meta data for this track was updated

  • created - the time when this track was created in the API

  • spotify - Spotify specific metadata - this is not always populated

    • uri
    • lastSearchDate

  • licensing - an array of information that defines primary rights holders of the content - this is not always populated and is not exhaustive of all rightsholders for a given track

  • itunes - Apple specific metadata - this is not always populated

    • url
    • collectionName
    • lastSearchDate

  • echonest - Echonest specific metadata - this is not always populated

    • artistId
    • songId
    • lastSearchDate

  • artwork

    • cover640 - a 640px wide cover image - this is not always populated
    • cover600 - a 600px wide, 600px tall cover image - this is not always populated
    • cover300 - a 300px wide, 300px tall cover image - this is not always populated
    • cover100 - a 100px wide, 100px tall cover image - this is not always populated

  • artist

    • name - the name of the artist

  • amazon - Amazon specific metadata - this is not always populated

    • asin
    • url
    • lastSearchDate

  • album

    • releaseYear - the year of when the album was released - this is not always populated, particularly for virtual albums created by PlayNetwork curation experts
    • name - the name of the album - this is not always populated and does not always match an actual release by an artist

  • legacy - internally tracked fields denoting information from the PlayNetwork Conductor CMS

    • genre
    • trackEntryDate
    • trackToken

Track Details
GET/v2/tracks/{alias}

Retrieve a single track from the API.

Example URI

GET https://curio-music-api.apps.playnetwork.com/v2/tracks/trackToken:1046487
URI Parameters
HideShow
alias
string (required) Example: trackToken:1046487
Request
HideShow
Headers
Content-Type: application/json
x-client-id: required
x-authentication-token: required
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "title": "Have Some Fun (Steve Aoki Edit)",
  "primaryGenre": "electronic",
  "isrc": "QMRSZ1401150",
  "duration": 621,
  "modified": "2015-05-06T14:56:05.674Z",
  "created": "2015-05-06T14:56:05.674Z",
  "spotify": {
    "uri": "spotify:track:3U4X8dKC6nRLL1Bct6RNgt",
    "lastSearchDate": "2015-05-06T14:56:03.723Z"
  },
  "licensing": [
    {
      "corporateName": "Sony Music",
      "recordCompany": "BMG"
    }
  ],
  "itunes": {
    "url": "https://itunes.apple.com/us/album/have-some-fun-feat.-cee-lo/id906802757?i=906805906&uo=4",
    "collectionName": "Have Some Fun (feat. Cee Lo, Pitbull & Juicy J) [Steve Aoki Edit] - Single",
    "lastSearchDate": "2015-05-06T14:56:03.814Z"
  },
  "echonest": {
    "lastSearchDate": "2015-05-06T14:56:04.079Z"
  },
  "artwork": {
    "cover640": "",
    "cover100": "http://is2.mzstatic.com/image/pf/us/r30/Music4/v4/36/ea/5f/36ea5f86-0b1c-2fdd-6f79-8d6d001fb787/859381011842.100x100-75.jpg"
  },
  "artist": {
    "name": "DJ Felli Fel"
  },
  "amazon": {
    "lastSearchDate": "2015-05-06T14:56:03.961Z"
  },
  "album": {
    "releaseYear": 2014,
    "name": "UK Commercial Dance July 14 #2"
  },
  "legacy": {
    "genre": "electronic",
    "trackEntryDate": "2014-07-14T07:00:00.000Z",
    "trackToken": 1046487
  }
}

Bulk Track Details

Retrieve one or more specified tracks from the API.

The resource returns a JSON array with objects containing the same properties returned for individual tracks.

Bulk Track Details
POST/v2/tracks/trackIds

Retrieve multiple tracks from the API.

Example URI

POST https://curio-music-api.apps.playnetwork.com/v2/tracks/trackIds
Request
HideShow
Headers
Content-Type: application/json
x-client-id: required
x-authentication-token: required
Body
[
  "tracktoken:1046487",
  "tracktoken:1120112"
]
Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "title": "Have Some Fun (Steve Aoki Edit)",
    "primaryGenre": "electronic",
    "isrc": "QMRSZ1401150",
    "duration": 621,
    "modified": "2015-05-06T14:56:05.674Z",
    "created": "2015-05-06T14:56:05.674Z",
    "spotify": {
      "uri": "spotify:track:3U4X8dKC6nRLL1Bct6RNgt",
      "lastSearchDate": "2015-05-06T14:56:03.723Z"
    },
    "licensing": [
      {
        "corporateName": "Sony Music",
        "recordCompany": "BMG"
      }
    ],
    "itunes": {
      "url": "https://itunes.apple.com/us/album/have-some-fun-feat.-cee-lo/id906802757?i=906805906&uo=4",
      "collectionName": "Have Some Fun (feat. Cee Lo, Pitbull & Juicy J) [Steve Aoki Edit] - Single",
      "lastSearchDate": "2015-05-06T14:56:03.814Z"
    },
    "echonest": {
      "lastSearchDate": "2015-05-06T14:56:04.079Z"
    },
    "artwork": {
      "cover640": "",
      "cover100": "http://is2.mzstatic.com/image/pf/us/r30/Music4/v4/36/ea/5f/36ea5f86-0b1c-2fdd-6f79-8d6d001fb787/859381011842.100x100-75.jpg"
    },
    "artist": {
      "name": "DJ Felli Fel"
    },
    "amazon": {
      "lastSearchDate": "2015-05-06T14:56:03.961Z"
    },
    "album": {
      "releaseYear": 2014,
      "name": "UK Commercial Dance July 14 #2"
    },
    "legacy": {
      "genre": "electronic",
      "trackEntryDate": "2014-07-14T07:00:00.000Z",
      "trackToken": 1046487
    }
  },
  {
    "itunes": {
      "lastSearchDate": "2015-09-14T16:58:46.186Z",
      "url": "https://itunes.apple.com/us/album/how-deep-is-your-love/id1001677304?i=1001677305&uo=4",
      "collectionName": "How Deep Is Your Love - Single"
    },
    "album": {
      "name": "MAC - AVAF PROMO JULY 2015 - REQUESTS",
      "entryDate": "2015-07-21T00:00:00.000Z",
      "releaseYear": 2015,
    },
    "tempo": 5,
    "artwork": {
      "cover100": "http://is2.mzstatic.com/image/thumb/Music1/v4/b0/2d/f9/b02df9d7-b92c-04fc-2c43-57bed17b2f59/dj.dkdebfmh.jpg/100x100bb-85.jpg",
      "cover640": "https://i.scdn.co/image/828657bab704cb2359132f978be1ca17ac0a59bc"
    },
    "amazon": {
      "lastSearchDate": "2015-09-14T16:58:46.547Z"
    },
    "echonest": {
      "artistId": "ARJRB241187FB556A3",
      "lastSearchDate": "2015-07-22T06:41:15.017Z",
      "songId": "SOZVMBQ14BB4521F8E"
    },
    "spotify": {
      "lastSearchDate": "2015-09-14T16:58:45.999Z",
      "uri": "spotify:track:4owbJfCN73rJQAgQ7HMBBH",
      "artistUri": "spotify:artist:7CajNmpbOovFoOoasH2HaY"
    },
    "licensing": [
      {
        "recordCompany": "Sony BMG Music Entertainment [UK] Limited",
        "corporateName": "Sony Music"
      }
    ],
    "title": "Pray To God (Calvin Harris Vs. Mike Pickering Hacienda Remix)",
    "duration": 444,
    "primaryGenre": "Dance",
    "artist": {
      "name": "Calvin Harris Feat. Haim",
    },
    "legacy": {
      "trackToken": 1120112,
      "trackEntryDate": "2015-07-21T00:00:00.000Z"
    }
  }
]

Filtering and Sorting

Using object bracket notation, filters and sort parameters can be provided to each resource in the API. The following describes the syntax for the parameters.

filters

The filters object supports the following functions:

  • filters[field]

This can be used to select specific fields to be returned from the API: /v2/tracks?filters[field]=legacy.trackToken,artist.name,title

  • filters[mandatory][beginsWith][field]

Filters resources based on a field value beginning with a specified string: /v2/collections?filters[mandatory][beginsWith][title]=Indie

  • filters[mandatory][contains][field]

Filters resources based on a field value containing a specified string: /v2/stations?filters[mandatory][contains][title]=December

  • filters[mandatory][endsWith][field]

Filters resources based on a field value containing a specified string: /v2/collections?filters[mandatory][endsWith][legacy.conceptName]=us

  • filters[mandatory][exact][field]

Filters resources based on a field value exactly matching the specified string: /v2/collections?filters[mandatory][exact][title]=Reggae

  • filters[mandatory][exists][field]

Filters resources based on a field value existing.

  • filters[mandatory][missing][field]

Filters resources based on a field value missing.

  • filters[mandatory][lt][field]

Filters resources based on a number or date field being less than the specified value.

  • filters[mandatory][lte][field]

Filters resources based on a number or date field being less than or equal to the specified value.

  • filters[mandatory][gt][field]

Filters resources based on a number or date field being greater than the specified value.

  • filters[mandatory][gte][field]

Filters resources based on a number or date field being greater than or equal the specified value.

sort

Sort can be used to specify ascending or descending ordering of items coming back from the API.

  • sort[asc]

Sorts resources in ascending order based on the specified field.

  • sort[desc]

Sorts resources in descending order based on the specified field.

pagination

Results from the API are paginated in all cases… the start and count can be supplied to define which segment of results to return.

  • start

The index at which to start retrieval.

  • count

The number of items to retrieve.

Generated by aglio on 08 Aug 2018