API Calls

The Vodomodo API supports three main API functions. They are the tour list, tour detail and video key calls. Each of these calls returns an XML result which is formatted to answer the API query. The tour list call returns a list of the currently active tours in the Vodomodo system. The tour detail call returns all of the details for a specific tour in the Vodomodo system. The video key call returns a key that allows access to one of the videos on the Vodomodo platform.

All of the API calls are made using your Vodomodo key so that your account is only debited for the queries you make. For that reason, it is your responsibility to KEEP YOUR API KEY PRIVATE so that no one is able to intercept your API key for their own use. We recommend that you query our APIs from a server side application in order to protect your API key. If you expose your API key in a browser, be aware that someone may capture it and, by using it, incur API charges on your behalf.


Tour List API Reference

The purpose of this API call is to return a complete list of available tours with minimal data.

Request Object Fields

Successful Response Object Fields

Error Response Object Fields

Example API Requests

	http://api.vodomodo.com?listing&key=2398df9sdyf9y9r&city=New York&state=NY    (will return success or failure API result)
	http://api.vodomodo.com?listing&errors                                        (will return API error documentation)
	http://api.vodomodo.com?listing&help                                          (will return API call documentation)
	

Example Response Objects (success and failure)

	<?xml version="1.0" encoding="ISO8859-1" ?>
	<tourlist>
	   <tour>
		<id>1</id>
		<name>Empire State Building</name>
		<state>NY</state>
		<city>New York</city>
		<area>Midtown Manhattan</area>
	      <thumbnail>020202020bbbbb</thumbnail>
	      <mobile-thumb>030303030ccccc</mobile-thumb>
	   </tour>
	   ...
	   <tour>
		<id>999999</id>
		<name>Grand Central Terminal</name>
		<state>NY</state>
		<city>New York</city>
		<area>Midtown Manhattan</area>
	      <thumbnail>040404040ddddd</thumbnail>
	      <mobile-thumb>050505050eeeee</mobile-thumb>
	   </tour>
	</tourlist>
------------------------------------------------------------------
	<?xml version="1.0" encoding="ISO8859-1" ?>
	<tourlist>
	   <status>400</status>
	   <errors>
		<message>Invalid API KEY.</message>
		<message>Free account has expired.</message>
	   </errors>
	</tourlist>
	

Image Key Usage

An image key can be used on the client device to access the Vodomodo tour images without reveaing your private API credentials. In the example above, the image token '020202020bbbbb' is used to access the tour image thumbnail as follows:

	<img src="http://api.vodomodo.com/?webimage=020202020bbbbb&imagetype=thumb">		Thumbnail
	

Similarily the other tokens are used to access other images:

	<img src="http://api.vodomodo.com/?webimage=030303030ccccc&imagetype=mthumb">		Mobile Thumbnail

	<img src="http://api.vodomodo.com/?webimage=040404040ddddd&imagetype=thumb">		Thumbnail for Grand Central Terminal
	<img src="http://api.vodomodo.com/?webimage=050505050eeeee&imagetype=mthumb">		Mobile Thumbnail for Grand Central Terminal
	


Tour Details API Reference

Request Object Fields

Successful Response Object Fields

Error Response Object Fields

Example API Requests

	http://api.vodomodo.com?details&id=123&key=2398df9sdyf9     (will return success or failure API result)
	http://api.vodomodo.com?details&errors                      (will return API error documentation)
	http://api.vodomodo.com?details&help                        (will return API call documentation)
	

