spotify-metadata 0.1.0

data/lib/spotify.rb

@@ -0,0 +1,174 @@
+require 'httparty'
+require 'ostruct'
+
+# Public: Various methods for interacting with the Spotify Metadata API. Please
+# read the Terms of Use for this API (http://is.gd/0Mcl04) before using it.
+#
+# Examples
+# 
+#   require 'spotify'
+#   
+#   artists = Spotify.search_artist 'Radiohead'
+#   puts artists.first.name # => 'Radiohead'
+#   
+#   album = Spotify.search_album('The King of Limbs').first
+#   puts "#{album.artist.name} - #{album.name}" # => Radiohead - Kid A
+module Spotify
+  include HTTParty
+  base_uri 'ws.spotify.com'
+  format   :json
+  headers  'Accept' => 'application/json' # Spotify API prefers Accept headers.
+  
+  # Internal: The version Integer of Spotify's API.
+  API_VERSION = 1
+  
+  # Public: Searches the Spotify API for artists.
+  #
+  # name    - The name String of the artist.
+  # options - The Hash options send along with the request (default: {}).
+  #           :page - The page of the result set (optional).
+  #
+  # Returns nil or an Array of Spotify::Artist objects.
+  def self.search_artist(name, options = {})
+    self.search :artist, options.merge(:q => name)
+  end
+  
+  # Public: searches the Spotify API for albums.
+  #
+  # name    - The name String of the album.
+  # options - The Hash options send along with the request (default: {}).
+  #           :page - The page of the result set (optional).
+  #
+  # Returns nil or an Array of Spotify::Album objects.
+  def self.search_album(name, options = {})
+    self.search :album, options.merge(:q => name)
+  end
+  
+  # Public: searches the Spotify API for tracks.
+  #
+  # name    - The name String of the track.
+  # options - The Hash options send along with the request (default: {}).
+  #           :page - The page of the result set (optional).
+  #
+  # Returns nil or an Array of Spotify::Track objects.
+  def self.search_track(name, options = {})
+    self.search :track, options.merge(:q => name)
+  end
+  
+  # Public: Looks up an Spotify artist URI.
+  #
+  # uri    - The Spotify URI String that needs to be lookup up.
+  # extras - A Symbol that define the detail level expected in the response
+  #          (default: nil).
+  #          :album       - request basic information about all the albums the 
+  #                         artist is featured in.
+  #          :albumdetail - request detailed information about all the albums 
+  #                         the artist is featured in
+  #
+  # Returns nil or an Spotify::Artist object.
+  def self.lookup_artist(uri, extras = nil)
+    query = extras.nil? ? { :uri => uri } : { :uri => uri, :extras => extras }
+    
+    artist = Artist.new self.lookup(query)['artist']
+    artist.albums.map! { |album| Album.new album['album'] } if extras
+    
+    artist
+  end
+
+  # Public: Looks up an Spotify album URI.
+  #
+  # uri    - The Spotify URI String that needs to be lookup up.
+  # extras - A Symbol that defines the detail level expected in the response 
+  #          (default: nil).
+  #          :track       - request basic information about all tracks in the
+  #                         album.
+  #          :trackdetail - request detailed information about all tracks in the
+  #                         album.
+  #
+  # Returns nil or an Spotify::Album object.
+  def self.lookup_album(uri, extras = nil)
+    query = extras.nil? ? { :uri => uri } : { :uri => uri, :extras => extras }
+    
+    album = Album.new self.lookup(query)['album']
+    album.tracks.map! { |track| Track.new track } if extras
+    
+    album
+  end
+
+  # Public: Looks up an Spotify track URI.
+  #
+  # uri    - The Spotify URI String that needs to be lookup up.
+  #
+  # Returns nil or an Spotify::Track object.  
+  def self.lookup_track(uri)
+    Track.new self.lookup(:uri => uri)['track']
+  end
+  
+  # Internal: Represents an artist.
+  class Artist < OpenStruct
+  end
+  
+  # Internal: Represents an album.
+  class Album < OpenStruct
+    # Public: Gets the artists.
+    #
+    # Returns an Array of Spotify::Artist objects.
+    def artists
+      super.nil? ? super : super.map { |artist| Artist.new artist }
+    end
+    
+    # Public: Gets the artist of artists.
+    #
+    # Returns an Array of Spotify::Artist objects or a Spotify::Artist object
+    # if only one artist was returned.
+    def artist
+      if artists.nil?
+        Artist.new :name => super
+      elsif artists.size > 1
+        artists
+      else
+        artists.first
+      end
+    end
+  end
+  
+  # Internal: Represents a track.
+  class Track < Album
+    # Public: Gets the album.
+    #
+    # Returns a Spotify::Album object.
+    def album
+      Album.new super
+    end
+  end
+
+private
+
+  # Internal: Performs a search query.
+  #
+  # method - The API method Symbol that needs to be called.
+  # query  - The query Hash that needs to be passed.
+  #
+  # Returns nil or an Array of artist, album or track objects.
+  def self.search(method, query)
+    result = get "/search/#{API_VERSION}/#{method}", :query => query
+    
+    items = result[method.to_s + 's']
+    return if items.nil? || items.empty?
+    
+    items.map do |item|
+      # TODO: Replace hyphens with underscores, so OpenStruct can use them as
+      # methods.
+      self.const_get(method.to_s.capitalize).new item
+    end
+  end
+  
+  # Internal: Performs a lookup query.
+  #
+  # query  -
+  #
+  # Returns
+  def self.lookup(query)
+    get "/lookup/#{API_VERSION}/", :query => query
+  end
+end

metadata

@@ -0,0 +1,56 @@
+--- !ruby/object:Gem::Specification
+name: spotify-metadata
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- Paul Brickfeld
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-01-25 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: httparty
+  requirement: &2152099480 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.8.1
+  type: :runtime
+  prerelease: false
+  version_requirements: *2152099480
+description: Search Spotify's Metadata API using Ruby.
+email: theboss@nearupon.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/spotify.rb
+homepage: https://github.com/britishtea/spotify
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.13
+signing_key: 
+specification_version: 3
+summary: Search Spotify's Metadata API using Ruby.
+test_files: []