bandsintown 0.1.1

data/History.txt

@@ -0,0 +1,18 @@
+== 0.1.1 2009-09-08
+* fixed escaping issue with / and ? in artist urls
+
+== 0.1.0 2009-09-05
+* Full Bandsintown API support
+* Added Artists - Events API method
+* Added Events - Recommended API method
+* Updated Bandsintown::Connection class
+* Added attributes for on_sale_datetime and ticket_status to Bandsintown::Event class
+* Lots of documentation
+
+== 0.0.2 2009-06-03
+* Added the daily events API method
+
+== 0.0.1 2009-02-20
+
+* 1 major enhancement:
+  * Initial release

data/Manifest.txt

@@ -0,0 +1,27 @@
+History.txt
+Manifest.txt
+README.rdoc
+Rakefile
+lib/bandsintown.rb
+lib/bandsintown/artist.rb
+lib/bandsintown/base.rb
+lib/bandsintown/connection.rb
+lib/bandsintown/event.rb
+lib/bandsintown/venue.rb
+script/console
+script/destroy
+script/generate
+script/txt2html
+spec/bandsintown/artist_spec.rb
+spec/bandsintown/base_spec.rb
+spec/bandsintown/connection_spec.rb
+spec/bandsintown/event_spec.rb
+spec/bandsintown/venue_spec.rb
+spec/bandsintown_spec.rb
+spec/spec.opts
+spec/spec_helper.rb
+website/index.html
+website/index.txt
+website/javascripts/rounded_corners_lite.inc.js
+website/stylesheets/screen.css
+website/template.html.erb

data/README.rdoc

