songkickr 0.1.4 → 0.2.0

data/lib/songkickr/artist.rb

@@ -1,13 +1,24 @@
 module Songkickr
+  # A single artist
+  #
+  #  { 
+  #   "uri":"http://www.songkick.com/artists/253846-radiohead",
+  #   "displayName":"Radiohead",
+  #   "id":253846,
+  #   "onTourUntil":"2010-01-01"
+  #  }
+  #
+  # http://www.songkick.com/developer/artist-search
   class Artist
-    attr_accessor :href, :display_name, :id, :uri, :onTourUntil
+    attr_accessor :uri, :display_name, :id, :uri, :on_tour_until
     
+    # Accepts a hash of artist attributes.
     def initialize(artist_hash = {})
-      @href         = artist_hash["href"]
-      @display_name = artist_hash["displayName"]
-      @id			= artist_hash["id"]
-      @uri 			= artist_hash["uri"]
-      @onTourUntil	= artist_hash["onTourUntil"]
+      @uri           = artist_hash["uri"]
+      @display_name  = artist_hash["displayName"]
+      @id            = artist_hash["id"]
+      @uri           = artist_hash["uri"]
+      @on_tour_until = artist_hash["onTourUntil"]
     end
   end
 end

data/lib/songkickr/artist_result.rb

@@ -1,29 +1,32 @@
 module Songkickr
+  # A class to represent the result hash of an Artist search.
   class ArtistResult
-  	attr_accessor :page, :total_entries, :results
+    attr_accessor :page, :total_entries, :results
 
-  	def initialize(result_hash = {})
-  		results_page = result_hash["resultsPage"]
+    # Takes the result hash directly and parses out the page and total entries and finally passes off to the parse_results method to get the results.
+    def initialize(result_hash = {})
+      results_page = result_hash["resultsPage"]
 
-  		if results_page
-  			@page 			= results_page["page"]
-  			@total_entries	= results_page["totalEntries"]
-  			@results 		= parse_results results_page["results"]
-  		end
-  	end
+      if results_page
+        @page          = results_page["page"]
+        @total_entries = results_page["totalEntries"]
+        @results       = parse_results results_page["results"]
+      end
+    end
 
-  	protected
-
-  	def parse_results(results = {})
-  		artists = []
-  		if results.include?("artist")
-  			results["artist"].each do |artist|
-  				artists << Songkickr::Artist.new(artist)
-  			end
-  		end
-
-  		artists
-  	end
+    protected
 
+    # Take the results hash directly and parse the artists into Artist objects.
+    #
+    # Returns an array of Artists.
+    def parse_results(results = {})
+      artists = []
+      if results.include?("artist")
+        results["artist"].each do |artist|
+          artists << Songkickr::Artist.new(artist)
+        end
+      end
+      artists
+    end
   end
-end
+end

data/lib/songkickr/concert_setlist_result.rb

@@ -1,9 +1,12 @@
 module Songkickr
+  # A class to represent the result hash of an Setlist search.
+  #
+  # http://www.songkick.com/developer/setlists
   class ConcertSetlistResult
     attr_accessor :results
     
+    # Takes the result ash and passes it to parse_results
     def initialize(result_hash = {})
-      
       if result_hash["resultsPage"]
         results_page = result_hash["resultsPage"]
       
@@ -17,7 +20,8 @@ module Songkickr
     
     
     protected
-    
+      
+      # Parses the setlist items into an array of SetlistItems
       def parse_results(results = {})
         setlists = []
         if results.include?("setlist")

data/lib/songkickr/event.rb

@@ -1,6 +1,43 @@
 module Songkickr
+  # A single event
+  #
+  #   {
+  #     "displayName": "Vampire Weekend at O2 Academy Brixton (February 16, 2010)",
+  #     "type": "Concert",
+  #     "uri": "http://www.songkick.com/concerts/3037536-vampire-weekend-at-o2-academy-brixton?utm_medium=partner&utm_source=131",
+  #     "venue": {
+  #       "lng": -0.1187418,
+  #       "displayName": "O2 Academy Brixton",
+  #       "lat": 51.4681089,
+  #       "id": 17522
+  #     },
+  #     "location": {
+  #       "lng": -0.1187418,
+  #       "city": "London, UK",
+  #       "lat": 51.4681089
+  #     },
+  #     "start": {
+  #       "time": "19:30:00",
+  #       "date": "2010-02-16"
+  #     },
+  #     "performance": [{
+  #       "artist": {
+  #         "uri": "http://www.songkick.com/artists/288696-vampire-weekend",
+  #         "displayName": "Vampire Weekend",
+  #         "id": 288696,
+  #         "identifier": [{"mbid": "af37c51c-0790-4a29-b995-456f98a6b8c9"}]
+  #       }
+  #       "displayName": "Vampire Weekend",
+  #       "billingIndex": 1,
+  #       "id": 5380281,
+  #       "billing": "headline"
+  #     }],
+  #     "id": 3037536
+  #   }
+  #
+  # http://www.songkick.com/developer/artist-search
   class Event
