In February, we launched an extension to the Europeana REST API: the Annotations API. Now, you can use it to generate, update and retrieve short descriptions for objects of our collections – these descriptions are called annotations. Another definition for annotations is user-contributed or system-generated enhancements, additions or corrections to metadata or media. An example (and the most well-known type) of annotation is the "tag", a short textual depiction about a digital resource.

By involving our users into improving and enhancing our data, the Annotations API creates connections across Europeana, facilitating the search and discovery of items in our systems.

Sample use-case: Portrait of a girl

We have selected the lovely Russian painting below to showcase the types of annotations currently supported by Europeana Annotations API. The examples of representations that are developed here are shortened. Check out the complete versions on the Data Model.

Portrait of a girl, unknown artist, 1800-50. Rybinsk State Architectural, Historical and Art Museum, Public Domain.

Firstly, you need to use a different API key (other than for the main REST API) to start experimenting with the Annotations API. You will also have access to a test environment where you can freely add annotations.

Simple tags

A simple tag is a short textual description. How would you tag the Russian artwork? Painting, girl, flower are examples of tags that could be used. In the API: Set the "motivation" to "tagging" and set the tag as the "body" value.

Example representation

{
"motivation": "tagging",
"body": "painting",
"target": "http://data.europeana.eu/portal/record/2023831/kng_item_item_jsf_id_89"
}

Semantic tags

A semantic tag is a tag to a resource from a controlled vocabulary, making it machine-interpretable. Currently, any URL is accepted as semantic resource. In our example, the artwork portraying a girl is related to Russia, which means we could use an URL to the Russian map as an annotation.

In the API: Set the "motivation" to "tagging" and set as body an object containing both @type as SpecificResource and as source the URL for the semantic resource taken from a controlled vocabulary.

Example representation

{
"motivation": "tagging",
"body": {
"@type": "SpecificResource",
"source": " http://www.geonames.org/500004/rybinsk.html"
},
"target": "http://data.europeana.eu/portal/record/2023831/kng_item_item_jsf_id_89"
}

Object links

An object link is a relationship between two (Europeana) objects. This relationship can be any, but it can only be made between two Europeana objects. The Russian painting above, for instance, is related to other artworks which are also from the Rybinsk State Architectural, Historical and Art Museum.

In the API: Set the "motivation" to "linking" and set as target an array containing the URIs of both objects.

Example representation

{
"motivation": "linking",
"target": [
"http://data.europeana.eu/portal/record/2023831/kng_item_item_jsf_id_7",
"http://data.europeana.eu/portal/record/2023831/kng_item_item_jsf_id_89"
]
}

Ready to tag away?

Get started and help us testing the Annotations API! Share your opinion on the Europeana API discussion group or to api@europeana.eu.

Your feedback will be used to make improvements and add more features to the final version to be released in 2017.