API/Content Access Protocol Examples

From ickStream Wiki
Jump to: navigation, search

Contents

Examples of usage with artist/album/tracks based service

Retrieving top level menus

To retrieve top level item lists available in the service

NOTE! This part is under construction and shouldn't be trusted at the moment

{
	"jsonrpc": 2.0,
	"id": 123,
	"method": "findItems",
	"params": {
		"contextId": "myMusic",
		"type": "menu"
	}
}

Which could result in a repsonse like:

{
	count = 2
	items = [
		{
			"id": "soundcloud:myMusic",
			"text": "My Library",
			"type": "menu",
		},
		{
			"id": "soundcloud:myMusic/artists",
			"text": "Artists",
			"type": "menu"
		},
		{
			"id": "soundcloud:myMusic/albums",
			"text": "Albums",
			"type": "menu"
		},
		{
			"id": "soundcloud:myMusic/tracks",
			"text": "Tracks",
			"type": "menu"
		},
		{
			"id": "soundcloud:top100",
			"text": "Top 100",
			"type": "menu",
		},
		{
			"id": "soundcloud:top100/artists",
			"text": "Top 100 Artists",
			"type": "menu",
			"parentNode": "soundcloud:top100"
		},
		{
			"id": "soundcloud:top100/tracks",
			"text": "Top 100 Tracks",
			"type": "menu",
			"parentNode": "soundcloud:top100"
		}
	]
}

Which typically would result in a menu like

* My Music
  * Artists
  * Albums
  * Tracks
* Top 100
  * Top 100 Artists
  * Top 100 Tracks

But it's up to the controller if it likes to use the server provided menu or not.

Retrieving sub menus/content

Examples of usage of findItems

To retrieve a list of all artists available in my favorite artists, albums, tracks in the service

{
	"jsonrpc": 2.0,
	"id": 123,
	"method": "findItems",
	"params": {
		"contextId": "myMusic",
		"type": "artist"
	}
}

Which could result in a response like:

{
	count = 2
	},
	items = [
		{
			"id": "soundcloud:artist:contributor1",
			"text": "First Artist",
			"type": "artist",
			"tracks" {
				"contextId": "myMusic",
				"artistId": "soundcloud:artist:contributor1",
				"type": "track"
			}
		},
		{
			"id": "soundcloud:artist:contributor2",
			"text": "Second Artist",
			"type": "artist",
			"tracks" {
				"contextId": "myMusic",
				"artistId": "soundcloud:artist:contributor2",
				"type": "track"
			}
		}
	]
}

To retrieve a list of all tracks available in my favorite artists, albums, tracks in the service where "First Artist" is involved:

{
	"jsonrpc": 2.0,
	"id": 123,
	"method": "findItems",
	"params": {
		"contextId": "soundcloud:myMusic",
		"artistId": "soundcloud:artist:contributor1",
		"type":"track"
	}
}

Which could result in a response like:

{
	count = 2,
	items = [
		{
			"id": ""soundcloud:track:track1",
			"text": "1. A nice track",
			"type": "track",
			"streamingRefs": [
				< streaming references, explained separately >,
			],
			"itemAttributes": {
				< model data, explained separately >
			}
		},
		{
			"id": ""soundcloud:track:track2",
			"text": "2. Another nice track",
			"type": "track",
			"streamingRefs": [
				< streaming references, explained separately >,
			],
			"itemAttributes": {
				< model data, explained separately >
			},
		}
	]
}

Examples of usage of findItems for internet radio station service

Retrieve top level menus

Retrieve top level items for RadioTime

This sample is based on [1]


{
    "jsonrpc": 2.0,
    "id": 1,
    "method": "findItems",
    "params": {
        "contextId": "allRadio",
        "type": "menu"
    }
}

Which gives the response:

{
  "jsonrpc" : "2.0",
  "id" : "1",
  "result" : {
    "count" : 8,
    "countAll" : 8,
    "offset" : 0,
    "items" : [ {
      "id" : "radiotime:allRadio",
      "text" : "Internet Radio"
    }, {
      "id" : "radiotime:menu:c=local",
      "parentNode" : "radiotime:allRadio",
      "text" : "Local Radio",
      "type" : "menu",
    },
 
     ...
 
     {
      "id" : "radiotime:menu:id=r0",
      "parentNode" : "radiotime:allRadio",
      "text" : "By Location",
      "type" : "menu",
    } ]
  }
}

Browsing into "Internet Radio/By Location":

{
    "jsonrpc": 2.0,
    "id": 1,
    "method": "findItems",
    "params": {
         "menuId": "radiotime:menu:id=r0"
    }
}

Which gives the response:

{
  "jsonrpc" : "2.0",
  "id" : "1",
  "result" : {
    "count" : 8,
    "countAll" : 8,
    "offset" : 0,
    "items" : [ {
      "id" : "radiotime:menu:id=r101215",
      "text" : "Africa",
      "type" : "menu",
    },
 
      ...
 
      {
      "id" : "radiotime:menu:id=r101217",
      "text" : "Europe",
      "type" : "menu",
    } ]
  }
}

Navigating into "Internet Radio/Europe/Germany/Berlin"

{
    "jsonrpc": 2.0,
    "id": 1,
    "method": "findItems",
    "params": {
         "menuId": "radiotime:menu:id=r100772"
    }
}