-    attr_accessor :type, :display_name, :location, :start, :uri, :id, :lat, :lng, :performance, :status, :venue, :tickets_uri
+    attr_accessor :type, :display_name, :location, :start, :uri, :id, :lat, :lng, :performances, :status, :venue, :tickets_uri
     
     def initialize(event_hash)
       @type         = event_hash["type"]
@@ -10,17 +47,19 @@ module Songkickr
       @venue        = Songkickr::Venue.new event_hash["venue"]
       @start        = start_hash_to_datetime event_hash["start"]
       @uri          = event_hash["uri"]
-      @performance  = parse_performance event_hash["performance"]
+      @performances = parse_performance event_hash["performance"]
       @id           = event_hash["id"]
       @tickets_uri  = event_hash["ticketsUri"]
     end
     
     protected
-    
+      
+      # Takes the start hash and turns in into a DateTime object.
       def start_hash_to_datetime(start_hash)
         datetime = DateTime.parse("#{start_hash["date"]} #{start_hash["time"]}")
       end
       
+      # Builds a list of Performance objects.
       def parse_performance(performance_array = nil)
         performances = []
         if performance_array

data/lib/songkickr/event_result.rb

@@ -1,7 +1,9 @@
 module Songkickr
+  # A class to represent the result hash of an Event search.
   class EventResult
     attr_accessor :page, :total_entries, :results
-    
+
+    # Takes the result hash directly and parses out the page and total entries and finally passes off to the parse_results method to get the results.
     def initialize(result_hash = {})
       results_page = result_hash["resultsPage"]
       

data/lib/songkickr/location.rb

@@ -1,19 +1,44 @@
 module Songkickr
+  # A class to represent the hash of a Location.
+  #
+  #   {
+  #     "city":{
+  #       "displayName":"London",
+  #       "country":{
+  #         "displayName":"UK"},
+  #         "lng":-0.128,
+  #         "lat":51.5078
+  #       },
+  #       "metroArea":{
+  #         "uri":"http://www.songkick.com/metro_areas/24426-uk-london",
+  #         "displayName":"London",
+  #         "country":{  "displayName":"UK" },
+  #         "id":24426,
+  #         "lng":-0.128,
+  #         "lat":51.5078
+  #       }
+  #     }
+  #   }
+  #
+  # http://www.songkick.com/developer/location-search
   class Location
-    attr_accessor :city, :lat, :lng
+    attr_accessor :city, :lat, :lng, :metro_area
     
+    # Takes a location hash. Handles the different city hashes from Event and Location
     def initialize(location_hash)
-      if(location_hash["city"].is_a?(String)) # location in Event
+      if location_hash["city"].is_a?(String) # location in Event
         @city = location_hash["city"]
         @lat  = location_hash["lat"]
         @lng  = location_hash["lng"]
-      elsif(location_hash["city"].is_a?(Hash)) # stand-alone Location
+      elsif location_hash["city"].is_a?(Hash) # stand-alone Location
         city_hash = location_hash["city"]
         @city = city_hash["displayName"]
         # some locations have a null lng, lat in city hash, but have non-null in metroArea hash
         @lat  = city_hash["lat"]
         @lng  = city_hash["lng"]
       end
+      
+      @metro_area = location_hash['metro_area']
     end
   end
 end

data/lib/songkickr/location_result.rb

@@ -1,9 +1,11 @@
 module Songkickr
+  # A class to represent the result hash of a Location search.
+  
+  #TODO: very similar to concert_setlist_result, event_result, and artist_result, extract common stuff to module/superclass
   class LocationResult
-    # TODO: very similar to event_result and artist_result,
-    # extract common stuff to module/superclass
     attr_accessor :page, :total_entries, :results
     
+    # Takes the result hash directly and parses out the page and total entries and finally passes off to the parse_results method to get the results.
     def initialize(result_hash = {})
       results_page = result_hash["resultsPage"]
       
@@ -16,7 +18,10 @@ module Songkickr
     
     
     protected
