bandsintown 0.1.4 → 0.2.0

data/History.txt

@@ -1,3 +1,11 @@
+== 0.2.0 2010-06-03
+* Added Events - Create API method (Bandsintown::Event.create)
+
+== 0.1.5 2010-04-06
+* Added Venues - Events API method (Bandsintown::Venue#events)
+* Added Venues - Search API method (Bandsintown::Venues.search)
+* Refactored Bandsintown::Venue initialization
+
 == 0.1.4 2010-03-02
 * Added Events - On Sale Soon API method (Bandsintown::Event.on_sale_soon)
 * Corrected some typos in Bandsintown::Event spec

data/Manifest.txt

@@ -15,6 +15,7 @@ script/txt2html
 spec/bandsintown/artist_spec.rb
 spec/bandsintown/base_spec.rb
 spec/bandsintown/connection_spec.rb
+spec/bandsintown/event/creation_helpers_spec.rb
 spec/bandsintown/event_spec.rb
 spec/bandsintown/venue_spec.rb
 spec/bandsintown_spec.rb

data/README.rdoc

@@ -107,6 +107,48 @@ For more information visit http://www.bandsintown.com/api/requests.
     :radius => 10
   })
 
+=== Find venues with name beginning with "House of Blues" near San Diego, CA
+
+  venues = Bandsintown::Venue.search({
+    :query => "House of Blues",
+    :location => "San Diego, CA"
+  })
+
+=== Find all upcoming events for a given venue
+
+  # 1700 => Bandsintown venue ID for Paradise Rock Club in Boston, MA
+  venue = Bandsintown::Venue.new(1700)
+  events = venue.events
+
+=== Create an event on bandsintown.com using Bandsintown::Artist and Bandsintown::Venue objects
+
+  # 1700 => Bandsintown venue ID for Paradise Rock Club in Boston, MA
+  Bandsintown::Event.create({
+    :artists => [Bandsintown::Artist.new(:name => "The Roots")],
+    :datetime => Time.parse("2010-06-01 20:00"),
+    :venue => Bandsintown::Venue.new(1700),
+    :ticket_url => "http://www.example.com/tickets/123",
+    :ticket_price => 19.5,
+    :on_sale_datetime => Time.parse("2010-05-01 12:00")
+  })
+
+=== Create an event on bandsintown.com using artist names and venue location hash
+
+  # 1700 => Bandsintown venue ID for Paradise Rock Club in Boston, MA
+  Bandsintown::Event.create({
+    :artists => ["Evidence", "Alchemist"],
+    :datetime => "2010-06-01T19:30:00",
+    :venue => { 
+      :name => "Paradise Rock Club",
+      :city => "Boston",
+      :region => "MA",
+      :country => "United States"
+    },
+    :ticket_url => "http://www.example.com/tickets/123",
+    :ticket_price => 15,
+    :on_sale_datetime => "2010-05-01T19:30:00"
+  })
+
 == Links
 
 * RDoc[http://bandsintown.rubyforge.org/rdoc]

data/Rakefile

@@ -9,7 +9,8 @@ $hoe = Hoe.new('bandsintown', Bandsintown::VERSION) do |p|
   p.rubyforge_name       = p.name # TODO this is default value
   p.extra_deps         = [
     ['activesupport','>= 2.0.2'],
-    ['json', '>= 1.1.3']
+    ['json', '>= 1.1.3'],
+    ['rest-client', '>= 1.5.0']
   ]
   p.extra_dev_deps = [
     ['newgem', ">= #{::Newgem::VERSION}"]

data/lib/bandsintown.rb

@@ -2,10 +2,10 @@ $:.unshift(File.dirname(__FILE__)) unless
   $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
 
 require 'rubygems'
-require 'open-uri'
 require 'cgi'
-require 'activesupport'
+require 'active_support'
 require 'json'
+require 'rest_client'
 
 require 'bandsintown/base'
 require 'bandsintown/connection'
@@ -14,7 +14,7 @@ require 'bandsintown/event'
 require 'bandsintown/venue'
 
 module Bandsintown
-  VERSION = '0.1.4'
+  VERSION = '0.2.0'
   class APIError < StandardError; end
   class << self
     # All Bandsintown API requests require an app_id parameter for identification.

data/lib/bandsintown/artist.rb

@@ -1,7 +1,7 @@
 module Bandsintown
   class Artist < Base
     
-    attr_accessor :name, :bandsintown_url, :mbid, :events, :upcoming_events_count
+    attr_accessor :name, :mbid, :events, :upcoming_events_count
     
     def initialize(options = {})
       @name = options[:name]
@@ -23,7 +23,7 @@ module Bandsintown
     #
     def events
       return @events unless @events.blank?
-      @events = self.class.request_and_parse("#{api_name}/events").map { |event| Bandsintown::Event.build_from_json(event) }
+      @events = self.class.request_and_parse(:get, "#{api_name}/events").map { |event| Bandsintown::Event.build_from_json(event) }
     end
     
     # Used in api requests as the RESTful resource id for artists (http://api.bandsintown.com/artists/id/method).
@@ -70,16 +70,16 @@ module Bandsintown
     #
     def self.get(options = {})
       request_url = Bandsintown::Artist.new(options).api_name
-      build_from_json(request_and_parse(request_url))
+      build_from_json(request_and_parse(:get, request_url))
     end
     
     def self.build_from_json(json_hash)
-      artist = Bandsintown::Artist.new({})
-      artist.name = json_hash['name']
-      artist.mbid = json_hash['mbid']
-      artist.bandsintown_url = json_hash['url']
-      artist.upcoming_events_count = json_hash['upcoming_events_count']
-      artist
+      returning Bandsintown::Artist.new({}) do |artist|
+        artist.name = json_hash['name']
+        artist.mbid = json_hash['mbid']
+        artist.bandsintown_url = json_hash['url']
+        artist.upcoming_events_count = json_hash['upcoming_events_count']
+      end
     end
     
     def self.resource_path

data/lib/bandsintown/base.rb

@@ -3,8 +3,12 @@ module Bandsintown
   
     attr_accessor :bandsintown_url
     
-    def self.request(api_method, args={})
-      self.connection.request(self.resource_path, api_method, args)
+    def self.request(http_method, api_method, args={})
+      case http_method
+      when :get  then self.connection.get(self.resource_path, api_method, args)
+      when :post then self.connection.post(self.resource_path, api_method, args)
+      else raise ArgumentError, "only :get and :post requests are supported"
+      end
     end
   
     def self.connection
@@ -23,8 +27,18 @@ module Bandsintown
       end
     end
     
-    def self.request_and_parse(api_method, args={})
-      parse(request(api_method, args))
+    def self.request_and_parse(http_method, api_method, args={})
+      parse(request(http_method, api_method, args))
+    end
+    
+    def to_hash
+      hash = {}
+      self.instance_variables.each do |ivar|
+        value = self.instance_variable_get(ivar)
+        next if value.blank?
+        hash[:"#{ivar.gsub('@', '')}"] = value
+      end
+      hash
     end
   
   end

data/lib/bandsintown/connection.rb

@@ -1,21 +1,28 @@
 module Bandsintown
   class Connection
-    attr_accessor :base_url
+    attr_accessor :base_url, :client
     
     def initialize(base_url)
       @base_url = base_url
     end
     
-    def request(resource_path, method_path, args = {})
-      request_url = "#{@base_url}/#{resource_path}/#{method_path}?#{encode(args.symbolize_keys)}"
+    def get(resource_path, method_path, params = {})
+      request_url = "#{@base_url}/#{resource_path}/#{method_path}?#{encode(params.symbolize_keys)}"
       begin
-        open(request_url).read
-      rescue OpenURI::HTTPError => error_response
-        error_response.io.read
+        RestClient.get(request_url)
+      rescue RestClient::ResourceNotFound => error_response
+        error_response.response
       end
     end
     
-    private 
+    def post(resource_path, method_path, body = {})
+      request_url = "#{@base_url}/#{resource_path}/#{method_path}?#{encode({})}"
+      begin
+        RestClient.post(request_url, body.to_json, :content_type => :json, :accept => :json)
+      rescue RestClient::ResourceNotFound => error_response
+        error_response.response
+      end
+    end
     
     def encode(args = {})
       start_date = args.delete(:start_date)

data/lib/bandsintown/event.rb

@@ -1,6 +1,62 @@
 module Bandsintown
   class Event < Base
     
+    # Module with helper methods for formatting Bandsintown::Event.create params
+    module CreationHelpers
+      ISO_8601_FORMAT = "%Y-%m-%dT%H:%M:%S"
+      
+      def self.included(klass)
+        klass.extend(ClassMethods)
+      end
+      
+      module ClassMethods
+        # Formats Time/DateTime/Date to ISO 8601 string, or return unmodified if passed as a String.
+        def parse_datetime(datetime)
+          case datetime
+          when Time, DateTime then datetime.strftime(ISO_8601_FORMAT)
+          when Date then (datetime + 19.hours).strftime(ISO_8601_FORMAT)
+          else datetime
+          end
+        end
+        
+        # Returns a hash with venue attributes.  If bandsintown_id is present this is preferred over location attributes.
+        # venue_data can be either a Bandsintown::Venue or a Hash.
+        def parse_venue(venue_data)
+          hash = venue_data.to_hash
+          bandsintown_id = hash[:id] || hash[:bandsintown_id]
+          venue = if bandsintown_id.blank?
+            {
+              :name => hash[:name], 
+              :address => hash[:address],
+              :city => hash[:city], 
+              :region => hash[:region],
+              :postalcode => hash[:postalcode],
+              :country => hash[:country], 
+              :latitude => hash[:latitude],
+              :longitude => hash[:longitude]
+            }
+          else
+            { :id => bandsintown_id }
+          end
+          venue.reject { |k,v| v.blank? }
+        end
+        
+        # Returns an array of hashes formatted either { :name => name } or { :mbid => mbid } based on each object in artist_data (can be Bandsintown::Artists, Hashes, or Strings)
+        def parse_artists(artist_data)
+          artist_data.map do |artist|
+            if artist.is_a?(String)
+              { :name => artist }
+            else
+              hash = artist.to_hash
+              hash[:mbid].blank? ? { :name => hash[:name] } : { :mbid => hash[:mbid] }
+            end
+          end          
+        end
+      end
+    end
+    
+    include CreationHelpers
+    
     attr_accessor :bandsintown_id, :datetime, :ticket_url, :artists, :venue, :status, :ticket_status, :on_sale_datetime
     
     def tickets_available?
@@ -44,7 +100,7 @@ module Bandsintown
     #
     def self.search(options = {})
       events = []
-      self.request_and_parse("search", options).each { |event| events << Bandsintown::Event.build_from_json(event) }
+      self.request_and_parse(:get, "search", options).each { |event| events << Bandsintown::Event.build_from_json(event) }
       events
     end
     
@@ -53,7 +109,7 @@ module Bandsintown
     #
     def self.daily
       events = []
-      self.request_and_parse("daily").each { |event| events << Bandsintown::Event.build_from_json(event) }
+      self.request_and_parse(:get, "daily").each { |event| events << Bandsintown::Event.build_from_json(event) }
       events
     end
     
@@ -75,7 +131,7 @@ module Bandsintown
     #
     def self.recommended(options = {})
       events = []
-      self.request_and_parse("recommended", options).each { |event| events << Bandsintown::Event.build_from_json(event) }
+      self.request_and_parse(:get, "recommended", options).each { |event| events << Bandsintown::Event.build_from_json(event) }
       events
     end
     
@@ -96,27 +152,92 @@ module Bandsintown
     #
     def self.on_sale_soon(options = {})
       events = []
-      self.request_and_parse("on_sale_soon", options).each { |event| events << Bandsintown::Event.build_from_json(event) }
+      self.request_and_parse(:get, "on_sale_soon", options).each { |event| events << Bandsintown::Event.build_from_json(event) }
       events
     end
     
+    #This is used to create an event on bandsintown.com.
+    #Unless you have a trusted app_id, events added through the API will need to be approved before they are seen live. 
+    #Contact Bandsintown if you are often adding events and would like a trusted account.
+    #See http://www.bandsintown.com/api/requests#events-create for more information.
+    #===options:
+    #   :artists - an Array of artist data with each element in one of the following formats:
+    #     * artist name String
+    #     * Hash of { :name => artist name } or { :mbid => music brainz id }
+    #     * Bandsintown::Artist object with :mbid or :name
+    #   :datetime - use one of the following formats:
+    #     * String in ISO-8601 format: '2010-06-01T19:30:00'
+    #     * Any object that responds to strftime (Date/Time/DateTime)
+    #   :venue - use one of the following formats:
+    #     * Hash of { :id => bandsintown id } or location data (:name, :address, :city, :region, :postalcode, :country, :latitude, :longitude)
+    #       * :name, :city, :region, :country are required for venues in the United States
+    #       * :name, :city, :country are required for venues outside the United States
+    #       * :latitude, :longitude, :address, and :postalcode are optional
+    #     * Bandsintown::Venue object
+    #   :on_sale_datetime - use the same formats as :datetime
+    #   :ticket_url - string with a link to where you can buy tickets to the event
+    #   :ticket_price - a number or string with ticket price
+    #
+    #===notes:
+    #   * :artists, :datetime, and :venue are required, all other options are optional.
+    #   * If :mbid and :name are available in an artist Hash or Bandsintown::Artist, :mbid is used first.
+    #   * If :bandsintown_id and location data are given in a venue Hash or Bandsintown::Venue, :bandsintown_id is used first.
+    #   * If you have a trusted app_id, this method will return a populated Bandsintown::Event object.
+    # 
+    #===examples:
+    #Create an event for Evidence and Alchemist at House of Blues - San Diego on June 1st, 2010 using Bandsintown::Artists and Bandsintown::Venue:
+    #   evidence = Bandsintown::Artist.new(:name => "Evidence")
+    #   alchemist = Bandsintown::Artist.new(:name => "Alchemist")
+    #   venue = Bandsintown::Venue.new(727861) # id for House of Blues - San Diego
+    #   Bandsintown::Event.create(:artists => [evidence, alchemist], :venue => venue, :datetime => "2010-06-01T19:30:00")
+    #   => "Event submitted successfully (pending approval)"
+    #
+    #Create an event for The Roots at Paradise Rock Club in Boston on June 1st, 2010 using artist name, venue location data, including full ticketing and price data:
+    #   paradise = { :name => "Paradise Rock Club", :address => "967 Commonwealth Ave", :city => "Boston", :region => "MA", :country => "United States" }
+    #   Bandsintown::Event.create(:artists => ["The Roots"], :venue => paradise, :datetime => Time.parse("2010-06-01 20:00"), :on_sale_datetime => Time.parse("2010-05-01 12:00"), :ticket_url => "http://www.example.com/tickets/123", :ticket_price => 19.5)
+    #   => "Event submitted successfully (pending approval)"
+    #
+    #Create an event with a trusted app_id
+    #   Bandsintown::Event.create(:artists => ["The Roots"], :datetime => Date.today, :venue => { :id => 123 })
+    #   => Bandsintown::Event with populated attributes
+    #
+    def self.create(options = {})
+      event_data = {
+        :artists          => self.parse_artists(options[:artists]),
+        :venue            => self.parse_venue(options[:venue]),
+        :datetime         => self.parse_datetime(options[:datetime]),
+        :on_sale_datetime => self.parse_datetime(options[:on_sale_datetime]),
+        :ticket_url       => options[:ticket_url],
+        :ticket_price     => options[:ticket_price]
+      }.reject { |k,v| v.blank? }
+      
+      response = self.request_and_parse(:post, "create", :event => event_data)
+      
+      if response.key?("message")
+        response["message"]
+      else
+        Bandsintown::Event.build_from_json(response["event"])
+      end
+    end
+    
     def self.resource_path
       "events"
     end
     
     def self.build_from_json(json_hash)
-      event                  = Bandsintown::Event.new
-      event.bandsintown_id   = json_hash["id"]
-      event.bandsintown_url  = json_hash["url"]
-      event.datetime         = Time.parse(json_hash["datetime"])
-      event.ticket_url       = json_hash["ticket_url"]
-      event.status           = json_hash["status"]
-      event.ticket_status    = json_hash["ticket_status"]
-      event.on_sale_datetime = Time.parse(json_hash["on_sale_datetime"]) rescue nil
-      event.venue            = Bandsintown::Venue.new(json_hash["venue"])
-      event.artists          = json_hash["artists"].map { |artist| Bandsintown::Artist.new(artist.symbolize_keys) }
-      event
+      returning Bandsintown::Event.new do |event|
+        event.bandsintown_id   = json_hash["id"]
+        event.bandsintown_url  = json_hash["url"]
+        event.datetime         = Time.parse(json_hash["datetime"])
+        event.ticket_url       = json_hash["ticket_url"]
+        event.status           = json_hash["status"]
+        event.ticket_status    = json_hash["ticket_status"]
+        event.on_sale_datetime = Time.parse(json_hash["on_sale_datetime"]) rescue nil
+        event.venue            = Bandsintown::Venue.build_from_json(json_hash["venue"])
+        event.artists          = json_hash["artists"].map { |artist| Bandsintown::Artist.new(artist.symbolize_keys) }
+      end
     end
+
     
   end
 end

data/lib/bandsintown/venue.rb

@@ -1,18 +1,73 @@
 module Bandsintown
   class Venue < Base
+    attr_accessor :name, :bandsintown_id, :city, :region, :country, :latitude, :longitude, :events
     
-    attr_accessor :name, :bandsintown_id, :region, :city, :country, :latitude, :longitude
+    #Note - address and postalcode are not returned in API responses, but they are accepted when passing venue data to Bandsintown::Event.create.
+    attr_accessor :address, :postalcode
         
-    def initialize(args={})
-      @name            = args["name"]
-      @bandsintown_url = args["url"]
-      @bandsintown_id  = args["id"]
-      @region          = args["region"]
-      @city            = args["city"]
-      @country         = args["country"]
-      @latitude        = args["latitude"]
-      @longitude       = args["longitude"]
-    end
+    def initialize(bandsintown_id)
+      @bandsintown_id = bandsintown_id
+    end 
+    
+    #Returns an array of Bandsintown::Event objects for each of the venues's upcoming events available through bandsintown.com.
+    #See http://www.bandsintown.com/api/requests#venues-events for more information.
+    #
+    #====example:
+    #
+    #   # using Paradise Rock Club in Boston, MA (bandsintown id 1700)
+    #   venue = Bandsintown::Venue.new(1700)
+    #   upcoming_paradise_events = venue.events
+    #
+    def events
+      @events ||= self.class.request_and_parse(:get, "#{@bandsintown_id}/events").map { |event_hash| Bandsintown::Event.build_from_json(event_hash) }
+    end 
     
+    #Returns an array of Bandsintown::Venue objects matching the options passed.
+    #See http://www.bandsintown.com/api/requests#venues-search for more information.
+    #====options:
+    # :query - a string to match the beginning of venue names
+    # :location - a string with one of the following formats:
+    #   * 'city, state' for United States and Canada
+    #   * 'city, country' for other countries
+    #   * 'latitude,longitude'
+    #   * ip address - will use the location of the passed ip address
+    #   * 'use_geoip' - will use the location of the ip address that made the request
+    # :radius - a number in miles. API default is 25, maximum is 150.
+    # :per_page - number of results per response.  Default is 5, maximum is 100.
+    # :page - offset for paginated results.  API default is 1.
+    #
+    #====notes:
+    #:query is required for this request, all other arguments are optional.
+    #
+    #====examples:
+    #All venues (first page w/ 5 results) with name beginning with 'House of Blues':
+    #   Bandsintown::Venue.search(:query => 'House of Blues')
+    #
+    #All venues (first page w/ 5 results) with name beginning with 'House of' within 25 miles of San Diego, CA:
+    #   Bandsintown::Venue.search(:query => "House of", :location => "San Diego, CA")
+    # 
+    #Second page of all venues near the request's ip address with name beginning with "Club" and 100 results per page:
+    #   Bandsintown::Venue.search(:query => "Club", :per_page => 100, :page => 2, :location => "use_geoip")
+    #
+    def self.search(options = {})
+      self.request_and_parse(:get, "search", options).map { |venue_hash| Bandsintown::Venue.build_from_json(venue_hash) }
+    end
+
+    def self.resource_path
+      "venues"
+    end
+     
+    def self.build_from_json(args={})
+      returning Bandsintown::Venue.new(args['id']) do |v|
+        v.name            = args["name"]
+        v.bandsintown_url = args["url"]
+        v.bandsintown_id  = args["id"]
+        v.region          = args["region"]
+        v.city            = args["city"]
+        v.country         = args["country"]
+        v.latitude        = args["latitude"]
+        v.longitude       = args["longitude"]
+      end
+    end    
   end
 end