Annotation API Documentation
The Annotation API is allows users to search, obtain and contribute annotations about items in Europeana. Annotations are user-contributed or software-generated enhancements, additions or corrections to (or a selection of) metadata or content resources. We adopted the Web Annotation Data Model as a base model for the representation of annotations and as a format for exchanging annotations between client applications and the API, but also the Web Annotation Protocol as base protocol for the API.
The Annotation Data Model
What are annotations?
Annotations (in the Europeana context) are user-contributed or software-generated enhancements to (a selection of) metadata or content resource. The Annotations API adopted the Web Annotation Data Model (WADM) as a base model for representing and exchanging annotations between client applications and the API. The WADM is a W3C recommendation that describes a model and format to share annotations across different platforms.
Please note that, even though we have adopted WADM as underlying data model for this API, it is not expected that we support the full extent of the model. We thus advise to look at the EDM Annotations Profile which describes the basics of our implementation and, in particular, the section on Annotation Scenarios for a comprehensive list of the different kinds of annotations that we support.
Basics of the model
In WADM, an annotation is essentially a reified relation between two or more resources, typically a body and a target, and conveys that the body reflects what is intended to be said about the target. A body can also be absent to describe situations where a target is simply bookmarked. A target can represent a resource or just a part of it that is being annotated.
Being reified as a class enables an annotation to be further described with a motivation which expresses the reason why the annotation was created but also some provenance information such as the user that created the annotation and the software application that was used, as well as the times when it was initially created and sent to the API.
Annotation Scenarios
The Annotations API supports different types of annotations. This page explains the types of annotations that are currently supported, providing examples on how to represent them in the API.
The examples used in this Section are shortened versions of the Annotation Model, you can find an example of a complete Annotation Data Model implementation here.
Simple tags (without language)
A simple tag is a short textual description of a resource. This scenario only applies when the language of the tag is not known, otherwise see the scenario described in the next Section.
Examples: | church |
Requirement: | A maximum of 64 characters is allowed for a simple tag. A tag cannot be a URL. |
In the API: | Set the "motivation" to "tagging" and set the tag within the "bodyValue" field. |
Availability: | Since version 0.2.1. |
Simple tags (with language)
A simple tag is a short textual description of a resource.
Examples: | church |
Requirement: | A maximum of 64 characters is allowed for a simple tag. A tag cannot be a URL and the language information must be specified. |
In the API: | Set the "motivation" to "tagging" and set the tag within the "body" field as a Textual Body. |
Availability: | Since version 0.2.1. |
Semantic tags
A semantic tag is a tag to a resource from a controlled vocabulary, making it machine-interpretable.
Example: | This object in Europeana is somehow related to France (http://sws.geonames.org/2988507). |
Requirement: | Any URI is accepted as semantic resource. In the future, it will be limited to a controlled list of acceptable domains. |
In the API: | Set the "motivation" to "tagging" and set as body the URI for the semantic resource taken from a contolled vocabulary. |
Availability: | Since version 0.2.1. |
Object links
An object link is a relationship between two (Europeana) objects. This relationship can be any.
Example: | This object in Europeana is (in some way) similar to this object. |
Requirement: | An object link can only be made between two Europeana objects. |
In the API: | Set the "motivation" to "linking" and set as target an array containing the URIs of both objects. |
Availability: | Since version 0.2.1. |
Geo Tags
A geo-tag adds a geographical location to an item.
Example: | This object in Europeana was located at latitude 52.081131 and longitude 4.324053. . |
In the API: | Set the "motivation" to "tagging" and include the "type", "lat" and "long" attributes in the body as per the example below. |
Availability: | Since version 0.2.2. |
Annotating media resources
Annotating a media resource means that the target of the annotation is not the Europeana item but instead a specific media resource within that item.
In the API: | Set the "target" of the annotation to a JSON object with the "scope" holding the unique identifier of the Europeana item and the "source" field the URL of the actual media resource being annotated. |
Availability: | Since version 0.2.8. |
Transcriptions
A transcription is typically an annotation expressing a relation between an image and the text that is represented on that image. Besides the text, the annotation can also refer to a page where the text is displayed, like in the example below.
In the API: | Set the "motivation" to "transcribing" and apply the same criteria as for media resources. |
Availability: | Since version 0.2.8. |
Getting Started
Access keys
While this API is in an Alpha state you will need to use a separate API key (other than for the main Europeana REST API) to start using it. You can use the following keys:
Environment | Details |
---|---|
Test | API key apidemo with user token tester1 (allows to create, update & remove annotations on behalf of a test user in the Annotations API test environment). |
Production | API key apidemo (allows to search and retrieve annotations in the Annotations API production (live) environment). |
Creating annotations in the production (live) environment is currently limited to only selected partners, this will be opened up as part of the Beta release.
Request
Every Annotations API call is an HTTP request in a specified format that is sent to the Annotations API service. The API root URLs for the two environments are located at:
https://test-annotations.europeana.eu/annotation (test)
https://www.europeana.eu/api/annotations (production)
Response
This API only supports the JSON-LD format, which is the Linked Open Data version of JSON (with the same syntax as JSON). The request and response format does not need to be passed along to the API, if not provided it will fallback to the default. You can provide the format either via the URL (extension) or via the "Accept" header. To specify the request and response format you can either do:
/search.jsonld?wskey=xxxxx&query=*:*
Or:
Request header: "Accept: application/ld+json"
/search?wskey=xxxxx&query=*:*
Retrieving annotations
Retrieve annotations by their identifier.
GET /{provider}/{identifier}
Response
See data model for more information on the representation of an annotation.
Discovery
Search for annotations.
GET /search
Request
Search and Facet fields
The following table shows the fields that can be used for searching annotations and the ones that can be used for faceting:
Response
Provision
Using the PUT/POST/DELETE methods for this API is currently not publicly available.. You can request access to the write methods by emailing us with your use case.
Create
The API has a generic method available for the creation of annotations. The creation method expects a body payload in the request with the full annotation. Alternatively you can provide this information as part of the body parameter.
Request
Response
For more examples and information on the data model for an annotation, see data model.
Update
Update the contents of an annotation. For this you can send a PUT request to the ID of the annotation. You can only update the annotations you have created yourself.
PUT /base/1
Request
You can provide the same content in the Update method as you’d provide for the Create method. Note that you have to provide the full annotation body, you currently cannot update parts of the annotation.
Response
Delete
Delete an annotation. You can send a DELETE HTTP request using the ID of the annotation. You can only delete the annotations you have created yourself. Deletion means the annotation will not be available anymore for search, and only available for retrieval based on the ID of the annotation.
DELETE /base/1
Request
Response
Console
Roadmap and Changelog
The current version of the Annotations API is 0.3.3 (August 2022). It is currently available as a Public Alpha, which is the first public version released primarily to get feedback from you. Do note that this means that changes can be introduced which could break backwards compatibility. It also means that to use this API you need a separate API key than for the other Europeana APIs. To see the changes made for the current version and also all previous releases, see the API changelog in the project GitHub.
Credits
This API was initially developed as part of the Europeana Sounds project. It's development has been carried out by the AIT Austrian Institute of Technology in cooperation with the Europeana Foundation.