-    
+      
+      # Take the results hash directly and parse the locations into Location objects.
+      #
+      # Returns an array of Locations.
       def parse_results(results = {})
         locations = []
         if results.include?("location")

data/lib/songkickr/performance.rb

@@ -1,11 +1,27 @@
 module Songkickr
+  # A single performance by an artist.
+  #   {
+  #     "artist": {
+  #       "uri": "http://www.songkick.com/artists/288696-vampire-weekend",
+  #       "displayName": "Vampire Weekend",
+  #       "id": 288696,
+  #       "identifier": [{"mbid": "af37c51c-0790-4a29-b995-456f98a6b8c9"}]
+  #     }
+  #     "displayName": "Vampire Weekend",
+  #     "billingIndex": 1,
+  #     "id": 5380281,
+  #     "billing": "headline"
+  #   }
   class Performance
-    attr_accessor :artist, :display_name, :id
+    attr_accessor :artist, :display_name, :id, :billing_index, :billing
     
+    # Takes a the hash of the performance. Parses out an Artist object for the artist.
     def initialize(performance_hash)
-      @artist       = Songkickr::Artist.new performance_hash["artist"]
-      @display_name = performance_hash["displayName"]
-      @id           = performance_hash["id"]
+      @artist        = Songkickr::Artist.new performance_hash["artist"]
+      @display_name  = performance_hash["displayName"]
+      @id            = performance_hash["id"]
+      @billing_index = performance_hash['billingIndex']
+      @billin        = performance_hash['billing']
     end
   end
 end

data/lib/songkickr/remote.rb

@@ -1,4 +1,5 @@
 module Songkickr
+  # Create an instance of the remote class to interact with the Songkick API.
   class Remote
     include HTTParty
     base_uri 'api.songkick.com/api/3.0'
@@ -6,7 +7,8 @@ module Songkickr
     
     attr_reader :api_key
     
-    # Get your api_key found here http://developer.songkick.com
+    # ==== Create a new instance of the remote class to talk to Songkick
+    # Get an API key for your app from http://developer.songkick.com/
     def initialize(api_key = nil)
       @api_key = api_key
       @api_key ||= Songkickr.api_key
@@ -14,105 +16,145 @@ module Songkickr
       self.class.default_params :apikey => @api_key
     end
     
-    
-    # Parameters - http://www.songkick.com/developer/event-search
-    #
-    #     type (concert or festival)
-    #     artists (events by any of the artists, comma-separated)
-    #     artist_name
-    #     artist_id
-    #     venue_id
-    #     setlist_item_name (name of a song which was played at the event – use with artist_id or artist_name)
-    #     min_date
-    #     max_date
-    #     location - see the Songkick website for instructions on how to use the location parameter
-    
+    # ==== Event Search API
+    # http://www.songkick.com/developer/event-search
+    #
+    # === Parameters
+    # * +query+ - A hash of query parameters, see below for options.
+    #
+    # _Example:_ <code>{ :type => 'concert', :artists => 'Coolio' }</code>
+    #
+    # ==== Query Parameters
+    # * +type+ - valid types: concert or festival
+    # * +artists+ - events by any of the artists, comma-separated
+    # * +artist_name+ - plain text name of artist ex. 'As I Lay Dying', 'Parkway Drive', 'Animals As Leaders'
+    # * +artist_id+ - Songkick unique ID for an artist
+    # * +venue_id+ - Songkick unique ID for a venue
+    # * +setlist_item_name+ - name of a song which was played at the event – use with artist_id or artist_name
+    # * +min_date+ - Oldest date for which you want to look for events
+    # * +max_date+ - Most recent date for which you want to look for events
+    # * +location+ - See the Songkick website for instructions on how to use the location parameter http://www.songkick.com/developer/location-search
     def events(query = {})
       path = extract_path_from_query(query)
       result = self.class.get("#{path}/events.json", :query => query)
       Songkickr::EventResult.new result
     end
     
-    
-    # Getting detailed information of a single event
+    # ==== Event API
     # http://www.songkick.com/developer/upcoming-events
-    
+    # 
+    # Getting detailed information of a single event.
+    #
+    # === Parameters
+    # * +event_id+ - Songkick event ID. Extract the event ID either from a previous API call or from the URL of the event page on the website.
     def event(event_id)
       result = self.class.get("/events/#{event_id}.json")
       # and now for some dirrty hack
       Songkickr::Event.new result["resultsPage"]["results"]["event"]
     end
