The Annotations API is an extension to the Europeana REST API which allows you to create, retrieve and manage annotations on Europeana objects. Annotations are user-contributed or system-generated enhancements, additions or corrections to (or a selection of) metadata or media. 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 HTTP protocol for the API.
The EuropeanaConnect Annotation Suite - A tool that allows end-users to annotate digital images, maps, audio and video files.
Roadmap and Changelog
The current version of the Annotations API is 0.2.8 (January 2018). 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.
Annotations (in the Europeana context) are user-contributed or system-generated enhancements to (a selection of) metadata or media. The most well-known type of annotation is the "tag", a short textual depiction of something. Annotations allow for the creation of meaningful connections across Europeana and will also offer up new ways to explore or find the content you're looking for.
The Annotations API adopted the Web Annotation Data Model (or simply WA) as a base model for exchanging annotations between client applications and the API. It is a W3C recommendation that describes a model and format to share annotations across different platforms.
Please note that, even though we have adopted WA 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 WA, 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.
REPRESENTATION IN JSON-LD
The URL of the JSON-LD context. (always with value "http://www.w3.org/ns/anno.jsonld")
The identifier of the Annotation. It is automatically generated unless a local identifier is specified upon creation.
Always has the values of "Annotation".
The time at which the Annotation was created by the client application. It must be expressed in ISO8601 format and should have a timezone specified.
The agent responsible for generating the Annotation. Typically a client application used to create the annotation.
Expresses the reason why the annotation was created. The value can be either "tagging", "linking" or "transcribing".
String or Object (Semantic Resource or Textual Body)
A body conveying what is intended to be said about the target. If the value is provided as a string, then it is interpreted as the URI and must only be used for the semantic tagging scenario. See the application scenarios section for more information.
A string conveying the tag text. This field must only be used in combination with "tagging" as motivation and when the language of the tag is not known. Otherwise, it is recommended to use the body field as defined in the Application Scenarios section.
The URL of the resource that is being annotated, or a specific resource in the case of media annotations. An array of URLs may also be set (mostly used for the object linking).
The URL of the annotation, if available in an external service.
An Agent can be either a Person or a Software. Typically the Person corresponds to the user that created the annotation while the Software reflects the client application that was used to create it. A Software can also create annotations if they result from an automatic process.
Either "Person" or "Software".
The name of the agent. Either the name of the user that created the annotation, or the name of the client software that was used to create it.
The homepage of the user or client application, if available.
A Semantic Resource is used whenever an external resource needs to be referenced as the body of the annotation. It is mostly used for Semantic Tagging.
The URI of the resource being referred as body.
The ISO639 language code corresponding to the language of the resource.
Annotations that refer to a media resource require that a oa:SpecificResource object is defined so that the context in which the annotation was made is captured by the annotation. Besides context, a Specific Resource can be used to capture any additional information about how a target is used in the Annotation. The following table lists the properties supported by this class.
The URL that identifies the media resource which is the ultimate target of the annotation.
The unique identifier of the Europeana item to which this media resource is associated to. In more general terms, scope is used to define the context in which the annotation was made, in terms of the resources that the annotator was viewing or using at the time.
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.
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:
For reading requests (GET) you need to authenticate by passing along your API key as the wskey parameter. Example (replace YOUR_KEY with your API key):
For writing requests (POST/PUT/DELETE) on behalf of a user you need to pass along your API key as the wskey parameter along with a user token as the userToken parameter. Example (replace YOUR_KEY with your API key and YOUR_TOKEN with the user token):
An error during processing of an API method is reported by (1) a relevant HTTP status code, (2) a value of the success field and (3) a meaningful error message in the error field.
The following HTTP status codes are returned:
The request was executed successfully.
Authentication credentials were missing or authentication failed.
The requested annotation was not found.
The request could be served because the application has reached its usage limit.
Internal Server Error. Something has gone wrong, which we will correct.
ANNOTATION API METHODS
Search for annotations.
The search term(s), this is mandatory.
The search profile which determines the extent of information returned as search result. Currently, two options are supported: "minimal" which returns only the identifier of the annotation; and "standard" (the default) which returns the annotation as it was sent to the API.
Query filter, to search on specific fields. The list of fields is presented below.
Includes a field to be used as facet in the response (see below which fields can be used as facets). More than one field can be added if separated by a space.
The number of records to return per page. For minimal profile, the maximum is 10.000 while for the standard profile is 100, with 10 as default for both profiles.
The page of the search results, defaults to 0 (first page).
Includes a field to be used for sorting. One of: created, generated or modified.
Order of sorting, either "asc" (ascending) or "desc" (descending).
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:
motivation of the Annotation
complete identifier of an Annotation
local identifier of an Annotation (/<provider>/<identifier>)
complete identifier of the generator
name of the generator
date on which the Annotation was first provided to the API
complete identifier of the creator
name of the user that created the annotation
date on which the Annotation was created by the annotation client application
date on which the Annotation was last modified
sum of all reports made to an Annotation by other users
searches in all searchable text in an Annotation
value within the body of an Annotation, applies to e.g. simple tagging
complete identifier of the resource within the body of an Annotation, applies to e.g. semantic tagging
complete identified of the target(s) of an Annotation
local identifier of a record when the target is a record (/collectionId/objectId)
complete identifier of the resource being linked to (ie. through the relation property)
Example: Don't show annotations which are reported by two or more different users:
/search?wskey=xxxxx&profile=minimal&query=*:*&qf=moderation_score:[-1 TO *]
Note that providing *:* as a search query means you will get all annotations.
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.
Delete an annotation. For this 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 /collections/1 HTTP/1.1
HTTP/1.1 204 NO CONTENT
Use the API Console to experiment with the API and build queries. The Request URL will display the call you need to make to the API.
The console below points to the production environment, to use the API console for the test environment click here.
Europeana Annotations - REST API
This Swagger API console provides an overview of and interface to the Europeana Annotations REST API. For more help and information, head to our comprehensive online documentation.
Europeana empowers the cultural heritage sector in its digital transformation. We develop expertise, tools and policies to embrace digital change and encourage partnerships that foster innovation.
All texts are CC BY-SA, images and media licensed individually. Europeana Foundation is registered at the Chamber of Commerce under number 27307531, RSIN number is 8186.80.349.
FIND US ELSEWHERE
Europeana is an initiative of the European Union, financed by the European Union’s Connecting Europe Facility and European Union Member States. The Europeana services, including this website, are operated by a consortium led by the Europeana Foundation under a service contract with the European Commission.
The European Commission does not guarantee the accuracy of the information and accepts no responsibility or liability whatsoever with regard to the information on this website. Neither the European Commission, nor any person acting on the European Commission’s behalf, is responsible or liable for the accuracy or use of the information on this website.
Hi! Could we please enable some additional services for analytics and security? You can always change or withdraw your consent later.