Pelagios WP1 at a Glance - Pt.1: The API

As the Pelagios 2 project is coming to a close, I'd like to wrap up our infrastructure work package (WP 1) with a series of posts on the software and tools we've been producing. In this first post I want to showcase the main tangible result from WP 1: the Pelagios API (or Deliverable 1.2, in project management terms).

The Pelagios API enables you to search and browse the data we are aggregating from our partners. It has a basic HTML interface, so you can click your way through the Pelagios network of places, datasets and place references. Your starting point can be either a particular place or a particular dataset. You can search for those by name, or - in case of the datasets - browse the list.

Places in the API

Olympia in the API

The API user interface provides views on the different objects in Pelagios: Places are shown with some basic metadata from their original Pleiades source entry, including labels, a description, their feature type, and so on. A table underneath the place description lists the references the Pelagios network has for that place, sorted by partner dataset; and clicking an entry will take you to the list of references for that place, in that particular dataset.

Below the list, you will find the neighbourhood cloud. This little gadget looks like one of the tag clouds often seen on blogs or social bookmarking sites, where they usually visualize the frequency of often-used words or tags in the system. This way, users can get a quick overall grasp of what the content on a particular site might be about.

The Pelagios neighbourhood cloud has a slightly different purpose: it shows neighbour places - not in a geographical sense, but in terms of how they are connected in the graph. Larger tags mean that the neighbour is "stronger" connected to the place than others.

We are still fiddling with the ranking metrics, but in a nutshell, a "strong" connection (as regards our current visualization) is one that runs through datasets that are primarily concerned with those two places. For example: see how the cloud for Thermopylae will render a neighbourhood to Lacedaemonia, Sparta and (to a slightly lesser extent) Salamis; or how the Island of Sardinia sits nicely between places in Italy and North Africa.

Datasets in the API

Datasets have similar overview pages. As for places, these show some basic metadata for the dataset (title, description, license terms, etc.) and list the subsets contained in this dataset. The view also shows a small bar graph listing the five most frequently referenced places.

Machine-Access

But the main purpose of the API is, as the name implies, not the user interface - it is to serve out machine-actionable representations of our data. To this end, the API provides responses in RDF (currently in XML and Turtle serialization), as well as JSON (with support for Content Negotiation). Cross domain requests to the API (essential for supporting client-side mashups) are supported through JSONP and CORS.

In terms of functionality, the API offers everything that's in the user interface, plus a few additional features which are not (yet) found there, including

• geographical search
• "geo-footprints" for datasets, i.e. the geographical area covered by all places referenced in a dataset
• configurable pagination for everything that comes in long lists (e.g. place references in a particular dataset)
• shortest path search between two places in the graph

The Pelagios API public beta is located at http://pelagios.dme.ait.ac.at/api

Technical documentation is part of our cookbook, available here.

Rainer Simon,
Austrian Institute of Technology

Continue with part 2 of this post.