@@ -0,0 +1,88 @@
+= bandsintown
+
+== Description
+
+Bandsintown.com API gem
+
+A Ruby library for accessing the Bandsintown API.
+
+The Bandsintown API lets any developer access the largest database of upcoming concert listings and concert tickets in the world.
+
+For more information visit http://www.bandsintown.com/api/requests.
+
+== Installing
+
+  sudo gem install bandsintown
+
+== Usage
+
+=== Requiring
+
+  require 'bandsintown'
+
+=== Setting the bandsintown app_id parameter
+
+  Bandsintown.app_id = 'YOUR_APP_ID'
+
+=== Find all upcoming events for a given artist
+
+  artist = Bandsintown::Artist.new("The Killers")
+  events = artist.events
+
+=== Find events this week around Boston, MA 
+
+  events = Bandsintown::Event.search({
+    :location => 'Boston, MA', 
+    :start_date => Time.now,
+    :end_date => 1.week.from_now
+  })
+
+=== Find events this week for Mos Def and Talib Kweli
+
+  events = Bandsintown::Event.search({
+    :artists => ['Mos Def', 'Talib Kweli'], 
+    :start_date => Time.now, 
+    :end_date => 1.week.from_now
+  })
+
+=== Find recommended events around Boston, MA for fans of Led Zeppelin
+
+  events = Bandsintown::Event.recommended({
+    :artists => ['Led Zeppelin'], 
+    :location => 'Boston, MA'
+  })
+
+=== find events added/updated/deleted within the last day
+
+  events = Bandsintown::Event.daily
+
+== Links
+
+* RDoc[http://bandsintown.rubyforge.org/rdoc]
+* {Bandsintown.com API Documentation}[http://www.bandsintown.com/api/requests]
+* Github[http://github.com/bandsintown/bandsintown]
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2009 Mike Costanza
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,28 @@
+%w[rubygems rake rake/clean fileutils newgem rubigen].each { |f| require f }
+require File.dirname(__FILE__) + '/lib/bandsintown'
+
+# Generate all the Rake tasks
+# Run 'rake -T' to see list of generated tasks (from gem root directory)
+$hoe = Hoe.new('bandsintown', Bandsintown::VERSION) do |p|
+  p.developer('Mike Costanza', 'mike@bandsintown.com')
+  p.changes              = p.paragraphs_of("History.txt", 0..1).join("\n\n")
+  p.rubyforge_name       = p.name # TODO this is default value
+  p.extra_deps         = [
+    ['activesupport','>= 2.0.2'],
+    ['json', '>= 1.1.3']
+  ]
+  p.extra_dev_deps = [
+    ['newgem', ">= #{::Newgem::VERSION}"]
+  ]
+  
+  p.clean_globs |= %w[**/.DS_Store tmp *.log]
+  path = (p.rubyforge_name == p.name) ? p.rubyforge_name : "\#{p.rubyforge_name}/\#{p.name}"
+  p.remote_rdoc_dir = File.join(path.gsub(/^#{p.rubyforge_name}\/?/,''), 'rdoc')
+  p.rsync_args = '-av --delete --ignore-errors'
+end
+
+require 'newgem/tasks' # load /tasks/*.rake
+Dir['tasks/**/*.rake'].each { |t| load t }
+
+# TODO - want other tests/tasks run by default? Add them to the list
+# task :default => [:spec, :features]

data/lib/bandsintown.rb

@@ -0,0 +1,27 @@
+$:.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 'json'
+
+require 'bandsintown/base'
+require 'bandsintown/connection'
+require 'bandsintown/artist'
+require 'bandsintown/event'
+require 'bandsintown/venue'
+
+module Bandsintown
+  VERSION = '0.1.1'
+  class APIError < StandardError; end
+  class << self
+    # All Bandsintown API requests require an app_id parameter for identification.
+    # See http://www.bandsintown.com/api/authentication for more information.
+    #
+    attr_accessor :app_id
+  end
+end
+
+

data/lib/bandsintown/artist.rb

@@ -0,0 +1,49 @@
+module Bandsintown
+  class Artist < Base
+    
+    attr_accessor :name, :events
+    
+    def initialize(name, url = nil)
+      @name = name
+      @bandsintown_url = url || build_bandsintown_url
+    end
+    
+    #Returns an array of Bandsintown::Event objects for each of the artist's upcoming events available through bandsintown.com.
+    #See http://www.bandsintown.com/api/requests#artists-events for more information.
+    #
+    #====example:
+    #   artist = Bandsintown::Artist.new("Little Brother")
+    #   upcoming_little_brother_events = artist.events
+    #
+    def events
+      return @events unless @events.blank?
+      @events = self.class.request_and_parse("#{api_name}/events").map { |event| Bandsintown::Event.build_from_json(event) }
+    end
+    
+    # name used in api requests. / and ? must be double escaped.
+    #
+    def api_name
+      name = @name.dup
+      name.gsub!('/', CGI.escape('/'))
+      name.gsub!('?', CGI.escape('?'))
+      URI.escape(name)
+    end
+    
+    def self.resource_path
+      "artists"
+    end
+    
+    private
+    
+    def build_bandsintown_url
+      name = @name.dup
+      name.gsub!('&', 'And')
+      name.gsub!('+', 'Plus')
+      name = name.split.map { |w| w.capitalize }.join if name =~ /\s/
+      name.gsub!('/', CGI.escape('/'))
+      name.gsub!('?', CGI.escape('?'))
+      "http://www.bandsintown.com/#{URI.escape(name)}"
+    end
+    
+  end
+end

data/lib/bandsintown/base.rb

@@ -0,0 +1,31 @@
+module Bandsintown
+  class Base
+  
+    attr_accessor :bandsintown_url
+    
+    def self.request(api_method, args={})
+      self.connection.request(self.resource_path, api_method, args)
+    end
+  
+    def self.connection
+      @connection ||= Bandsintown::Connection.new("http://api.bandsintown.com")
+    end
+    
+    def self.parse(response)
+      json = JSON.parse(response)
+      check_for_errors(json)
+      json
+    end
+    
+    def self.check_for_errors(json)
+      if json.is_a?(Hash) && json.has_key?("errors")
+        raise Bandsintown::APIError.new(json["errors"].join(", "))
+      end
+    end
+    
+    def self.request_and_parse(api_method, args={})
+      parse(request(api_method, args))
+    end
+  
+  end
+end

data/lib/bandsintown/connection.rb

@@ -0,0 +1,36 @@
+module Bandsintown
+  class Connection
+    attr_accessor :base_url
+    
+    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)}"
+      begin
+        open(request_url).read
+      rescue OpenURI::HTTPError => error_response
+        error_response.io.read
+      end
+    end
+    
+    private 
+    
+    def encode(args = {})
+      start_date = args.delete(:start_date)
+      end_date   = args.delete(:end_date)
+      if start_date && end_date
+        start_date  = start_date.strftime("%Y-%m-%d") unless start_date.is_a?(String)
+        end_date    = end_date.strftime("%Y-%m-%d")   unless end_date.is_a?(String)
+        args[:date] = "#{start_date},#{end_date}"
+      elsif args.has_key?(:date)
+        args[:date] = args[:date].strftime("%Y-%m-%d") unless args[:date].is_a?(String)
+      end
+      args[:format] = "json"
+      args[:app_id] = Bandsintown.app_id
+      args.to_param
+    end
+    
+  end
+end

data/lib/bandsintown/event.rb

@@ -0,0 +1,102 @@
+module Bandsintown
+  class Event < Base
+    
+    attr_accessor :bandsintown_id, :datetime, :ticket_url, :artists, :venue, :status, :ticket_status, :on_sale_datetime
+    
+    def tickets_available?
+      ticket_status == "available"
+    end
+    
+    #Returns an array of Bandsintown::Event objects matching the options passed.
+    #See http://www.bandsintown.com/api/requests#events-search for more information.
+    #====options:
+    # :artists - an array of artist names or music brainz id's (formatted as 'mbid_<id>').
+    # :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.
+    # :date - use one of the following formats:
+    #   * 'upcoming' - all upcoming dates, this is the API default.
+    #   * single date
+    #     * String formatted 'yyyy-mm-dd'
+    #     * Time/Date/DateTime object (anything that responds to strftime)
+    #   * date range
+    #     * String formatted 'yyyy-mm-dd,yyyy-mm-dd'
+    #     * alternatively use :start_date and :end_date with 'yyyy-mm-dd' Strings or Time/Date/DateTime objects.
+    # :per_page - number of results per response.  API default is 50, maximum is 100.
+    # :page - offset for paginated results.  API default is 1.
+    #
+    #====notes:
+    #:location or :artists is required for this request, all other arguments are optional.
+    #
+    #====examples:
+    #All concerts (first page w/ 50 results) in New York City for The Roots or Slum Village within the next 30 days (using Date objects):
+    #   Bandsintown::Event.search(:location => "New York, NY", :artists => ["The Roots", "Slum Village"], :start_date => Date.today, :end_date => Date.today + 30)
+    #
+    #All concerts (first page w/ 50 results) on Dec 31 2009 (using formatted date string) within 100 miles of London:
+    #   Bandsintown::Event.search(:location => "London, UK", :radius => 100, :date => "2009-12-31")
+    # 
+    #Second page of all concerts near the request's ip address within in the next month, using Time objects and 100 results per page:
+    #   Bandsintown::Event.search(:start_date => Time.now, :end_date => 1.month.from_now, :per_page => 100, :page => 2, :location => "use_geoip")
+    #
+    def self.search(options = {})
+      events = []
+      self.request_and_parse("search", options).each { |event| events << Bandsintown::Event.build_from_json(event) }
+      events
+    end
+    
+    #Returns an array of Bandsintown::Event objects for all events added to Bandsintown within the last day (updated at 12:00 PM EST daily).
+    #See http://www.bandsintown.com/api/requests#events-daily for more information.
+    #
+    def self.daily
+      events = []
+      self.request_and_parse("daily").each { |event| events << Bandsintown::Event.build_from_json(event) }
+      events
+    end
+    
+    #Returns an array of Bandsintown::Event objects matching the options passed.
+    #See http://www.bandsintown.com/api/requests#events-recommended for more information.
+    #====options:
+    #All options are the same as Bandsintown::Event.search with the following extra option:
+    # :only_recs - boolean for whether to include events with the artists from the :artists option. default is false.
+    #
+    #====notes:
+    #:location and :artists are required for this request, all other arguments are optional.
+    #
+    #====examples:
+    #All concerts (first page w/ 50 results) in Boston, MA recommended for fans of Metallica, including Metallica concerts
+    #   Bandsintown::Event.recommended(:location => "Boston, MA", :artists => ["Metallica"])
+    #
+    #All concerts (first page w/ 50 results) on Dec 31 2009 within 100 miles of London recommended for fans of Usher and Lil Wayne, excluding Usher and Lil Wayne concerts
+    #   Bandsintown::Event.recommended(:location => "London, UK", :radius => 100, :date => "2009-12-31", :artists => ["Usher", "Lil Wayne"], :only_recs => true)
+    #
+    def self.recommended(options = {})
+      events = []
+      self.request_and_parse("recommended", options).each { |event| events << Bandsintown::Event.build_from_json(event) }
+      events
+    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"].each { |artist| event.artists << Bandsintown::Artist.new(artist["name"], artist["url"]) }
+      event
+    end
+    
+  end
+end

data/lib/bandsintown/venue.rb

@@ -0,0 +1,18 @@
+module Bandsintown
+  class Venue < Base
+    
+    attr_accessor :name, :bandsintown_id, :region, :city, :country, :latitude, :longitude
+        
+    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
+    
+  end
+end

data/script/console

@@ -0,0 +1,10 @@
+#!/usr/bin/env ruby
+# File: script/console
+irb = RUBY_PLATFORM =~ /(:?mswin|mingw)/ ? 'irb.bat' : 'irb'
+
+libs =  " -r irb/completion"
+# Perhaps use a console_lib to store any extra methods I may want available in the cosole
+# libs << " -r #{File.dirname(__FILE__) + '/../lib/console_lib/console_logger.rb'}"
+libs <<  " -r #{File.dirname(__FILE__) + '/../lib/bandsintown.rb'}"
+puts "Loading bandsintown gem"
+exec "#{irb} #{libs} --simple-prompt"