Getting started

tkell edited this page Sep 13, 2010 · 54 revisions

Getting started


06. July 2010

Adding support for key requirements, versioning, and linked partitions:

  • Consumer Key Requirement: a valid consumer key must be supplied, even when only accessing public resources
  • Versioning: requests to /v1 are now active.
  • Linked Partitioning: a request passed with linked_partitioning=1 will have a next-paritition-href field in the response body. This field will contain a link to the next partition of the request.
  • These features are currently only live on sandbox-soundcloud.

21. November 2009

Version 0.4.5 brings support for groups and the resolve api:

  • groups: read only support for groups and it’s tracks, members, moderators, contributors

  • resolver: Resolve almost any soundcloud permalink to an api resource. i.e.: sc_client.resolve(‘’) will return the track object of the specified url.
  • Detailed documentation will follow.

19. November 2009

With version 0.4.2 we switched back to the mojodna oauth gem, since the bug was finally fixed. We also had to switch to to host our gems, since github doesn’t support gem building and hosting anymore. By doing that we renamed jwagener-oauth-active-resource to oauth-active-resource.

September 2009

With the soundcloud-ruby-api-wrapper version 0.4.1 we switched from the official (mojodna) oauth gem to pelle oauth gem (0.3.6) because of an everlasting,unfixed bug in the official gem.

Required Gems


First install all the missing required gems. To install the oauth-active-resource gem you can use:

$ sudo gem install oauth-active-resource -s

Then install the soundcloud api wrapper gem:

$ sudo gem install soundcloud-ruby-api-wrapper -s

Setup OAuth things

Look at to find out, how you setup your OAuth things.

First steps

Let’s start with a simple app. It will find and display the 10 hottest tracks of alltime. You don’t need any OAuth authentication to do this.

require 'rubygems'
gem 'soundcloud-ruby-api-wrapper'
require 'soundcloud'

# Create an anonymous soundcloud client
# if you prefer to work with, replace this with:
# sc_client = Soundcloud.register({:consumer_key => 'Your_Consumer_Key_Here', :site => ""})
sc_client = Soundcloud.register

# Find the 10 hottest tracks
hot_tracks = sc_client.Track.find(:all,:params => {:order => 'hotness', :limit => 10})

# and display their titles
p '==the 10 hottest tracks=='
hot_tracks.each do |track|
  p track.title

To test authentication you can use this small app, which will dispay the name of the logged in user.

require 'rubygems'
gem 'soundcloud-ruby-api-wrapper'
require 'soundcloud'

gem 'oauth'
require 'oauth'

# Create a Soundcloud OAuth consumer token object

# Create an OAuth access token object

# Create an authenticated Soundcloud client, based on the access token
sc_client = Soundcloud.register({:access_token => access_token})

# Get the logged in user 
my_user = sc_client.User.find_me

# Display his full name
p "Hello, my name is #{my_user.full_name}"

Find more examples in these pages: Model Events, Model Users, Model Tracks, Model Playlists, Model Comments.


The Soundcloud API provides 3 different types of sub-resources:

Nested sub-resources

These are directly embedded in the resource. For example a playlist has a track array.


When saving the original resource, the nested array will be saved as well.

playlist.tracks << some_track

Separate sub-resources

These are separated from the original resource.
A Track has the path “/tracks/[TRACK ID]”
This track has a collection of users, which have access to this track, called permissions.
These can be accessed via the path “/tracks/[TRACK ID]/permission”.

In ruby they are accessed like nested resources:


But have to be saved explicitly:

playlist.permissions << some_user

A lot of these collections are partials, that means Soundcloud API will not return more than 50 items per request.
For example the user famous_dj has 120 fans/followers. will only return 50 fans.
To get all fans you have to do something like this:

fans = []
limit = 50
some_fans ={:offset => fans.length, :limit => limit})
fans += some_fans
end while some_fans.length >= limit

The array fans now contains all fans/followers of famous_dj.

‘Single changeable’ separate sub-resources

Some separate collections can’t be saved in a bulk request. Instead each item has to be added or removed explicitly.
For now this only affects the contacts (followees) and favorites of a user.

To add a track to the logged-in users favorites:





track.is_favorite? => true or false

The same works with the contacts of the logged-in user:

another_user.is_contact? => true or false

You can also check if another users follows some user or has a specific favorite:

user.has_contact?(some_user) => true of false 
user.has_favorite?(some_track) => true or false

Linked Partitioning

Linked partitioning can be used to get N resources, then then next N, then then next N, and so on. At the moment, it is only live on, and is opt-in. Set linked_partitioning to 1 to activate it. The response will then have a next-partition-href field, and a get_next_partition() method. For example:

# Connect to SoundCloud
soundcloud = Soundcloud.register({:consumer_key => 'Your_Consumer_Key', :site => ''}) 

# This will request the 10 hottest tracks, with linked partitioning on.
hot_tracks = soundcloud.Track.find(:all, :params => {:limit => 10, :linked_partitioning => 1})

# This will print the title of each track:  the return object acts as Array
hot_tracks.each do |track|
  p track.title

# To get the next partition of tracks:
hot_tracks2 = hot_tracks.get_next_partition(soundcloud.Track)
hot_tracks2.each do |track|
  p track.title

# To loop over all tracks, in sets of 10: 
while hot_tracks != nil
  hot_tracks.each do |track|
    p track.title
  hot_tracks = hot_tracks.get_next_partition(soundcloud.Track)

Note that get_next_partition will return nil if there are no more resources to get. Note also that you must pass the soundcloud object and the desired method to get_next_partition. A request for Users would thus look like: get_next_partition(soundcloud.User)