EU Latitude API documentation

Concept

For a simpler use, this API is following the REST concept : only simple GET or POST requests with the right variables are needed. All the methods are called on the same URL : http://api.discover-eu.com/

A mandatory variable will precise the method to call : METHOD

Each call without this METHOD variable will bring back to the documentation.

The same method will be available through SOAP or XML-RPC in a later version.

Authentification key

Most of the methods needs an authentification key that can be asked to the project team.

This key will determine which content is available : free public content only, or publisher content also. This key should be given in the variable : KEY

Each call to a method needing the key, and the key is absent, will bring back to the documentation.

Objects available

The main object of our database is the « Item ».

An item usually contains contents (one now, more later) from different sources, a contact and is most of the time geolocalised. All of the items managed have one of the following classes :

ADD : A simple address like a restaurant or a museum. They have the following types :
- 1 : Hosting
- 2 : Restaurant
- 3 : To do / To see
- 4 : Practical information
- 5 : Events
- 6 : Encyclopedia
GEM : A gem : a "must see", contains links to additional addresses to make a full stay. They have the following topics :
- 1 : Gastronomy and accomodation
- 2 : Landscapes and nature
- 3 : Art and cultural heritage
WAY : A way containing several Gems or Addresses

Results

Results have the following XML format : <response> <item> <id>3242</id> <name>POI official name</name> <class>ADD</class> <type>3</type> <title>POI editorial title</title> <published>2009-04-02 15:17:39</published> <date>2009-05-14 12:45:22</date> <content> <chapo>Tantus est igitur innatus in nobis cognitionis amor et scientiae ut nemo dubitare possit</chapo> <text>Tantus est igitur innatus in nobis cognitionis amor et scientiae ut nemo dubitare possit</text> <practical>Tantus est igitur innatus in nobis cognitionis amor et scientiae ut nemo dubitare possit</practical> </content> <address> <street>109, rue Oberkampf</street> <zip>75011</zip> <city>Paris</city> <country>France</country> <latitude>48.8658</latitude> <longitude>2.37791</longitude> </address> <image> <id>picture-id</id> <copyright>copyright of the pucture</copyright> </image> <contact> <name>Contact name</name> <tel1>01 44 94 89 90</tel1> <tel2/> <email1>mail@domaine.net</email1> <web1>http://www.site.com/</web1> </contact> <source>Source Name</source> <attached/> </item> <item> (...) </item> </response>

Content can contain specific semantic tags :

[cite] [/cite] : quote, author name should usually be displayed in italic
[strong] [/strong] : important content, should usually be displayed in bold

Methods

The different available methods are the following

Test

Test method, don’t need a key. Send back the argument given in the REQUEST variable in an XML. Arguments :

METHOD : method name, should be the string « test »
REQUEST : argument, should be a string

Example using GET : http://api.discover-eu.com/?METHOD=test&REQUEST=hello Send back « hello » in a structured XML.

searchFull

Full research method

Arguments :

METHOD : method name, should be the string 'searchFull'
KEY : the key given by the project team
REQUEST : an XML request in the format described below
LANG : content language (default : fr)
MAX : maximum number of elements to send (default :20)
PAGE : page number to send (default :1)
OUTPUT : type of output (default : XML)

REQUEST format:
REQUEST is an XML starting by the tag Inside, the following tags can be found : <id> send the item having this ID. If several tags, send items having id1 OR id2 OR … <class> send items having this class. If several tags, send items having class1 OR class2 OR … <tag> send items having this tag. If several tags, send items having tag1 AND tag2 AND tag3. Tags are a tree. It a tag is asked, his child are asked too. <link role=""> send items linked to others. The link role can be precised by the « role » attribute. Inside the tag, a sub-request should be put. <startdate> send items available after this date. <enddate> send items available before this date. <modifiedAfter> send items modified after this date. <around> send items close to a position. Need the sub-tags : <latitude> latitude <longitude> longitude <radius> distance to the point in km </around> <picture>1</picture> only items having picture <audio>1</audio> only items having audio <video>1</video> only items having video Dates are in the format YYYY-MM-DD
Example :
<request> <class>GEM</class> <class>ADD</class> <tag>HOS.01.01</tag> <tag>HOS.02.03</tag> </request> OUTPUT :
Only XML is available for the moment with items and their contents attached (according to the rights given by the key).
More output formats will be added later like CSV or others according to the needs.
Result values given for the pictures, audio, video included in the XML have to be used with the getPicture, getAudio, getVideo methods described below respectively.
Test searchFull

search

Simpler and faster search method without XML request.
Arguments :

METHOD: method name, should be the string 'search'
KEY: the key given by the project team
LATITUDE: latitude
LONGITUDE: longitude
RADIUS: distance to the point in km
CLASS: filter to get only those item (default : none)
TAG: filter to get only item having this Tag or one below ; to use multiple tags, separate them by a coma (default : none)
PICTURE: if not null, only items having picture
AUDIO: if not null, only items having audio
VIDEO: if not null, only items having video
MODIFIEDAFTER: only items modified after or at this date
STARTDATE: only timed items available after or at this date
ENDDATE : only timed items available before or at this date
LANG: content language (default : fr)
MAX: maximum number of elements to send (default :100)
PAGE: page number to send (default :1)
OUTPUT: type of output (default : XML)

Dates are in the format YYYY-MM-DD

OUTPUT :
Only XML is available for the moment with items and their contents attached (according to the rights given by the key).
More output formats will be added later like CSV or others according to the needs.
Result values given for the pictures, audio, video included in the XML have to be used with the getPicture, getAudio, getVideo methods described below respectively.
Test search

getPicture

Get a picture from its name (the one given by XML). They are always given in JPEG format.
Arguments :

METHOD : method name, should be the string 'getPicture'
KEY : the key given by the project team
PICTURE : name of the picture
FORMAT : Format of the pic, can be :
- thumb : thumbnail, either 150x100 or 75x100 pixels according to orientation
- small : small picture for mobile device, 320 pixels max in the bigger dimension, width or height according to orientation.
- default : full definition picture, according to the source.

getAudio

Get an audio from its name (the one given by XML). They are always given in MP3 format.
Arguments :

METHOD : method name, should be the string 'getAudio'
KEY : the key given by the project team
AUDIO : name of the audio

getVideo

Get a video from its name (the one given by XML). They exist either in Macromedia FLV format, or MP4 H264 format. However, Mime Type is ever video/mpeg
Arguments :

METHOD : method name, should be the string 'getAudio'
KEY : the key given by the project team
AUDIO : name of the audio

More method will be added as needed.