Example Response Objects (success and failure)

	<?xml version="1.0" encoding="ISO8859-1" ?>
	<tour>
	   <id>1</id>
	   <name>Empire State Building</name>
	   <state>NY</state>
	   <city>New York</city>
	   <area>Midtown Manhattan</area>
	   <zip>01023</zip>
	   <description>Concise description of attraction</description>
	   <latitude>+45.034585</latitude>
	   <longitude >-97.3409384</longitude >
	   <phone>(414) 555-1212</phone>
	   <hours>9 a.m. to 10 p.m. during Summer and closes at 5 p.m. rest of year</hours>
	   <street1>National Mall</street1>
	   <street2>Near 57th and Kilborne</street2>
	   <tickets>No Charge</tickets>
	   <website>empirestate.org</website>
	   <webimage>010101010aaaaa</webimage>
	   <thumbnail>020202020bbbbb</thumbnail>
	   <mobile-thumb>030303030ccccc</mobile-thumb>
	   <mobile-small>040404040ddddd</mobile-small>
	   <mobile-normal>050505050eeeee</mobile-normal>
	   <mobile-large>060606060fffff</mobile-large>
	</tour>
------------------------------------------------------------------
	<?xml version="1.0" encoding="ISO8859-1" ?>
	<tour>
	   <status>404</status>
	   <errors>
		<message>Invalid tour identifier.</message>
		<message>Tour was not found.</message>
	   </errors>
	</tour>
	

Image Key Usage

An image key can be used on the client device to access the Vodomodo tour images without reveaing your private API credentials. In the example above, the image token '010101010aaaaa' is used to access the tour image as follows:

	<img src="http://api.vodomodo.com/?webimage=010101010aaaaa">
	

Similarily the other tokens are used to access other images:

	<img src="http://api.vodomodo.com/?webimage=020202020bbbbb&imagetype=thumb">		Thumbnail
	<img src="http://api.vodomodo.com/?webimage=030303030ccccc&imagetype=mthumb">		Mobile Thumbnail
	<img src="http://api.vodomodo.com/?webimage=040404040ddddd&imagetype=msmall">		Mobile Small Image
	<img src="http://api.vodomodo.com/?webimage=050505050eeeee&imagetype=mnormal">	Mobile Normal Image
	<img src="http://api.vodomodo.com/?webimage=060606060fffff&imagetype=mlarge">		Mobile Large Image
	


Video Key API Reference

Request Object Fields

Successful Response Object Fields

Error Response Object Fields

Example API Requests

	If you want the video for tour #123 and your API key is 2398df9sdyf9

	http://api.vodomodo.com?video&id=123&key=2398df9sdyf9       (will return success or failure API result)
	http://api.vodomodo.com?video&errors                        (will return API error documentation)
	http://api.vodomodo.com?video&help                          (will return API call documentation)
	

Example Response Objects (success and failure)

	<?xml version="1.0" encoding="ISO8859-1" ?>
	<videokey>
	   <id>9999</id>
	   <token>0909offuweu2u2hj344324</token>
	   <user>23947scds</user>
	</videokey>
------------------------------------------------------------------
	<?xml version="1.0" encoding="ISO8859-1" ?>
	<videokey>
	   <status>400</status>
	   <errors>
		<message>Invalid API KEY.</message>
		<message>Free account has expired.</message>
	   </errors>
	</videokey>
	

Video Key Usage

A video key can be used on the client device to access the Vodomodo web player, or to stream to mobile device without reveaing your private API credentials. In the example above, the video token '0909offuweu2u2hj344324' and user id '23947scds' are used to access the videos as follows:

	http://www.vodomodo.com/?p=mediaplayer&token=0909offuweu2u2hj344324&user=23947scds          (web player)
	http://www.vodomodo.com/mediafile.php?mediaid=0909offuweu2u2hj344324&user=23947scds         (streaming video)
	http://www.vodomodo.com/mediafile.m3u8?mediaid=0909offuweu2u2hj344324&user=23947scds        (iphone video stream)
	http://www.vodomodo.com/mediafile.php?mediaid=0909offuweu2u2hj344324&user=23947scds&android (android video stream)
	


Sample Code for Mobile Streaming

Download and review the following zip files to assist in learning to use the API on Android and iPhone devices. In each .zip file, you will find a PDF file that explains how to use the sample code in accessing the three primary API endpoints (getting a list of tours in a city, getting the tour details for a particular tour and streaming a video for a particular tour).

Android zip

iOS zip