Services

The following APIs are available:

• Geospatial Data API
• International Image Interoperability Framework (IIIF)
• Quantitative Data API
• OpenSearch API
• Linked Data API
• unAPI

Geospatial Data API

Many of the resources available in digital formats within the UCD Digital Library have a geographical context. Examples include:

• documentation describing or referencing points of interest;
• references to natural or man-made features;
• place of origin, including: place of publication, writer and addressee addresses in correspondence, etc.;
• graphical depictions of places, momuments, architectural sites, etc.

A typical example would be the recording of the song "Charming Edward Boyle," sung by farmer John Joe Murphy, which refers to the place where the recording was captured — the townland of Derryheanlish (County Fermanagh). In the descriptive metadata for this item, geographic references are encoded to provide a centroid value for the townland as well as references to identifiers in the Placenames Datbase of Ireland and OpenStreetMap:

                                <subject>
                                  <geographic
                                    authority="logainm"
                                    authorityID="//logainm.ie/"
                                    valueURI="//logainm.ie/59405.aspx">
                                    Derryheanlish (County Fermanagh, Ireland)</geographic>
                                  <cartographics
                                    authority="OpenStreetMap"
                                    authorityID="//nominatim.openstreetmap.org/"
                                    valueURI="urn:osm:relation_id:2097373">
                                    <coordinates>54.26240695,-7.16416493432504</coordinates>
                                  </cartographics>
                                </subject>
                            

UCD Library provides an applications programming interface, or API, that facilitates discovery and re-use of these data from the UCD Digital Library as well as the supporting geographic knowledge base.

The API supports several methods for identifying resources in the UCD Digital Library by geographical attributes. These are:

• id({PID}) — information about a particular resource identified by PID
• collectionId({PID}) — information about all resources that are part of a collection identified by PID
• nearby({Lat},{Lng},{dist}) — all resources within dist kilometres of point Lat,Lng
• bbox({{Lng,Lat,Lng,Lat}}) — information about all resorces referencing locations with the bounding box
• region({administrative_unit},{placename}) — information about all resources within the boundaries of the named place

Two additional methods return reference information from the UCD Library geographic knowledge base:

• geometryByID({{resource_identifier},{resource_ID}}) — return information about the place in resource_identifier identified by identifier
• geometryByName({placename}) — return information about all places named placename

The API accepts a range of additional parameters that enable control of how information returned is serialised, the maximum number of records to be returned, etc. Please refer to the full documentation for further details.

Web Mapping Supports

UCD Library provides supports for visualising map data provided via its Geospatial Data API. For example, the API is used with the UCD Digital Library web interface to visualise the geographic context of items described or represented there. With the above example of ithe song "Charming Edward Boyle,", a map can be built using coordinates and boundary data returned by the API showing the geographic area where the song was collected. The visualisation can include links to more information in the UCD Digital Library, or other sources such as the Placenames Database of Ireland and OpenStreetMap; the townland's boundary can also be provided using this information in conjunction with the Geospatial Data API:

The following examples demonstrate an approach to using the Geospatial Data API in conjunction with the LeafletJS javascript library for visualising maps using the methods of the UCD Library Geospatial Data API. In the demo application, the methods are applied via the query string parameters geoFilter (for search queries) and geoBounds (to request boundary data):

• id({PID}) — geoFilter=id(ivrla:31127)
• collectionId({PID}) — geoFilter=collectionId(ivrla:31284)
• nearby({Lat},{Lng},{dist}) — geoFilter=nearby(53.3366055,-6.2596153,5)
• bbox({{Lng,Lat,Lng,Lat}}) — geoFilter=bbox(-6.26976,53.318569,-6.092606,53.264802)
• region({administrative_unit},{placename}) — geoFilter=region(County,Tipperary)
• geometryByID({{resource_identifier},{resource_ID}}) — geoBounds=geometryByID(urn:osm:place_id,73775885)
• geometryByName({placename}) — geoBounds=geometryByName(Dublin)

The parameters geoFilter and geoBounds can also be combined in a single query:

• geoFilter=collectionId(ivrla:31284)&geoBounds=geometryByID(geonames,2964574)

International Image Interoperability Framework (IIIF)

