UPDATE: this version of Peripleo is deprecated. To visit the new, updated version, see
or
http://github.com/pelagios/peripleo2 (source code)
API USERS: fret not! The new Peripleo version features a partially backwards-compatible API ("legacy compatibility API"). This means that most of the documentation below remains valid. Links and documentation text have been updated to reflect this.
Peripleo (Greek for "to sail", "to swim around") is a search & browsing engine for data in the Pelagios network. Peripleo is work in progress.
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 small archive of historical photographs, 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.
An overview of Peripleo & what you can do with it is available at the Pelagios project blog.
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.)
The API returns responses in JSON format. CORS and
JSONP are both supported. UPDATE: backwards-compatible API provides CORS-only
at the moment. 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://peripleo.pelagios.org/peripleo/search?query=gold
Results 21 - 40: http://peripleo.pelagios.org/peripleo/search?query=gold&offset=20
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://peripleo.pelagios.org/peripleo/search?query=bronze&prettyprint=true
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://peripleo.pelagios.org/peripleo/search, followed by any of these the filter parameters:
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://peripleo.pelagios.org/peripleo/search?query=gold+AND+coin
http://peripleo.pelagios.org/peripleo/search?query=athen*
http://peripleo.pelagios.org/peripleo/search?query=bvrdigala~
Restrict the results to place, dataset or item. Allows multiple values, as comma-separated list. Examples:
http://peripleo.pelagios.org/peripleo/search?query=coin&types=place
Restrict results to one or more specific datasets. (Separate multiple dataset IDs by comma.) E.g. find everything for 'mausoleum' in the Epigraphic Database Heidelberg:
http://peripleo.pelagios.org/peripleo/search?query=mausoleum&datasets=http%3A%2F%2Fedh-www...
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:
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://peripleo.pelagios.org/peripleo/search?bbox=23.716,23.7266,37.97,37.978
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://peripleo.pelagios.org/peripleo/search?query=athens&type=place&lat=37.97&lon=23.72&radius=3
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://peripleo.pelagios.org/peripleo/search?query=coin&from=-600&to=-500&types=item
http://peripleo.pelagios.org/peripleo/search?from=2014&to=2014
The API provides 'REST-style' access to entity metadata via the following URL paths:
UPDATE: not all methods were ported to the Peripleo v.2 legacy compatibility API. Please get in touch if you require further information.
/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.
The code for the Peripleo is licensed under the GNU General Public License v3.0.