JamBase4R

JamBase4R is a framework agnostic Ruby wrapper around the JamBase live music search API. (developer.jambase.com/docs)

This gem can be used to create mashups where your users might want to search for live music. This gem is a replacement for a Ruby on Rails plugin that I wrote a while back called JamBase4Rails. Since Rails is no longer promoting the use of traditional plugins, but rather gems, I thought it was time to do a re-write.

**Note: JamBase requires that any site making use of it’s API provide attribution. See developer.jambase.com/docs for more information. This gem provides helpers to make adding attribution to your site easy.

This gem adds helper methods to your views (if you are using Rails), but does not alter controllers or models in any way.

This is a forked version from Matt Payne’s original, to include new start/end date parameters allowed in the jambase api.

Installation

1) get and install the gem

sudo gem install madcowley-jambase4r

- OR - If using Rails: a) Add config.gem ‘madcowley-jambase4r’, :lib => “jambase4r” to your environment.rb file. b) rake gems:install from your project root

Configuration

Using the JamBase API requires that you register for an API key. Get one here: developer.jambase.com/member/register

JamBase4R is configured via the configure method. The configure method takes a block that is passed a settings object. 2 properties can be set: 1) api_key (required) 2) logger (optional)

FOR RAILS

In an initializer, add the following configuration:

#app_specific_initializers.rb

JamBase4R.configure do |config|

config.api_key = "XXXXXXXXXXXXX"
config.logger = RAILS_DEFAULT_LOGGER - This is optional if you want to enable logging. You can pass an instance of

any class that conforms to the same interface as RAILS_DEFAULT_LOGGER (Specifically, it must respond to #info(msg) and #error(msg)) end

FOR SINATRA

I would typically configure JamBase4R with a Sinatra configure block.

configure do JamBase4R.configure do |config| config.api_key = “XXXXXXXXXXXXX” end end

FOR OTHERS

Check the documentation of the framework you are using. All should allow for this type of configuration.

ATTRIBUTION

JamBase requires that you indicate where your data comes from (attribution). To make this easy, there is a JamBase4R::ViewHelper module that gets automatically included into ActionView::Base if using Rails and into Sinatra’s helpers if using Sinatra.

There are a couple of methods: 1) jambase_text_attribution 2) jambase_image_attribution 3) jambase_flavicon

Example

To make use of JamBase4R just use the JamBase4R::API object.

Available methods (all are class methods):

All methods return an instance of an Array, which contains zero or more Event objects

1) JamBase4R::API.search(options) 2) JamBase4R::API.search_by_artist(artist_name, additional_options={}) 3) JamBase4R::API.search_by_zipcode(zipcode, additional_options={}) 4) JamBase4R::API.search_by_user(user, additional_options={})

Possible options:

:band (or :artist (an alias for :band)) => The name of the band to search for. :zip => The zipcode to search within :radius => The distance from the zipcode to include in the search :user => The registered user - this limits the results to those within the user’s favorite artists :startdate => return results on or after this date :enddate => return results before this date

ie: JamBase4R::API.search(:band => “A Band”, :zip => “90210”, :radius => 20)

JamBase4R::API.search_by_artist("A Band", {:zip => "90210"})
JamBase4R::API.search_by_zipcode("90210")
JamBase4R::API.search_by_user("Matt")

The general schema of the results is:

- events
	- event
       - event_id (String)
       - event_date (String)
       - event_url (String)

- ticket_url (String)

- venue (Venue)
    - venue_id (String)
    - venue_name (String)
    - venue_city (String)
    - venue_state (String)
    - venue_zip (String)
- artists (Artists)
    - Artist(s) (Artist)
        - artist_id
        - artist_name

Copyright © 2009 [Matt Payne], released under the MIT license