Venue-driver-api-documentation is a project mainly written in PHP, it's free.
Documentation and examples for using the Venue Driver REST API.
h1. Venue Driver API Documentation
h2. REST API
Venue Driver provides a simple HTTP API that's built according to a REST design pattern. That just means that each of our resources like "Events" has a URL that you can call, and each resource has 'index', 'create', 'read', 'update' and 'delete' actions. You tell it whether you want your data in XML or JSON. In some cases we also provide HTML representations so that you don't even have to process raw data.
h3. Resources
Venue Driver provides easy XML or JSON access to Reservation and Guest (for Guestlist) resources:
h2. Common tasks
h3. Get a venue list for an account
If you're only dealing with one venue then you don't need to use the API to obtain a venue list. You can simply obtain your venue's ID from Venue Driver support staff, and then use other API methods for accessing lists of events for a venue, flyers for an event, etc.
If you need to obtain a list of venues for an account, then you will need the account ID, which you can obtain from Venue Driver support. Then use that account ID to request a list of venues for that account:
curl 'http://venuedriver.com/api/accounts/1234/venues.xml?username=venuesite&password=password'
Replace the number '1234' in the above example with your account ID, and replace the username and password with your authentication information.
The above will return something like this:
Las Vegas
USA
2010-07-13T12:14:18-04:00
[email protected]
2000-01-01T21:00:00-05:00
http://www.mgmgrand.com/
35
36.146532
-115.193981
PlugNPay
702-425-9399
2000-01-01T21:00:00-05:00
first
NV
US/Pacific
Studio 54
2010-07-13T12:14:18-04:00
81901
3799 Las Vegas Boulevard South
Las Vegas
USA
2010-07-13T12:14:18-04:00
[email protected]
2000-01-01T21:00:00-05:00
http://www.mgmgrand.com/
1
36.101688
-115.172111
PlugNPay
702-891-7983
2000-01-01T21:00:00-05:00
first
NV
US/Pacific
Tabú Ultra Lounge
2010-07-13T12:14:18-04:00
89109
3799 Las Vegas Boulevard South
Las Vegas
USA
2010-07-13T12:14:18-04:00
[email protected]
2000-01-01T10:00:00-05:00
http://www.wetrepublic.com/
36
36.101198
-115.172424
PlugNPay
702.891.1111
2000-01-01T10:00:00-05:00
first
NV
US/Pacific
Wet Republic
2010-07-13T12:14:18-04:00
89109
You can also request the same information with JSON formatting instead of XML, like this:
curl 'http://venuedriver.com/api/accounts/1234/venues.json?username=venuesite&password=password'
The above will return the same information, formatted with JSON:
[{"city": "Las Vegas", "address": null, "zip": "81901", "myspace_URL": null, "latitude": "36.146532", "created_at": "2010/07/13 12:14:18 -0400", "title": "Studio 54", "reservations_sort": null, "country": "USA", "updated_at": "2010/07/13 12:14:18 -0400", "sort_name": "first", "payment_gateway": "PlugNPay", "guestlists_sort": null, "id": 35, "phone": "702-425-9399", "guestlist_close_time": "2000/01/01 21:00:00 -0500", "time_zone": "US/Pacific", "social_status": null, "reservations_summary_time": "2000/01/01 21:00:00 -0500", "longitude": "-115.193981", "home_URL": "http://www.mgmgrand.com/", "description": null, "tickets_sort": null, "state": "NV", "email": "[email protected]"}, {"city": "Las Vegas", "address": "3799 Las Vegas Boulevard South", "zip": "89109", "myspace_URL": null, "latitude": "36.101688", "created_at": "2010/07/13 12:14:18 -0400", "title": "Tabu00fa Ultra Lounge", "reservations_sort": null, "country": "USA", "updated_at": "2010/07/13 12:14:18 -0400", "sort_name": "first", "payment_gateway": "PlugNPay", "guestlists_sort": null, "id": 1, "phone": "702-891-7983", "guestlist_close_time": "2000/01/01 21:00:00 -0500", "time_zone": "US/Pacific", "social_status": null, "reservations_summary_time": "2000/01/01 21:00:00 -0500", "longitude": "-115.172111", "home_URL": "http://www.mgmgrand.com/", "description": null, "tickets_sort": null, "state": "NV", "email": "[email protected]"}, {"city": "Las Vegas", "address": "3799 Las Vegas Boulevard South", "zip": "89109", "myspace_URL": null, "latitude": "36.101198", "created_at": "2010/07/13 12:14:18 -0400", "title": "Wet Republic", "reservations_sort": null, "country": "USA", "updated_at": "2010/07/13 12:14:18 -0400", "sort_name": "first", "payment_gateway": "PlugNPay", "guestlists_sort": null, "id": 36, "phone": "702.891.1111", "guestlist_close_time": "2000/01/01 10:00:00 -0500", "time_zone": "US/Pacific", "social_status": null, "reservations_summary_time": "2000/01/01 10:00:00 -0500", "longitude": "-115.172424", "home_URL": "http://www.wetrepublic.com/", "description": null, "tickets_sort": null, "state": "NV", "email": "[email protected]"}]
h3. Get an event list for a venue
You can get an event list for a venue record in Venue Driver if you have a valid login and also the venue ID. The venue ID is numeric, and you can obtain it through the above venue index method, or you can obtain the ID for your venue from Venue Driver support. The API's /venues resource exposes a nested events resource. So if you want the events for the venue with ID 1234, then you can get that with:
curl 'http://venuedriver.com/api/venues/1234/events.xml?username=venuesite&password=password'
The above will return something like this:
2000-01-01T08:15:00-05:00
2010-02-09T20:48:10-05:00
2010-03-12
5635
2000-01-01T22:30:00-05:00
0
Friday Event
2010-03-01T14:42:29-05:00
2000-01-01T08:15:00-05:00
2010-02-09T20:48:35-05:00
2010-03-13
5636
2000-01-01T22:00:00-05:00
0
Saturday Event
2010-03-01T14:42:29-05:00
This API method can also return data formatted with JSON instead of XML, just like the venue index method above. Simply change the file extension in the request URL from ".xml" to ".json":
curl 'http://venuedriver.com/api/venues/1234/events.json?username=venuesite&password=password'
h3. Get flyer images for an event
Flyers are a nested resource under the event resource. They are not included in the event list returned by /venues/:venue_id/events.xml, but you can obtain them through the flyer resource:
curl 'http://venuedriver.com/api/venues/1234/events/5678/flyers.xml?username=venuesite&password=password'
The above will return the list of flyers for the event 5678:
image/jpeg
IMG_3020.jpg
473217
2010-03-02T17:00:00-05:00
5313
8
/assets/8/original/IMG_3020.jpg
image/jpeg
IMG_2970.jpg
603736
2010-03-02T17:00:56-05:00
5313
9
/assets/9/original/IMG_2970.jpg
image/jpeg
Safari-screenshot-236.jpg
58457
2010-03-02T18:02:25-05:00
5313
10
/assets/10/original/Safari-screenshot-236.jpg
application/pdf
20091206-160523.pdf
3302460
2010-03-02T18:38:33-05:00
5313
12
/assets/12/original/20091206-160523.pdf
image/jpeg
02_events.jpg
1378489
2010-03-02T18:39:34-05:00
5313
13
/assets/13/original/02_events.jpg
You can also use the show action for the event resource. For example, this will return the list of flyer images for the event 5678 at the venue 1234:
curl 'http://venuedriver.com/api/venues/1234/events/5678.xml?username=venuesite&password=password'
The response includes the attributes for the event as in the above, but it also includes the nested flyer records:
2000-01-01T09:00:00-05:00
2010-01-02T01:01:46-05:00
2010-03-02
5313
2000-01-01T22:30:00-05:00
Tuesday Night
2010-03-01T14:42:14-05:00
image/jpeg
IMG_3020.jpg
473217
2010-03-02T17:00:00-05:00
5313
8
/assets/8/original/IMG_3020.jpg
image/jpeg
IMG_2970.jpg
603736
2010-03-02T17:00:56-05:00
5313
9
/assets/9/original/IMG_2970.jpg
image/jpeg
Safari-screenshot-236.jpg
58457
2010-03-02T18:02:25-05:00
5313
10
/assets/10/original/Safari-screenshot-236.jpg
application/pdf
20091206-160523.pdf
3302460
2010-03-02T18:38:33-05:00
5313
12
/assets/12/original/20091206-160523.pdf
image/jpeg
02_events.jpg
1378489
2010-03-02T18:39:34-05:00
5313
13
/assets/13/original/02_events.jpg
h3. Create a reservation
Create a reservation in Venue Driver by posting a reservation record with the proper event_id to http://venuedriver.com/api/reservations, as in this example:
curl -i -H "Accept: application/json" -X POST -d "event_id=1840479691&reservation[first]=test&reservation[last]=test&reservation[phone]=5555555&reservation[email][email protected]" "http://venuedriver.com/api/reservations?username=venuesite&password=password"
When successful, the above query will return a JSON representation of the new reservation:
HTTP/1.1 200 OK
Connection: close
Date: Tue, 25 May 2010 18:25:22 GMT
Set-Cookie: _saintpeter_session_id=0792619031d7ae234dcf2400a5fb59e3; path=/
Status: 200 OK
ETag: "bad52e9d03f4b589acee6aeb5ec7962e"
P3P: CP="NOI DSP COR NID ADMa OPTa OUR NOR"
X-Runtime: 0.65959
Content-Type: application/json; charset=utf-8
Content-Length: 892
Server: Mongrel 1.1.5
Cache-Control: private, max-age=0, must-revalidate
{"city":null,"checkin_time":null,"checked_in":null,"address1":null,"zip":null,"created_at":"2010/05/25 14:25:23 -0400","confirmation":null,"address2":null,"staff_id":null,"event_id":1840479691,"customer_notes":null,"country":null,"company_name":null,"updated_at":"2010/05/25 14:25:23 -0400","table_id":null,"notes":null,"gratuity":null,"table_number":null,"signup_notes":null,"minimum_currency":null,"last":"test","area_id":null,"actual_paid_bottles":null,"account_id":null,"total_spend":null,"id":2132434459,"approved":null,"actual_comp_bottles":null,"phone":"5555555","guests":null,"first":"test","walkup":false,"total_returns":null,"phone_alternative":null,"paid_bottles":null,"event_notes":null,"date_of_birth":null,"seated_table_id":null,"phone_hash":"5555555","phone_carrier":null,"comp_bottles":null,"state":null,"email":"[email protected]","host_name":"[not assigned]","bottles_both":"0"}
h2. Convenience methods
h3. Event select tag
Venue Driver provides an API method that will return HTML code for an event select box, to be inserted directly into a web page. For example, to get a drop-down select box for all upcoming events at the venue with Venue Driver ID code 1234, you might call a URL like this:
http://venuedriver.com/api/venues/1234/events/select_tag.html?username=venuesite&password=password
You can test from the command line using the cURL utility:
curl 'http://venuedriver.com/api/venues/129582/events/select_tag.html?username=venuesite&password=password'
It will return something like this:
Using that resource URL is pretty simple. In Ruby for example it looks like this:
url = "http://venuedriver/api/venues/129582/events/select_tag.html?username=venuesite&password=password"
events_html = Net::HTTP.get_response(URI.parse(url))
Then you can just drop that HTML snippet into your form with @<%= events_html %>@ or the equivalent in PHP or whatever. That gives you a simple way to build a form that can request guest list signup for any upcoming event.
When somebody submits the form, creating the guest list entry is similarly simple. It also involves a simple HTTP query to an API URL. Are you using PHP? I can send you an example snippet for doing the post if so.
h2. Examples
h3. Ruby on Rails
"Promoter":http://github.com/angelmg/promoter is a Rails plugin for accessing the Venue Driver API. Promoter is a Rails Engine plugin that adds controllers and views to your web site for providing reservation, guest list and mailing list signup forms. It uses Active Resource to access Venue Driver. For example, here is how to get a list of events and a list of flyers for an event from the console:
>> @events = Event.find(:all, :params => {:venue_id => 1})
=> [#Sun Jan 02 03:30:00 UTC 2000, "myspace_URL"=>nil, ...
>> @events.size
=> 38
>> puts @events.first.to_yaml
--- !ruby/object:Event
attributes:
open: 2000-01-02 03:30:00 Z
myspace_URL:
created_at: 2009-12-18 03:48:14 Z
title: Sundays at Tabu
close: 2000-01-01 13:30:00 Z
closed_message:
ages:
cover:
guestlist_conditions:
updated_at: 2010-03-01 19:42:22 Z
time:
wiki_name:
id: 5237
date: 2010-02-28
VIP_URL:
tickets_URL:
home_URL:
description:
active:
flyers: []
tickets_sold_count: 0
guestlist_URL:
prefix_options:
:venue_id: 1
=> nil
>> @flyers = Flyer.find(:all, :params => {:venue_id => 1, :event_id => 5313})
=> [#"IMG_3020.jpg", "asset_url"=>"/assets/8/original/IMG_3020.jpg" ...
>> @flyers.size
=> 5
>> puts @flyers.first.to_yaml
--- !ruby/object:Flyer
attributes:
asset_file_name: IMG_3020.jpg
asset_url: /assets/8/original/IMG_3020.jpg
asset_file_size: 473217
asset_content_type: image/jpeg
id: 8
parent_id:
asset_updated_at: 2010-03-02 22:00:00 Z
prefix_options:
:venue_id: 1
:event_id: 5313
=> nil
>>
h3. PHP
These examples show how to build reservation and guest list forms with PHP. These examples use a "PHP library":http://code.google.com/p/phpactiveresource/ for accessing our REST resources.
Here are the example files:
"Example PHP reservation form":http://github.com/endymion/venue-driver-api-documentation/raw/master/examples/php/ReservationForm.php "Example PHP guest list form":http://github.com/endymion/venue-driver-api-documentation/raw/master/examples/php/GuestListForm.php "Venue Driver API configuration file":http://github.com/endymion/venue-driver-api-documentation/raw/master/examples/php/VenueDriver.php "ActiveResource REST API for PHP":http://github.com/endymion/venue-driver-api-documentation/raw/master/examples/php/ActiveResource.php
h3. JavaScript
You might want to add an on-change handler to the select boxes that Venue Driver's convenience methods return. Here is an example of how to do that unobtrusively using jQuery:
"Unobtrusive JavaScript example":http://github.com/endymion/venue-driver-api-documentation/raw/master/examples/javascript/unobtrustive-onchange-example.html