Skyjam API

dpogue edited this page Apr 8, 2012 · 1 revision
Clone this wiki locally

The Skyjam service API is used by the Google Play Music application for Android. It is a JSON API that provides access to songs and playlists.

This is unofficial, and not otherwise documented by Google. Parts of this were originally posted at http://dpogue.ca/gmusic.html.

Authenticating

The service API uses Google's ClientLogin for authentication. This process is documented fairly thoroughly in http://code.google.com/apis/accounts/docs/AuthForInstalledApps.html and we can copy their sample requests exactly, aside from the value of the service parameter.

The service parameter value for Skyjam is sj

Using cURL, I was able to get an auth token with the following command:

curl -d accountType=GOOGLE \
     -d Email=jondoe@gmail.com \
     -d Passwd=north23AZ \
     -d service=sj \
     https://www.google.com/accounts/ClientLogin

The response should contain 3 values, SID, LSID, and Auth. We need the Auth token value for authenticating our API requests.

Making a request

According to the URIs from the Android client, the base for API requests is https://www.googleapis.com/sj/v1beta1/. All requests return JSON data, matching the definitions below.

When making a request, we need to include the Auth token as an HTTP header. Using cURL, that looks like this:

curl --header "Authorization: GoogleLogin auth=YOUR_AUTH_TOKEN" \
     https://www.googleapis.com/sj/v1beta1/tracks

If everything is successful, you should get back a JSON response containing all of the metadata for all of your tracks.

JSON Models

TrackFeed

This stores a (partial) list of tracks, and sometimes a token for requesting the rest of the list.

Key Meaning
nextPageToken A token which can be used to fetch the next page of tracks. This is only present if there are more than 5000 tracks in the library.
data A TrackFeedData object.

TrackFeedData

This stores a list of tracks.

Key Meaning
items A JSON array of Track objects

Track

This model stores the metadata associated with a single track.

Key Meaning
album The album name
albumArtRef A JSON array of AlbumArtRef objects
albumArtist The name of the album artist
albumId The internal ID of the album (only present if bought from the store?)
artist The artist name
beatsPerMinute The number of beats per minute
comment A comment
composer The composer name
creationTimestamp A timestamp representing the track's creation on the server
discNumber The disc number
durationMillis The duration of the track in milliseconds
estimatedSize The estimated size of the track (in bytes? kilobytes?)
genre The genre
deleted Boolean indicating whether the track has been deleted
lastModifiedTimestamp Timestamp of the last modificaton
playCount The number of times the track has been played
rating The 1-5 rating (as a string, not an integer!)
id The server ID of the track (also called RemoteID sometimes)
storeId The ID of the track in the store (only present for store bought tracks)
title The track title
totalDiscCount The total number of discs
trackNumber The track number
trackType The type of track (certain values indicate it's a store bought track)
year The year

PlaylistFeed

This stores a (partial) list of playlists, and sometimes a token for requesting the rest of the list.

Key Meaning
nextPageToken A token which can be used to fetch the next page of playlists.
data A PlaylistFeedData object.

PlaylistFeedData

This stores a list of playlists.

Key Meaning
items A JSON array of Playlist objects

Playlist

This stores the information about a playlist.

Key Meaning
creationTimestamp The timestamp of when the playlist was created.
deleted Boolean indicating whether the playlist has been deleted.
lastModifiedTimestamp The timestamp of when the playlist was last modified.
name The name of the playlist.
id The server ID of the playlist.
type "USER_GENERATED" or "MAGIC"

Requests

All POST requests must set the Content-Type to application/json!

Tracks

Get the list of tracks

GET https://www.googleapis.com/sj/v1beta1/tracks

Returns: TrackFeed

Get the rest of the tracks using the continuation token

POST https://www.googleapis.com/sj/v1beta1/trackfeed

Returns: TrackFeed

The body is a JSON object with the following key:

Key Meaning
start-token The value of the nextPageToken from the TrackFeed

Get a single track

GET https://www.googleapis.com/sj/v1beta1/tracks/<track ID>

Returns: Track

Playlists

Get a list of all playlists

GET https://www.googleapis.com/sj/v1beta1/playlists

Returns: PlaylistFeed

Get the rest of the playlists using the continuation token

POST https://www.googleapis.com/sj/v1beta1/playlistfeed

Returns: PlaylistFeed

The body is a JSON object with the following key:

Key Meaning
start-token The value of the nextPageToken from the PlaylistFeed

Get a single playlist

GET https://www.googleapis.com/sj/v1beta1/playlists/<playlist ID>

Returns: Playlist