The International Image Interoperability Framework (IIIF) provides an interoperable technology and community framework for image delivery, with the following goals (see: http://iiif.io/about.html:

• To give scholars an unprecedented level of uniform and rich access to image-based resources hosted around the world.
• To define a set of common application programming interfaces that support interoperability between image repositories.
• To develop, cultivate and document shared technologies, such as image servers and web clients, that provide a world-class user experience in viewing, comparing, manipulating and annotating images.

UCD Digital Library has implemented support for the IIIF Image and Presentation APIs, which serve images and metadata that enable IIIF-aware clients to view and compare images. Support has also been implemented for Mirador, a native IIIF client written in javascript.

IIIF Images API

The UCD Digital Library holds a wealth of visual still images and facilitates their discovery and inspection online. It also provides the ability to export images in various resolutions for non-commercial re-use. The Image Services API supports these simple export services in the Digital Library web environment, but it can also be used directly to exploit its full range of capabilities for advanced users.

The UCD DIgital Library Image Services API is based on the specification of the International Image Interoperability Framework: Image API 2.0. This API specification was conceived "to facilitate systematic reuse of image resources in digital image repositories maintained by cultural heritage organisations". It implements a RESTful web service that returns either image metadata or an image in response to standard HTTP requests. Requests for image metadata provide details of an images technical characteristics, whereas requests for images allow users to specify region, size, rotation, quality characteristics and format of the requested image.

For example, the two images below are served via the Image Services API. In the first, an image with a height of 180px was requested in JPEG format; in the second, the request indicated that a specific region of the image is requested in a more detailed resolution:

Calls to the API follow this template:

https://iiif.ucd.ie/loris/{identifier}/{region}/{size}/{rotation}/{quality}{.format}

For further details on how to express image attributes (such as "region" and "rotation") please see the IIIF Image API specification.

Getting Started

Images must be requested by the internal identifier, which takes the form of a namespace identifier and a numeric identifier, separated by a colon (':'). An example would be 'ivrla:31286'.

IIIF Presentation API

The IIIF Presentation API specifies a web service that returns JSON-LD structured documents that together provide metadata that describe the structure and layout of a digitised object or other collection of images and related content. These metadata describe a range of resource types, including manifests (the overall description of the structure and properties of the digital representation of an object), canvases (containers that represents a page or view and have associated content resources and which provides a frame of reference for the layout of a page), content (such as images), collections and more.

UCD Digital Library implements support for the IIIF Presentation API 2.0. This service is integrated with the UCD Digital Library Image Services API, following the syntactical template prescribed by the IIIF Presentation API:

Mirador: a native IIIF image viewer

UCD Digital Library has implemented support for Mirador, a native IIIF image viewer that "has been optimized to display resources from repositories that support the International Image Interoperability Framework (IIIF) API's. It provides a tiling windowed environment for comparing multiple image-based resources, synchronized structural and visual navigation of content using OpenSeadragon, Open Annotation compliant annotation creation and viewing on deep-zoomable canvases, metadata display, book reading, bookmarking and more."

UCD Digital Library's implementation of Mirador is experimental while we evaluate its deployment and the performance of the IIIF APIs. To make Mirador your default image viewer during your browser session, select the settings icon at the top of the page and check the box labeled "Use Mirador viewer."

UCD's Image Resizing, Cropping and Linking Tool

UCD Digital Library provides a bespoke tool to assist users in donwloading images from the Digital Library to match their own requirements. This service allows users to resize images, crop them to select only a specific region of the image, rotate images, etc. The tool provides a link to the image that can be used for persistent linking from another web site, for example, or one can download an image in the format (JPEG, PNG, GIF) of their choice. The tool is linked from the Mirador image viewer and is launched by clicking or touching the "Edit Image" link in the menu. For example, with the example above, clicking the "Edit Image" link will bring you to the image resizing, cropping and linking tool (illustrated below). Note that to recreate your bespoke image, you only need to use the link provided beneath the image.

Quantitative Data API

UCD Digital Library supports a Quantiative Data API to enable preview of variables and, in the case of open access resources, data values of survey datasets and similarly structured quantitative datasets that are represented with DDI 2.1 metadata.

Documentaiton for the API is available at:

http://data.ucd.ie/docs/apiQuant.pdf

The API provides methods to query for resource lists and metadata and to download open access datasets; methods are planned to enable a range of analytical tasks as well, namely, tabluations, correlations, and regressions. All responses are made in JSON format. Please consult the detailed documentation for further information.

For an example of the use of the Quantitative Data API, visit the record for the Open Access Irish National Election Survey (INES), which enables download of the dataset in multiple formats via the API, and uses JavaScript to enable exploration of survey metadata.

OpenSearch API

OpenSearch represents a way for providers of internet search services to syndicate search results or to enable third-parties to integrate a provider's search services into local applications. OpenSearch specifications and documentation are found at http://www.opensearch.org/.

The OpenSearch implementation at UCD DIgital Library is described in an OpenSearch Description Document at http://digital.ucd.ie/. It identifies the OpenSearch endpoint and search template for the service:

Responses are provided in RSS 2.0 XML format with the GeoRSS extensions to accommodate spatial references.

For further information on OpenSearch visit the OpenSearch web site or the article at http://en.wikipedia.org/wiki/OpenSearch.

Linked Data API

About Linked Data from the UCD Digital Library

UCD Library's Linked Data services have been conceived and implemented in conformance to precepts identified in Tim Berner-Lee's Linked Data -- Design Issues (2006; http://www.w3.org/DesignIssues/LinkedData.html) as well as principles of Linked Data and approaches to deployment of Linked Data services described in Tom Heath and Christian Bizer's Linked Data: Evolving the Web into a Global Data Space (1st edition). Synthesis Lectures on the Semantic Web: Theory and Technology, 1:1, 1-136. Morgan & Claypool; http://linkeddatabook.com/book.

Data is available through three means:

1. Dumps of RDF data in RDF-XML and N-Triples formats
2. Individual records via a Linked Data Services API
3. A SPARQL endpoint

A description of UCD Library's Linked Data services has been expressed using the VoID vocabulary (VoID is an RDF Schema vocabulary for expressing metadata about RDF datasets; see: http://www.w3.org/TR/void/). The description is accessible via its "well-known URI": http://data.ucd.ie/.well-known/void. Individual RDF documents also provide a VoID "backlink" to this description, e.g.,

<void:inDataset rdf:resource="http://data.ucd.ie/ld/void.ttl#UCDLibraryLOD"/>.

Data Services

RDF Data for Download

Linked Data from the UCD Digital Library is available for download as compressed file archives in RDF-XML and N-Triples formats:

Linked Data API

UCD Library provides a Linked Data API for accessing available RDF data by individual record identifier. A broad range of RDF serialisations is supported, including RDF-XML, N-Triples, N3/Notation3, N-Quads, Turtle, TriX, and JSON. Full documentation of the API is available at:

http://data.ucd.ie/docs/apiLOD.pdf

The Linked Data API is deployed as part of the general web API of the UCD Digital Library. The Web API enables users to reference information resources by URIs that include a resource identifier, called a PID, and a semantic qualifier that specifies a representation of the resource in any of a number of available formats, including several RDF serialisations. The default representation returned to users is HTML5; HTTP 303 redirects are used to return alternative representations of information resources. (See: "Cool URIs for the Semantic Web", http://www.w3.org/TR/cooluris/.)

The following table summarises the syntax for requesting specific representations of information resources managed within the UCD Digital Repository:

The Web API also supports HTTP content negotiation to facilitate machine-executed requests for representations of information resources.

unAPI

unAPI is

… a tiny HTTP API any web application may use to co-publish discretely identified objects in both HTML pages and disparate bare object formats. It consists of three parts: an identifier microformat, an HTML autodiscovery link, and three HTTP interface functions, two of which have a standardized response format.

UCD Digital Library deploys the unAPI protocol to expose descriptive metadata for citation download to unAPI-enabled clients, such as Zotero. The unAPI supports download of the following formats:

• oai_dc: OAI-ccompliant Dublin Core (XML)
• mods: MODS 3.X (XML)
• BibTeX
• RIS

The unAPI endpoint is at http://digital.ucd.ie/api/unAPI.