Class: Bandsintown::Event

Inherits:
Base
  • Object
show all
Includes:
CreationHelpers
Defined in:
lib/bandsintown/event.rb

Defined Under Namespace

Modules: CreationHelpers

Constant Summary

Constants included from CreationHelpers

CreationHelpers::ISO_8601_FORMAT

Instance Attribute Summary collapse

Attributes inherited from Base

#bandsintown_url

Class Method Summary collapse

Instance Method Summary collapse

Methods included from CreationHelpers

included

Methods inherited from Base

check_for_errors, connection, parse, request, request_and_parse, #to_hash

Instance Attribute Details

#artists ⇒ Object

Returns the value of attribute artists.



60
61
62
 
# File 'lib/bandsintown/event.rb', line 60

def artists
  @artists
end

#bandsintown_id ⇒ Object

Returns the value of attribute bandsintown_id.



60
61
62
 
# File 'lib/bandsintown/event.rb', line 60

def bandsintown_id
  @bandsintown_id
end

#datetime ⇒ Object

Returns the value of attribute datetime.



60
61
62
 
# File 'lib/bandsintown/event.rb', line 60

def datetime
  @datetime
end

#on_sale_datetime ⇒ Object

Returns the value of attribute on_sale_datetime.



60
61
62
 
# File 'lib/bandsintown/event.rb', line 60

def on_sale_datetime
  @on_sale_datetime
end

#status ⇒ Object

Returns the value of attribute status.



60
61
62
 
# File 'lib/bandsintown/event.rb', line 60

def status
  @status
end

#ticket_status ⇒ Object

Returns the value of attribute ticket_status.



60
61
62
 
# File 'lib/bandsintown/event.rb', line 60

def ticket_status
  @ticket_status
end

#ticket_url ⇒ Object

Returns the value of attribute ticket_url.



60
61
62
 
# File 'lib/bandsintown/event.rb', line 60

def ticket_url
  @ticket_url
end

#venue ⇒ Object

Returns the value of attribute venue.



60
61
62
 
# File 'lib/bandsintown/event.rb', line 60

def venue
  @venue
end

Class Method Details

.build_from_json(json_hash) ⇒ Object 



252
253
254
255
256
257
258
259
260
261
262
263
264
 
# File 'lib/bandsintown/event.rb', line 252

def self.build_from_json(json_hash)
  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

.create(options = {}) ⇒ Object

This is used to create an event on bandsintown.com. Unless you have a trusted app_id, events added or removed through the API will need to be approved before the changes are seen live. Contact Bandsintown if you are often adding events and would like a trusted account. See 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



204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
 
# File 'lib/bandsintown/event.rb', line 204

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, "", :event => event_data)
  
  if response.key?("message")
    response["message"]
  else
    Bandsintown::Event.build_from_json(response["event"])
  end
end

.daily ⇒ Object

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 www.bandsintown.com/api/requests#events-daily for more information.



110
111
112
113
114
 
# File 'lib/bandsintown/event.rb', line 110

def self.daily
  events = []
  self.request_and_parse(:get, "daily").each { |event| events << Bandsintown::Event.build_from_json(event) }
  events
end

.on_sale_soon(options = {}) ⇒ Object

Returns an array of Bandsintown::Event objects going on sale in the next week, and matching the options passed. See www.bandsintown.com/api/requests#on-sale-soon for more information.

options:

:location, :radius, and :date options are supported. See the Bandsintown::Event.search documentation for accepted formats.

notes:

If :location is given without :radius, a default radius of 25 miles will be used.

examples:

All upcoming concerts within 10 miles of Boston, MA, with tickets going on sale in the next week:

Bandsintown::Event.on_sale_soon(:location => "Boston, MA", :radius => 10)

All concerts happening between Mar 01 2010 and Mar 15 2010 within 25 miles of London, UK, with tickets going on sale in the next week:

Bandsintown::Event.on_sale_soon(:location => "London, UK", :start_date => "2010-03-01", :end_date => "2010-03-15")



153
154
155
156
157
 
# File 'lib/bandsintown/event.rb', line 153

def self.on_sale_soon(options = {})
  events = []
  self.request_and_parse(:get, "on_sale_soon", options).each { |event| events << Bandsintown::Event.build_from_json(event) }
  events
end

.recommended(options = {}) ⇒ Object

Returns an array of Bandsintown::Event objects matching the options passed. See 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)



132
133
134
135
136
 
# File 'lib/bandsintown/event.rb', line 132

def self.recommended(options = {})
  events = []
  self.request_and_parse(:get, "recommended", options).each { |event| events << Bandsintown::Event.build_from_json(event) }
  events
end

.resource_path ⇒ Object 



248
249
250
 
# File 'lib/bandsintown/event.rb', line 248

def self.resource_path
  "events"
end

.search(options = {}) ⇒ Object

Returns an array of Bandsintown::Event objects matching the options passed. See 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")



101
102
103
104
105
 
# File 'lib/bandsintown/event.rb', line 101

def self.search(options = {})
  events = []
  self.request_and_parse(:get, "search", options).each { |event| events << Bandsintown::Event.build_from_json(event) }
  events
end

Instance Method Details

#cancel ⇒ Object

This is used to cancel an event on Bandsintown. If you want to remove a single artist from an event, use Bandsintown::Artist#cancel_event instead. If successful, this method will always return a status message. Unless you have a trusted app_id, events added or removed through the API will need to be approved before the changes are seen live. Contact Bandsintown if you are often adding events and would like a trusted account. See www.bandsintown.com/api/requests#events-cancel for more information.

examples:

Cancel an event with a non-trusted app_id:

events = Bandsintown::Event.search(:location => "San Diego, CA")
event = events.first
event.cancel
=> "Event successfully cancelled (Pending Approval)"

Cancel an event with a trusted app_id:

events = Bandsintown::Event.search(:location => "San Diego, CA")
event = events.first
event.cancel
=> "Event successfully cancelled"

Raises:

  • (StandardError) 


242
243
244
245
246
 
# File 'lib/bandsintown/event.rb', line 242

def cancel
  raise StandardError.new("event cancellation requires a bandsintown_id") if @bandsintown_id.blank?
  response = self.class.request_and_parse(:post, "#{@bandsintown_id}/cancel")
  response["message"]
end

#tickets_available? ⇒ Boolean

Returns:

  • (Boolean) 


62
63
64
 
# File 'lib/bandsintown/event.rb', line 62

def tickets_available?
  ticket_status == "available"
end