- 
-    # Parameters - http://groups.google.com/group/songkick-api/browse_thread/thread/af15b9a6ad3c3513#
-    #   artist_id - Songkick artist_id, use artist_search to get it
-    #   min_date
-    #   max_date
-    #   per_page
-    #   page
 
+    # ==== Gigography API
+    # http://groups.google.com/group/songkick-api/browse_thread/thread/af15b9a6ad3c3513#
+    #
+    # === Parameters
+    # * +artist_id+ - Songkick artist_id, use artist_search to get it
+    # * +query+ - A hash of query parameters, see below for options.
+    # 
+    # ==== Query Parameters
+    # * +min_date+ - Oldest date for which you want to look for events
+    # * +max_date+ - Most recent date for which you want to look for events
+    # * +per_page+ - Number of items on a page
+    # * +page+ - Number of page
     def gigography(artist_id, query= {})
       result = self.class.get("/artists/#{artist_id}/gigography.json",:query=>query)
       Songkickr::EventResult.new result
     end
 
-    # Parameters - http://www.songkick.com/developer/artist-search
-    #   full_text (full text of a search)
-    # returns artist
-
+    # ==== Artist Search API
+    # Returns Artist objects.
+    #
+    # http://www.songkick.com/developer/artist-search
+    #
+    # === Parameters
+    # * +query+ - Search for artists by name using full text search. Results from Songkick are returned by relevancy.
+    #
+    # ==== Query Parameters
+    # * +artist_name+ - Name of an artist. <em>Ex. 'Lady Gaga', 'Slayer', 'Atmosphere'</em>
     def artist_search(query={})
-        result = self.class.get("/search/artists.json?query=#{query[:artist_name]}", :query=>query)
-        Songkickr::ArtistResult.new result
+      result = self.class.get("/search/artists.json", :query => query)
+      Songkickr::ArtistResult.new result
     end
     
-    # Parameters - http://www.songkick.com/developer/events-for-user
-    #
-    #     attendance (all, im_going, i_might_go) - defaults to im_going
-    #     type (concert or festival)
-    #     artists (events by any of the artists, comma-separated)
-    #     artist_name
-    #     artist_id
-    #     venue_id
-    #     setlist_item_name (name of a song which was played at the event – use with artist_id or artist_name)
-    #     min_date
-    #     max_date
-    #     location - see the Songkick website for instructions on how to use the location parameter
-    
+    # ==== User Events API
+    # http://www.songkick.com/developer/upcoming-events-for-user
+    #
+    # === Parameters
+    # * +username+ - A Songkick username.
+    # * +query+ - A hash of query parameters, see below for options.
+    #
+    # ==== Query Parameters
+    # * +attendance+ (all, im_going, i_might_go) - defaults to im_going
+    # * +type+ (concert or festival)
+    # * +artists+ (events by any of the artists, comma-separated)
+    # * +artist_id+ - Songkick unique ID for an artist
+    # * +venue_id+ - Songkick unique ID for a venue
+    # * +setlist_item_name+ (name of a song which was played at the event – use with artist_id or artist_name)
+    # * +min_date+ - Oldest date for which you want to look for events
+    # * +max_date+ - Most recent date for which you want to look for events
+    # * +location+ - see the Songkick website for instructions on how to use the location parameter
     def users_events(username, query = {})
       result = self.class.get("/users/#{username}/events.json", :query => query)
       Songkickr::EventResult.new result
     end
-    
-    # Metro Area Events (Upcoming) - http://www.songkick.com/developer/upcoming-events-for-metro-area
-    
+
+    # ==== Metro Area Events (Upcoming)
+    # Returns an array of Events.
+    #
+    # http://www.songkick.com/developer/upcoming-events-for-metro-area
+    #
+    # === Parameters
+    # * +metro_area_id+ - Songkick unique ID for metro areas. Use location_search to find a metro area ID.
+    # * +query+ - A hash of query parameters, see below for options.
+    #
+    # ==== Query Parameters
+    # * +page+ - Page number
+    # * +per_page+ - Number of results per page, max 50.
     def metro_areas_events(metro_area_id, query = {})
       result = self.class.get("/metro_areas/#{metro_area_id}/calendar.json", :query => query)
       Songkickr::EventResult.new result
-    end  
+    end
     
-    # Parameters - http://www.songkick.com/developer/setlists
+    # ==== Concert Setlists API
+    # http://www.songkick.com/developer/setlists
     #
