Spot

A Ruby implementation of the Spotify Meta API.

This gem is used internally at the Radiofy project.

Follow me on Twitter for more info and updates.

The Spot::Search.find_song method returns the first hit.

Spot::Search.find_song("Like Glue")

The find_all_songs method returns a list of Spot::Song objects.

Spot::Search.find_all_songs("Like Glue")

The Spot::Search.find_artist method returns the first hit.

Spot::Search.find_artist("Madonna")

The find_all_artists method returns a list of Spot::Artist objects.

Spot::Search.find_all_artists("Madonna")

The Spot::Search.find_album method returns the first hit.

Spot::Search.find_album("Old Skool Of Rock")

The find_all_albums method returns a list of Spot::Album objects.

Spot::Search.find_all_albums("Old Skool Of Rock")

The prime method makes it possible to fetch the best matching result based on the ingoing argument. It will reject data (songs, artists and albums) that contains any of the these words.

Spot::Search.prime.find_song("Sweet Home Alabama")

All songs in Spotify isn't available everywhere. It might therefore be usefull to specify a location, also know as a territory.

If you for example want to find all songs available in Sweden, then you might do something like this.

Spot::Search.territory("SE").find_song("Sweet Home Alabama")

You can find the complete territory list here.

Sometimes it may be useful to filer ingoing params.
You can filter the ingoing string by using the strip method.

Spot::Search.strip.find_song("3. Who's That Chick ? feat.Rihanna [Singel Version] - (Single)")

This is the string that is being passed to Spot.

"who's that chick ?"

Spot::Search.page(11).find_song("sweet home")

You can easily chain method like this.

Spot::Search.page(11).territory("SE").prime.strip.find_song("sweet home")

As soon as the result or results method is applied to the query a request to Spotify is made.

Here is an example (#result).

>> song = Spot::Search.find_song("sweet home").result

>> puts song.title
=> Home Sweet Home

>> puts song.class
=> Spot::Song

Here is an example (#results).

>> songs = Spot::Search.find_all_songs("sweet home").results
>> puts songs.count
=> 100

Spot::Song, Spot::Artist and Spot::Album shares the following methods.

• popularity (Float) Popularity acording to Spotify. From 0.0 to 1.0.
• href (String) Url for the specific object. Default is a spotify url on this format: spotify:track:5DhDGwNXRPHsMApbtVKvFb. http may be passed as a string, which will return an Spotify HTTP Url.
• available? (Boolean) Takes one argument, a territory. Returns true if the object is accessible in the given region. Read more about it in the Specify a territory section above.
• to_s (String) A string representation of the object.
• valid? (Boolean) Returns true if the object is valid, a.k.a is accessible in the given territory. If no territory is given, this will be true.
• name (String) Same as Spot::Song#title.

Methods available for the Spot::Song class.

• length (Fixnum) Length in seconds.
• title (String) Song title.
• to_s (String) String representation of the object in this format: artist - song.
• artist (Artist) The artist.
• album (Album) The album.

Methods available for the Spot::Artist class.

• name (String) Name of the artist.
• to_s (String) Same as above.

Methods available for the Spot::Album class.

• artist (Artist) The artist.

spot = Spot::Search.find_song("kaizers orchestra")

puts spot.num_results # => 188
puts spot.limit       # => 100
puts spot.offset      # => 0
puts spot.query       # => "kaizers orchestra"

• num_results (Fixnum) The amount of hits.
• limit (Fixnum) The amount of results on each page.
• query (String) The search param that was passed to Spotify.
• offset (Fixnum)

Be aware: Spotify has an request limit set for 10 requests per second.
Which means that you can't just use it like this.

["song1", "song2", ...].each do |song|
  Spot::Search.find_song(song)
  # Do something with the data.
end

Instead use something like Wire to limit the amount of requests per seconds.

require "rubygems"
require "wire"
require "spot"

wires = []
["song1", "song2" ... ].each do |s|
  wires << Wire.new(max: 10, wait: 1, vars: [s]) do |song|
    Spot::Search.find_song(song)
    # Do something with the data.
  end
end

wires.map(&:join)

[sudo] gem install spot

Spot is tested in OS X 10.6.7, 10.7.4 using Ruby 1.8.7, 1.9.2.

Spot is released under the MIT license.