Peripleo

Peripleo (Greek for "to sail", "to swim around") is a search & browsing engine for data in the Pelagios network. Peripleo is work in progress.

Background - the Pelagios Initiative

Pelagios (Greek for 'of the Sea') is a community network that facilitates linking of online resources that document the past, based on the places they refer to. From the large epigraphic database to the personal Flickr photostream, each of our partner datasets represents one piece of the puzzle. Pelagios combines these pieces into a coherent whole that enables connection, exchange and discovery - just as the Mediterranean Sea did for the Ancient World.

Peripleo

An overview of Peripleo & what you can do with it is available at the Pelagios project blog.

Peripleo API

The Peripleo API provides machine access to our data. The 'mental model' behind Peripleo is simple! It consists of only three types of entities:

• Items such as archaeological artefacts, literary texts, photographs, etc.
• Places to which these items are related, e.g. places mentioned in a text or the findspot of an artefact
• Datasets which are collections of items, e.g. a particular museum collection or data corpus published by an institution

Datasets as well as items can be hierarchical. (E.g. the Pelagios 3 dataset is sub-divided into a corpus of Greek and Latin literary texts. Likewise, an item such as Herodotus' The Histories can be subdivided into individual Books.)

Response Format

The API returns responses in JSON format. CORS and JSONP are both supported. Most responses are paginated, i.e. you will get back only one "page" of results:

{
  "total" : 112,
  "limit" : 20,
  "items" : [
    ...
  ]
}

You can traverse pages using an offset and limit (= page size) parameter. If limit is omitted, it will default to a page size of 20. Example:

Results 1 - 20: http://pelagios.org/peripleo/search?query=gold

Results 21 - 40: http://pelagios.org/peripleo/search?query=gold&offset=20

Pretty Printing

Per default, the API will return a compact, unformatted JSON response. You can force a more human-readable response by appending a prettyprint=true parameter. Example:

http://pelagios.org/peripleo/search?query=bronze&prettyprint=true

Searching the API

The main feature you'll probably want to use is search. You can search the API by keyword, place (gazetteer URIs), space (geographic area), time interval, dataset, object type (i.e. place, item or dataset) - or any combination of those. A typical search result record looks like this:

{
  "identifier" : "bb4e2f4b0bc7f4d6c065cb5167f4d3f831ccf795af0204f2647f8ec1bbcabcba",
  "title" : "Periplus of the Euxine Sea",
  "object_type" : "Item",
  "temporal_bounds" : {
    "start" : 130,
    "end" : 130
  },
  "geo_bounds" : {
    "min_lon" : 23.7195,
    "max_lon" : 44.0,
    "min_lat" : 37.5197,
    "max_lat" : 45.5
  }
}

The identifier, title and object_type labels are always present. Depending on the object, the record can also include a short textual description, the bounds of the object in space and time (geo_bounds and temporal_bounds, respectively) and a lists of URLs to depictions (images).

In case the result represents and item (rather than a place), the record can also include a homepage URL for the item, and the dataset_path, i.e. the hierarchy of datasets the item is in. In case the result reprents a place, the record will include a list of variant names and, potentially, a list of matches - additional identifier URIs, under the same place is registered in other gazetteers.

You can retrieve more information about a record (such as all places related to an item, or information about sub-items) through REST-style access (see below), using the record's identifier as a key.

The base URL for search is http://pelagios.org/peripleo/search, followed by any of these the filter parameters:

query

A keyword query. Per default, only exact matches are returned. Supports logical AND and OR operators, and trailing asterisk for prefix queries. (Note that logical operators need to be uppercase!) If you want to run a fuzzy search, which will also match similar - but not necessarily identical - terms, append a '~' to your query term. Examples:

http://pelagios.org/peripleo/search?query=gold+AND+coin

http://pelagios.org/peripleo/search?query=athen*

http://pelagios.org/peripleo/search?query=bvrdigala~

types

Restrict the results to place, dataset or item. Allows multiple values, as comma-separated list. Examples:

http://pelagios.org/peripleo/search?query=coin&types=place

datasets

Restrict results to one or more specific datasets. (Separate multiple dataset IDs by comma.) E.g. find everything for 'mausoleum' in the Following Hadrian photo collection:

http://pelagios.org/peripleo/search?query=mausoleum&datasets=ca222503...

places

Restrict to one or more places. Places are identified by a comma-separated list of gazetteer URIs. (URIs need to be URL-escaped!). If more than one place is specified, they are logically combined to an AND query. That means the search will return items related to all of the places in the list. E.g. find everything that refers to both Rome AND Syria:

http://pelagios.org/peripleo/search?places=http:%2F%2Fpleiades.stoa.org%2Fplaces%2F981550,htt...

bbox

Restrict to a geographic bounding box. The bounding box must be specified as a comma-separated list of decimal (WGS-84 datum) numbers, according to the format bbox={minLon},{maxLon},{minLat},{maxLat}. Example:

http://pelagios.org/peripleo/search?bbox=23.716,23.7266,37.97,37.978

lat, lon, radius

Alternatively, you can restrict to a geographic area by specifying a center lat, lon coordinate for your search, and a radius (in km). If you omit the radius, it will default to 10km. Note: if you specify both a bbox parameter and a coordinate, coordinate and radius will be ignored, and the bounding box will take precedence.

http://pelagios.org/peripleo/search?query=athens&type=place&lat=37.97&lon=23.72&radius=3

from, to

Restrict the results to a specific time interval. Both parameters take an integer number, which is interpreted as year. (Use negative numbers for BC years.) If you are interested in one specific year only, use the same value for from and to. Note: items in Pelagios that are not dated will not appear in the results. Examples:

http://pelagios.org/peripleo/search?query=coin&from=-600&to=-500&types=item

http://pelagios.org/peripleo/search?from=2014&to=2014

REST-Style Access

The API provides 'REST-style' access to entity metadata via the following URL paths:

• /peripleo/datasets - list all datasets
• /peripleo/datasets/{id} - get the dataset with the specified ID
• /peripleo/datasets/{id}/items - list all items contained in this dataset
• /peripleo/datasets/{id}/places - list all places related to the items in this dataset *)
• /peripleo/datasets/{id}/time - get the 'temporal profile' of the dataset **)
• /peripleo/items/{id} - get the item with the specified ID
• /peripleo/items/{id}/items - list sub-items to this item
• /peripleo/items/{id}/places - list all places related to this item
• /peripleo/places/{uri} - get information about the place with the (URL-escaped!) URI

*) Append verbose=false as query parameter to receive a less verbose response. This response will have additional performance benefits and load faster than the full response. Usually, you will only need this if you retrieve many places in one request, by setting a high page size limit.

**) The temporal profile is an aggregation of the date information of all items contained in the dataset. It consists of a start and end year for the dataset, and a 'histogram' that plots the number of items over the start-to-end time interval.

License

The code for the Peripleo is licensed under the GNU General Public License v3.0.