-    #     event_id
-    
+    # === Parameters
+    #
+    # * +event_id+ - Songkick event ID. Extract the event ID either from a previous API call or from the URL of the event page on the website.
     def concert_setlists(event_id)
       result = self.class.get("/events/#{event_id}/setlists.json")
       Songkickr::ConcertSetlistResult.new result
     end
     
-    # Parameters - http://www.songkick.com/developer/location-search
+    # ==== Location Search API
+    # http://www.songkick.com/developer/location-search
     #
-    #     location - 'geo:{lat,lng}' string
-    #     query - name of location to search for
-    
+    # === Parameters
+    # * +query+ - A hash of query parameters, see below for options.
+    #
+    # ==== Query Parameters
+    # * +location+ - 'geo:{lat,lng}' string <em>Ex. 'geo:{-0.128,51.5078}'</em>
     def location_search(query = {})
-      result = self.class.get("/search/locations.json",:query=>query)
+      result = self.class.get("/search/locations.json", :query => query)
       Songkickr::LocationResult.new result
     end
     
-    private
     
-    def extract_path_from_query(query = {})
-      mbid = query.delete :mbid
-      "/artists/mbid:#{mbid}" if mbid
-    end
+    private
+      
+      # Given a query, look for an mbid key and return a path to access it.
+      def extract_path_from_query(query = {})
+        mbid = query.delete :mbid
+        "/artists/mbid:#{mbid}" if mbid
+      end
   end
 end

data/lib/songkickr/setlist.rb

@@ -1,7 +1,26 @@
 module Songkickr
+  #   A single set list by an artist.
+  #
+  #   {
+  #     "displayName": "N.E.R.D. at Glastonbury Festival 2009",
+  #     "artist": {
+  #       "uri": "http://www.songkick.com/artists/387012-nerd?utm_source=791&utm_medium=partner"
+  #       "identifier": [
+  #         {
+  #           "href": "http://api.songkick.com/api/3.0/artists/mbid:3fb49f5a-fdc0-4789-9c84-22b38b3f3cb5.json"
+  #           "mbid": "3fb49f5a-fdc0-4789-9c84-22b38b3f3cb5"
+  #         }
+  #       ]
+  #       "displayName": "N.E.R.D."
+  #       "id": 387012
+  #     },
+  #     "id": 9511,
+  #     "setlistItem": []
+  #   }
   class Setlist
     attr_accessor :event, :setlist_items, :artist, :playlist_uri, :display_name, :id
     
+    # Takes the setlist hash and parses out an Event and Artist and an array of SetlistItems.
     def initialize(setlist_hash)
       @event         = Songkickr::Event.new setlist_hash["event"]
       @setlist_items = parse_setlist_items setlist_hash["setlistItem"]
@@ -13,6 +32,7 @@ module Songkickr
     
     protected
       
+      # Takes the array of setlist items and create SetLists
       def parse_setlist_items(setlist_item_array = nil)
         setlist_items = []
         if setlist_item_array

data/lib/songkickr/setlist_item.rb

@@ -1,7 +1,13 @@
 module Songkickr
+  # A single set list item.
+  #    {
+  #      encore: 0
+  #      name: "Anti Matter "
+  #    }
   class SetlistItem
     attr_accessor :encore, :name
     
+    # Takes the set list item hash and parses a boolean out for encore.
     def initialize(setlist_item_hash)
       @encore = !!setlist_item_hash["encore"]
       @name   = setlist_item_hash["name"]

data/lib/songkickr.rb

@@ -16,21 +16,34 @@ require dir + '/songkickr/concert_setlist_result'
 require dir + '/songkickr/remote'
 require dir + '/songkickr/artist_result'
 
-class APIKeyNotSet < StandardError; 
+class APIKeyNotSet < StandardError;
+  # Warns of missing API key
   def to_s
     'API key not set!'
   end
 end
 
 module Songkickr
-  
-  # Get your API key from http://developer.songkick.com/
+  # Returns the Songkick API key
+  # In order to use the Songkick API, you must have a Songkick API (their rule, not mine).
+  # Get an API key for your app from http://developer.songkick.com/
+  # 
+  # ==== Example
+  #
+  #   require 'songkickr'
+  #   remote = Songkickr::Remote.new XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+  #   remote.api_key
+  #   XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   def self.api_key
     raise APIKeyNotSet if @api_key.nil?
 
     @api_key
   end
 
+  # Set the API key. In the event you need to set the API key after initializing the the remote.
+  # === Parameters
+  #
+  # * +api_key+ - A developer key from Songkick. Get an API key for your app from http://developer.songkick.com/
   def self.api_key=(api_key)
     @api_key = api_key
   end