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.

How to use

Find a song

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

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

Find all songs

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

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

Find an artist

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

Spot::Search.find_artist("Madonna")

Find all artists

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

Spot::Search.find_all_artists("Madonna")

Find an album

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

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

Find all albums

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

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

Find best match

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")

Specify a territory

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.

Filter ingoing arguments

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 ?"

Specify a page

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

Combine methods

You can easily chain method like this.

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

Data to work with

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

Base

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.

Song

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.

Artist

Methods available for the Spot::Artist class.

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

Album

Methods available for the Spot::Album class.

• artist (Artist) The artist.

Spot

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)

Request limit!

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)

How do install

[sudo] gem install spot

Requirements

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

License

Spot is released under the MIT license.