Path: lib/eventful/api.rb
Last Update: Mon May 14 17:15:22 -0700 2007

A library for working with the Eventful API. Simple programmatic access to Eventful‘s database of events, venues, performers and speakers, groups, calendars, and users.

See api.eventful.com for more information about the Eventful API and the available API methods.

Example Usage

 require 'rubygems'
 require 'eventful/api'


   # Start an API session with a username and password
   eventful = Eventful::API.new 'application_key',
                                :user => 'username',
                                :password => 'password'

   # Lookup an event by its unique id
   event = eventful.call 'events/get',
                         :id => 'E0-001-001042544-7'

   puts "Event Title: #{event['title']}"

   # Get information about that event's venue
   venue = eventful.call 'venues/get',
                         :id => event['venue_id']

   puts "Venue: #{venue['name']}"

 rescue Eventful::APIError => e
   puts "There was a problem with the API: #{e}"

Another Example

 require 'rubygems'
 require 'eventful/api'

 # First, create our Eventful::API object
 eventful = Eventful::API.new 'application_key'

 loop do
   # Ask the user what and where to search
   puts "Search where? (Ex: San Diego)"
   print "? "
   location = gets.chomp
   puts "Search for what (Ex: music)"
   print "? "
   query = gets.chomp

   # This is the cool part!
   results = eventful.call 'events/search',
                           :keywords => query,
                           :location => location,
                           :page_size => 5

   # If we couldn't find anything, ask the user again
   if results['events'].nil? then
     puts "Hmm. I couldn't find anything. Sorry."

   # Output the results
   results['events']['event'].each do |event|
     puts "http://eventful.com/events/" + event['id']
     puts event['title']
     puts "  at " + event['venue_name']
     puts "  on " + Time.parse(event['start_time']).strftime("%a, %b %d, %I:%M %p") if event['start_time']


Use of the Eventful API requires an application key (see api.eventful.com/keys for more information).

Change Notes

Eventful API

Version 2.2.0

  • The authentication bug has been fixed, so I‘m rolling back the workaround.
  • Documented the parameters for specifying alternative API servers when calling Eventful.new
  • The names of these keys have been changed to be a bit friendlier. The old keys will still work fine.
  • Hash keys to methods can now be Symbols, in addition to strings
  • A fun new example, just because

Version 2.1.1

  • Includes a workaround fix for an authentication bug. This fix may be rolled back should the workaround become unecessary in the future.

Version 2.1

  • As EVDB Inc. has been renamed Eventful Inc., the EVDB module has been renamed Eventful, and the gem is now named eventfulapi. Support for the evdbapi gem is being discontinued; please use the eventfulapi gem from now on.
  • Much better at throwing an error when a network or server problem happens, rather than failing silently and mysteriously
  • Documentation improvements


Version 2.0.1

  • Fixed a minor documentation error

Version 2.0

Version 2.0 of this library includes some significant changes which may not be backwards compatible. Specifically:

  • Anonymous logins are now allowed
  • Fixes a potential image uploading API error

Most importantly, the library now uses YAML as its data exchange format instead of XML, and the objects returned from a call can be used like hashes instead of REXML objects.


Current Author:Paul Knight (paul@eventful.com)
Previous Authors:Joe Auricchio
Copyright:Copyright (C) 2005-2007 Eventful Inc.
License:This code is distributed under the same terms as Ruby itself (see www.ruby-lang.org/en/LICENSE.txt)

Required files

mime/types   rubygems   mime/types   yaml   cgi   net/http   base64   digest/md5