Some things to note:

  • The "radiotime:menu:id=r100772" value is found in the id attribute of the parent menu for "Germany", it's just not displayed in this sample to save some space.

The response would be something like:

{
  "jsonrpc" : "2.0",
  "id" : "1",
  "result" : {
    "count" : 68,
    "countAll" : 68,
    "offset" : 0,
    "items" : [ {
      "id" : "radiotime:menu:id=r100772.stations",
      "text" : "All Stations",
      "type" : "menu"
    }, {
      "id" : "radiotime:radio:id=s126577",
      "parentNode" : "radiotime:menu:id=r100772.stations",
      "text" : "88vier 88.4 (Public)",
      "type" : "stream",
      "image" : "http://radiotime-logos.s3.amazonaws.com/s126577q.png",
      "streamingRefs" : [ {
        "format" : "mp3",
        "url" : "http://opml.radiotime.com/Tune.ashx?id=s126577"
      } ]
    },
 
      ...
 
     {
      "id" : "radiotime:menu:id=r100772.pivotGenre",
      "text" : "By Genre",
      "type" : "menu"
    },
 
      ...
 
       {
      "id" : "radiotime:menu:id=r100772&filter=g22",
      "parentNode" : "radiotime:menu:id=r100772.pivotGenre",
      "text" : "World",
      "type" : "menu",
    }, {
      "id" : "radiotime:menu:id=r100772&filter=g40",
      "parentNode" : "radiotime:menu:id=r100772.pivotGenre",
      "text" : "World Talk",
      "type" : "menu",
    } ]
  }
}

Some things to note:

  • The menu combines:
    • hierarchical items like "All Stations" and "By Genre"
    • with "By Genre/World" and "By Genre/World Talk"
    • with internet radio stream items like "All Stations/88vier 88.4 (Public)"
  • type=stream is used instead of type=track for the streamable items since this is a continuous stream and not a single track

Retrieving a single item

Examples of usage of getItem

To retrieve a single deezer album

{
     "jsonrpc": "2.0",
     "id": 12354,
     "method": "getItem",
     "params": {
          "contextId": "allMusic",
          "itemId":"deezer:album:75046"
     }
}

Which results in a response like:

{
   "jsonrpc" : "2.0",
   "id" : 12354,
   "result" :
      {
         "id" : "deezer:album:75046",
         "text" : "Super Colossal",
         "type" : "album",
         "image" : "http://api.deezer.com/2.0/album/75046/image",
         "itemAttributes" :
            {
               "id" : "deezer:album:75046",
               "name" : "Super Colossal",
               "image" : "http://api.deezer.com/2.0/album/75046/image",
               "mainArtists" :
                  [
                     {
                        "id" : "deezer:artist:496",
                        "name" : "Joe Satriani"
                     }
                  ]
            }
      }
}

To retrieve a single deezer album which doesn't exist in the myMusic context

{
     "jsonrpc": "2.0",
     "id": 12354,
     "method": "getItem",
     "params": {
          "contextId": "myMusic",
          "itemId":"deezer:album:75046"
     }
}

Which if the album doesn't exist results in a reply like:

{
    "jsonrpc": "2.0",
    "id":12354
}


Model attribute examples

Below follows some sample of the *itemAttributes* structure for various item types. (The values are just dummy data at the moment because we haven't found a suitable reference sample yet)

Model attributes for an artist

"itemAttributes": {
	"id": "spotify:artist:composer1",
	"name": "Wolfgang Amadeus Mozart"
}

Model attributes for an album

"itemAttributes": {
	"id": "spotify:album:yyy",
	"name:" "Some album",
	"image": "http://somehost/somealbum.jpg",
}

Model attributes for a track

"itemAttributes": {
	"id": "spotify:track:xxx",
	"name": "Some track",
	"image": "http://somehost/sometrack.jpg",
	"trackNumber": 1,
	"disc": "A",
	"album": {
		"id": "spotify:album:yyy",
		"name:" "Some album",
		"image": "http://somehost/somealbum.jpg",
		"year": "2010",
		"mainArtists": [
			{
				"id": "spotify:artist:artist1",
				"name": "Some famous classical soloist"
			}
		],
	},
	"mainArtists": [
		{
			"id": "spotify:artist:artist1",
			"name": "Some famous classical soloist"
		}
	],
	"composer": [
		{
			"id": "spotify:artist:composer1",
			"name": "Wolfgang Amadeus Mozart"
		}
	],
	"conductor": [
		{
			"id": "spotify:artist:conductor1",
			"name": "Some conductor"
		}
	],
	"performers": [
		{
			"id": "spotify:artist:orchestra1",
			"name": "Some orchestra"
		}
	],
	"year": "2010",
	"categories": [
		{
			"id": "spotify:category.genre:classical",
			"categoryType": "genre",
			"name": "Classical"
		},
		{
			"id": "spotify:category.genre:chamber",
			"categoryType": "genre",
			"name": "Chamber Music"
		}
	]
}

Model attributes for a genre

{
	"id": "spotify:category.genre:classical",
	"categoryType": "genre",
	"name": "Classical"
}

Model attributes for a playlist

{
	"id": "spotify:playlist:playlist1",
	"playlistType": "static",
	"name": "My Classical Playlist"
},
Personal tools
Namespaces

Variants
Actions
Navigation
Toolbox