User Manual

User Manual

This is a work in progres (and in dire need of some restructuring)...

Google Field Trip

Google Field Trip (GFT) is a mobile travel discovery tool that shows points of interest around the user's geographical location (see also here). A number of Europeana collections have been selected to be offered through Google Field Trip. In order to facilitate this, our API provides a tailored RSS feed. The package eu.europeana.api2.v2.model.xml.rss.fieldtrip provides this functionality.

Here's a mockup RSS feed, showing only one item for brevity:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<rss xmlns:{xmlns gunk goes here}">
<channel>
    <title>Kuuluisa poro piilopaikkoja</title>
    <link>http://tama.on.sivusto.fi</link>
    <description>Sulatettu kävellä kutsua verinen turisteja katsomaan meidän suurin historiallinen poroa diskot Helmi Pohjoiseen</description>
    <language>fi</language>
    <image>
        <url>http://piilopaikkoja.fi/kaviot/johtajat.jpg</url>
    </image>
    <item>
        <guid>http://europeana.eu/portal/record/12345/kaviot.html</guid>
        <title>KAVIOT KNARRVIKEN</title>
        <link>http://tama.on.sivusto.fi/valituksiin/knarrviken.html</link>
        <description><![CDATA[<p>Vakavasti! Sinun pitäisi nähdä joitakin paikkoja näin ilmoitettu. 
            On hämmästyttävää, varsinkin kun otetaan huomioon, että heillä oli vain seitsemän metriä 
            punaista puuvillalankaa loitolla jääkarhuja</p>
            <p>Katso tämä sivu alkuperäisessä yhteydessään: <a href="http://www.nuuskaaminen.paikkoja.fi/huutaa-kaviot/noloa-tilaisuus.html">http://www.nuuskaaminen.paikkoja.fi/huutaa-kaviot/noloa-tilaisuus.html</a>
            <p>]]>
        </description>
        <fieldtrip:image>
            <url>http://tama.on.sivusto.fi/tilannekuvia/287_pohjoiseen.jpg</url>
            <attribution><![CDATA[<a href="http://creativecommons.org/licenses/by/3.0/">Copyrights</a> monimutkainen]]></attribution>
        </fieldtrip:image>
        <georss:point>68.324562 25.063433</georss:point>
        <pubDate>Wed, Aug 20 2014 13:36:43 +0200</pubDate>
    </item>
</channel>
</rss>

How the feed is populated

The data describing the items in the GFT rss feed comes from Solr. GFT also requires some collection-level information (e.g. a title, description, image) that is not available from Solr: this information is stored in the europeana.properties configuration file.

It was a requirement to insert the edm.shownAt link in the item's descriptive text. In order to be able to show the label for that link (e.g. show item in original context) in the same language as the description is in, we include the label text translations in our portal messages.properties files (at least for the languages of the selected collections). After the item's (or collection's) language is retrieved, the fitting translation is then retrieved and applied.

Here is shown how the various elements from the rss feed are populated:

in the API code

The entry point in the code for the rss query is the fieldTripRss() method in the class eu.europeana.api2.v2.web.controller.SearchController.java. First, the collection (channel in GFT terms) level data are retrieved from the europeana.properties file using getGftChannelAttributes() in eu.europeana.corelib.web.support.Configuration.java. Then Solr is queried to retrieve the collection; then, for each item, we retrieve that item's language property (if that's not found, we use the collection's language property stored in europeana.properties) and retrieve the label text translation for that language via the existing Spring's MessageSource mechanism (used extensively in the Portal).

Then, in eu.europeana.api2.utils.FieldTripUtils.java, we add this label text plus the edm.shownAt URL to each item's description field. In that class we also add the other required Solr fields to the item. The collection-level information and the items are then assembled into a rss stream in eu.europeana.api2.v2.web.controller.SearchController.java.

## Important database tables

###apikey

Columns:

• apikey (string): the public API key
• privatekey (string): a secret second API key (the two key should be used in login form as name/password pair)
• usagelimit (int): how many times a user can access the API
• userid (int): reference to an existing user identifier (see user table). One user might have multiple apikey.

###users

• id: user identifier
• apikey: API key, but it is not in use as far as I know it
• email: email
• enabled (boolean): the user is enabled to use API
• firstname: first name
• languages:
• lastlogin: last time the user logged in for personal page
• lastname: user's last name
• newsletter:
• password: user's password (in encripted form)
• projectid:
• providerid:
• registrationdate: when he registrated
• role:
• username: username when login

## Usage of API2 form command line

To improve the understandability of the API documentation here is a short example of how to use it with cURL tool. It helps to create a similar implementation with your own favorite tool.

Request the session identifier:

First you have to POST the api2key and secret parameters to the /login page

request: $ curl -i -d "api2key=[your api key]&secret=[your secret key]" "http://localhost:8080/api2/login"

response:

1. HTTP/1.1 302 Moved Temporarily

2. Server: Apache-Coyote/1.1

3. Set-Cookie: JSESSIONID=54B3FED3649FD8D205C297A52363825B; Path=/api2; HttpOnly

4. Location: http://localhost:8080/api2/

5. Content-Length: 0

6. Date: Fri, 13 Jul 2012 10:41:40 GMT

In line 3 you can find the session ID in the form of a key=value pair. This is JSESSIONID=54B3FED3649FD8D205C297A52363825B

You have to extract it, and use it in later requests.

Use the session identifier:

Now use this session identifier as cookie: $ curl -i -b "JSESSIONID=54B3FED3649FD8D205C297A52363825B" "http://localhost:8080/api2/search.json?query=john"

The response will be:

HTTP/1.1 200 OK Server: Apache-Coyote/1.1 Content-Type: application/json Transfer-Encoding: chunked Date: Fri, 13 Jul 2012 10:42:09 GMT { "apikey": "[your api key]", "action": "search.json", "success": true, "statsDuration": 0, "itemsCount": 12, "totalResults": 880, "items": [{...},{...}...] }

As you can see the application now returns good response, the content type is JSON, and you actually get the JSON result.

cURL parameters used in this short tutorial:

-i Include protocol headers in the output. With applying this you can see the HTTP headers. -d DATA HTTP POST data. The format of the data is URL encoded. -b STRING String to read cookies from.