Methods
For calling conventions and authentication information see the main Web Service API page.
Core
get
Does not require authentication
Fetch one or more objects from Rdio.
Arguments
- keys
- required — a list of keys for the objects to fetch — a list of keys, comma separated
- extras
- optional — a list of additional fields to return — a list, comma separated
- options
- optional — jsonified dictionary of options
Returns
Returns an object whose keys are the keys supplied to the call and whose values are the objects corresponding to those keys. Those objects can be of any Rdio type. Invalid keys will be missing from the result object.
getObjectFromShortCode
Does not require authentication
Return the object that the supplied Rdio short-code is a representation of, or an error if the short-code is invalid.
Arguments
- short_code
- required — the short-code - everything after the http://rd.io/x/
- extras
- optional — a list of additional fields to return — a list, comma separated
Returns
Returns the object that the short-code links to, or an empty object if the short-code is invalid or doesn't link anywhere".
getObjectFromUrl
Does not require authentication
Return the object that the supplied Rdio url is a representation of, or 404 error response if the url doesn't represent an object.
Arguments
- url
- required — the path portion of the url
- extras
- optional — a list of additional fields to return — a list, comma separated
Returns
Returns the object represented at the url, or a 404 error response if the url doesn't point to page representing an object.
Catalog
getAlbumsByUPC
Does not require authentication
Finds and returns albums based on their Universal Product Code (UPC).
Arguments
- upc
- required — the UPC code to search for
- extras
- optional — a list of additional fields to return — a list, comma separated
Returns
A list of Album objects that have the supplied UPC.
getAlbumsForArtist
Does not require authentication
Return the albums by (or featuring) an artist.
Arguments
- artist
- required — the artist — a key
- featuring
- optional — return albums featuring the artist rather than albums credited to the artist — a boolean as either "true" or "false"
- extras
- optional — a list of additional fields to return — a list, comma separated
- start
- optional — the offset of the first result to return — an integer
- count
- optional — the maximum number of results to return — an integer
Returns
Returns an array of Album objects.
getAlbumsForLabel
Does not require authentication
Return the albums for a label.
Arguments
- label
- required — the label — a key
- extras
- optional — a list of additional fields to return — a list, comma separated
- start
- optional — the offset of the first result to return — an integer
- count
- optional — the maximum number of results to return — an integer
Returns
Returns an array of Album objects.
getArtistsForLabel
Does not require authentication
Return the artists for a label.
Arguments
- label
- required — the label — a key
- extras
- optional — a list of additional fields to return — a list, comma separated
- start
- optional — the offset of the first result to return — an integer
- count
- optional — the maximum number of results to return — an integer
Returns
Returns an array of Artist objects.
getTracksByISRC
Does not require authentication
Finds and returns tracks based on their International Standard Recording Code (ISRC).
Arguments
- isrc
- required — the ISRC code to search for
- extras
- optional — a list of additional fields to return — a list, comma separated
Returns
A list of Track objects that have the supplied ISRC.
getTracksForArtist
Does not require authentication
Get all of the tracks by this artist.
Arguments
- artist
- required — the artist — a key
- appears_on
- optional — returns tracks that the artist appears on rather than tracks credited to the artist — a boolean as either "true" or "false"
- extras
- optional — a list of additional fields to return — a list, comma separated
- start
- optional — the offset of the first result to return — an integer
- count
- optional — the maximum number of results to return — an integer
Returns
Returns an array of Track objects.
search
Does not require authentication
Search for artists, albums, tracks, users or all kinds of objects.
Arguments
- query
- required — the search query
- types
- required — types to include in results — a comma separated list of: "Artist", "Album", "Track", "Playlist" or "User"
- never_or
- optional — by default search uses an AND query that falls back to an OR query if there are no results, passing false here will disable that fallback — a boolean as either "true" or "false"
- extras
- optional — a list of additional fields to return — a list, comma separated
- start
- optional — the offset of the first result to return — an integer
- count
- optional — the maximum number of results to return — an integer
Returns
Returns an object containing a results array of objects (the type depends on what was in types) plus a set of type count integer fields: person_count, track_count, album_count, playlist_count, artist_count, and number_results, the grand total.
searchSuggestions
Does not require authentication
Match the supplied prefix against artists, albums, tracks, playlists and people in the Rdio system. Return the first ten matches.
Arguments
- query
- required — the search prefix
- types
- optional — object types to include in results — a comma separated list of: "Artist", "Album", "Track", "Playlist" or "User"
- extras
- optional — a list of additional fields to return — a list, comma separated
Returns
Returns an array of objects matching the search prefix.
Collection
addToCollection
Does require authentication
Add tracks or playlists to the current user's collection.
Arguments
- keys
- required — the tracks and playlists to add to the collection — a list of keys, comma separated
Returns
Always returns true.
getAlbumsForArtistInCollection
Does not require authentication
Get the albums in the user's collection by a particular artist.
Arguments
- artist
- required — the artist — a key
- user
- optional — the collection user — a key
- extras
- optional — a list of additional fields to return — a list, comma separated
- sort
- optional — the sort order — "name" or "releaseDate"
Returns
Returns an array of Album objects.
getAlbumsInCollection
Does not require authentication
Get all of the albums in the user's collection.
Arguments
- user
- optional — the collection user — a key
- start
- optional — the offset of the first result to return — an integer
- count
- optional — the maximum number of results to return — an integer
- sort
- optional — sort by, valid values are: "dateAdded", "playCount", "artist" and "name"
- query
- optional — filter collection albums by this
- extras
- optional — a list of additional fields to return — a list, comma separated
Returns
Returns an array of Album objects.
getArtistsInCollection
Does not require authentication
Get all of the artist in a user's collection.
Arguments
- user
- optional — the user whose collection — a key
- start
- optional — the offset of the first result to return — an integer
- count
- optional — the maximum number of results to return — an integer
- sort
- optional — sort by, only "name" and "playCount" are supported
- query
- optional — filter collection artists by this
- extras
- optional — a list of additional fields to return — a list, comma separated
Returns
Returns an array of Artist objects.
getOfflineTracks
Does require authentication
Returns a list of tracks that the current user has sync'd for offline listening.
Arguments
- start
- optional (default: 0) — the offset of the first result to return — an integer
- count
- optional (default: 10) — the maximum number of results to return — an integer
- extras
- optional — a list of additional fields to return — a list, comma separated
Returns
A list of the user's offline tracks.
getTracksForAlbumInCollection
Does not require authentication
Which tracks on the given album are in the user's collection.
Arguments
- album
- required — the album — a key
- user
- optional — the user whose collection to examine — a key
- extras
- optional — a list of additional fields to return — a list, comma separated
Returns
Returns an array of Track objects.
getTracksForArtistInCollection
Does not require authentication
Which tracks from the given artist are in the user's collection.
Arguments
- artist
- required — the artist — a key
- user
- optional — the user whose collection to examine — a key
- extras
- optional — a list of additional fields to return — a list, comma separated
Returns
Returns an array of Track objects.
getTracksInCollection
Does not require authentication
Get all of the tracks in the user's collection.
Arguments
- user
- optional — the collection user — a key
- start
- optional — the offset of the first result to return — an integer
- count
- optional — the maximum number of results to return — an integer
- sort
- optional — sort by, valid values are: "dateAdded", "playCount", "artist", "album" and "name"
- query
- optional — filter collection tracks by this
- extras
- optional — a list of additional fields to return — a list, comma separated
Returns
Returns an array of Track objects.
removeFromCollection
Does require authentication
Remove tracks or playlists from the current user's collection.
Arguments
- keys
- required — the list of track or playlist keys to remove from the collection — a list of keys, comma separated
Returns
Returns true if the remove succeeds or false if the remove fails.
setAvailableOffline
Does require authentication
Mark tracks or playlists for offline syncing.
Arguments
- keys
- required — the tracks and playlists mark or unmark for offline syncing — a list of keys, comma separated
- offline
- required — pass true to mark the given keys for offline syncing, or false to unmark. — a boolean as either "true" or "false"
Returns
Always returns true.
Playlists
addToPlaylist
Does require authentication
Add a track to a playlist.
Arguments
- playlist
- required — playlist to add to — a key
- tracks
- required — tracks to add to playlist — a list of keys, comma separated
- extras
- optional — a list of additional fields to return — a list, comma separated
Returns
Returns the Playlist object.
createPlaylist
Does require authentication
Create a new playlist in the current user's collection. The new playlist will be returned if the creation is successful, otherwise null will be returned.
Arguments
- name
- required — playlist name
- description
- required — playlist description
- tracks
- required — initial tracks start the playlist off — a list of keys, comma separated
- extras
- optional — a list of additional fields to return — a list, comma separated
Returns
Returns the new Playlist.
deletePlaylist
Does require authentication
Delete a playlist.
Arguments
- playlist
- required — the playlist to delete — a key
Returns
Returns true on success but false on failure.
getPlaylists
Does not require authentication
Returns a user's playlists. If no user is specified then the current user will be used.
Arguments
- user
- optional — the user — a key
- extras
- optional — a list of additional fields to return — a list, comma separated
- ordered_list
- optional — True if the playlists should be returned as an ordered list. — a boolean as either "true" or "false"
Returns
Returns an object containing three arrays of Playlist objects, owned (playlists created by the user), collab (playlists that the user is a collaborator on), and subscribed (playlists that the user has subscribed to).
getUserPlaylists
Does not require authentication
Returns a user's playlist. kind must be owned (the user's playlists), collab (playlists the user collaborates on), or subscribed (playlists the user has subscribed to). sort must be lastUpdated or name.
Arguments
- user
- required — the user — a key
- kind
- optional — the type of playlist, default owned
- sort
- optional — sort order, default lastUpdated
- start
- optional — the offset of the first result to return — an integer
- count
- optional — the maximum number of results to return — an integer
- extras
- optional — a list of additional fields to return — a list, comma separated
Returns
Returns a list containing Playlist objects.
removeFromPlaylist
Does require authentication
Remove items from a playlist by range (index and count). All track keys to remove must be in the tracks list too. This is to prevent accidental overwriting of playlist changes.
Arguments
- playlist
- required — the playlist to modify — a key
- index
- required — the index of the first item to remove — an integer
- count
- required — the number of tracks to remove from the playlist — an integer
- tracks
- required — the keys of the tracks to remove — a list of keys, comma separated
- extras
- optional — a list of additional fields to return — a list, comma separated
Returns
Returns the Playlist object on success or null on failure.
setPlaylistCollaborating
Does require authentication
Start or stop collaborating on this playlist.
Arguments
- playlist
- required — the playlist to set collaborating status on — a key
- collaborating
- required — set the user collaboration status for this playlist — a boolean as either "true" or "false"
Returns
Returns true on success or false on failure.
setPlaylistCollaborationMode
Does require authentication
Set the playlist collaboration mode to allow no collaboration (0), collaboration with all Rdio users (1), or collaboration with Rdio users followed by the playlist owner (2).
Arguments
- playlist
- required — the playlist to modify — a key
- mode
- required — the new mode for the playlist — an integer
Returns
Returns true on success or false on failure.
setPlaylistFields
Does require authentication
Sets the name and description for a playlist.
Arguments
- playlist
- required — playlist to modify — a key
- name
- required — new name for playlist
- description
- required — new description for playlist
Returns
Returns true on success and false on failure.
setPlaylistOrder
Does require authentication
Saves the given order of tracks in a given playlist. The new order must have the same tracks as the previous order (this method may not be used to add/remove tracks).
Arguments
- playlist
- required — playlist to reorder — a key
- tracks
- required — new order of tracks in playlist — a list of keys, comma separated
- extras
- optional — a list of additional fields to return — a list, comma separated
Returns
Returns the Playlist object on success or null on failure.
Comments
Social Network
addFriend
Does require authentication
Add a friend to the current user.
Arguments
- user
- required — the user to add — a key
Returns
Returns true if the add succeeds, false if the add fails.
currentUser
Does require authentication
Get information about the currently logged in user.
Arguments
- extras
- optional — a list of additional fields to return — a list, comma separated
Returns
Returns the currently logged in User.
findUser
Does not require authentication
Find a user either by email address or by their username. Exactly one of email or vanityName must be supplied.
Arguments
- optional — an email address
- vanityName
- optional — a username
- extras
- optional — a list of additional fields to return — a list, comma separated
Returns
Returns a matching User object or null if no user is found.
removeFriend
Does require authentication
Remove a friend from the current user.
Arguments
- user
- required — the user to remove — a key
Returns
Returns true if the remove succeeds, false if the remove fails.
userFollowers
Does not require authentication
Get a list of users following a user.
Arguments
- user
- required — the user — a key
- start
- optional — the offset of the first result to return — an integer
- count
- optional — the maximum number of results to return — an integer
- extras
- optional — a list of additional fields to return — a list, comma separated
- inCommon
- optional — if present, return followers of both the user argument and this user — a key
Returns
A list of users, sorted by descending add time.
userFollowing
Does not require authentication
Get a list of users that a user follows.
Arguments
- user
- required — the user — a key
- start
- optional — the offset of the first result to return — an integer
- count
- optional — the maximum number of results to return — an integer
- extras
- optional — a list of additional fields to return — a list, comma separated
- inCommon
- optional — if present, return friends being followed by both the user argument and this user — a key
Returns
A list of users, sorted by descending add time.
Activity and Statistics
getActivityStream
Does not require authentication
Get the activity events for a user, a user's friends, or everyone on Rdio.
Arguments
- user
- required — the user to retrieve an activity stream for — a key
- scope
- required — the scope of the activity stream, either "user", "friends" or "everyone"
- last_id
- optional — the last_id returned by the last call to getActivityStream - return activity that occurred before this id
- count
- optional — the count of the results to return — an integer
- extras
- optional — a list of additional fields to return — a list, comma separated
Returns
Returns an object containing a last_id property that can be used to walk through activity, a user property that is the User object for the user that was passed in, and an updates array containing a series of updates.
Each update has an owner (a User object for the person who did the activity), a date (an ISO formatted date/time string), an update_type (a number indicating what kind of update occurred), and additional depending on the update_type.
The update_type can be:
0 — track added to collection
1 — track added to playlist
3 — friend added
5 — user joined
6 — comment added to track
7 — comment added to album
8 — comment added to artist
9 — comment added to playlist
10 — track added via match collection
11 — user subscribed to Rdio
12 — track synced to mobile
.
getHeavyRotation
Does not require authentication
Find the most popular artists or albums for a user, their friends or the whole site.
Arguments
- user
- optional — the user, or everyone if this is missing — a key
- type
- optional — "artists" or "albums"
- friends
- optional — the user's friends's heavy rotation instead of the user's — a boolean as either "true" or "false"
- limit
- optional — the maximum number of results to return — an integer
- start
- optional — the offset of the first result to return — an integer
- count
- optional — the maximum number of results to return — an integer
- extras
- optional — a list of additional fields to return — a list, comma separated
Returns
Returns an array of Artist or Album objects (depending on the type argument), ordered by descending popularity.
getNewReleases
Does not require authentication
Return new albums released across a timeframe.
Arguments
- time
- optional — Timeframe, "thisweek", "lastweek" or "twoweeks"
- start
- optional — the offset of the first result to return — an integer
- count
- optional — the maximum number of results to return — an integer
- extras
- optional — a list of additional fields to return — a list, comma separated
Returns
Returns an array of Album objects.
getTopCharts
Does not require authentication
Return the site-wide most popular items for a given type.
Arguments
- type
- required — types to include in results, valid values are "Artist", "Album", "Track", "Playlist"
- start
- optional — the offset of the first result to return — an integer
- count
- optional — the maximum number of results to return — an integer
- extras
- optional — a list of additional fields to return — a list, comma separated
Returns
Returns an array of Artist, Album, Track or Playlist objects, depending on the type argument.
Playback
getPlaybackToken
Does not require authentication
Get an playback token. If you are using this for web playback you must supply a domain.
Arguments
- domain
- optional — the domain that the playback SWF will be embedded in
Returns
Returns a playback token string.
