The Annotation API is an extension to the Europeana REST API which allows you to create, retrieve and manage annotations on Europeana objectsallows users to search, obtain and contribute annotations about items in Europeana. Annotations are user-contributed or systemsoftware-generated enhancements, additions or corrections to (or a selection of) metadata or mediacontent 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 HTTP protocol for the API.

The Annotation Data Model

Anchor
annotationdatamodel annotationdatamodel

What are annotations?

Annotations (in the Europeana context) are user-contributed or systemsoftware-generated enhancements to (a selection of) metadata or mediacontent resource. 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 (WAAnnotations API adopted the Web Annotation Data Model (WADM) as a base model for representing and exchanging annotations between client applications and the API. It 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 WA 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 the Web Annotation Data Model 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.

Field

Datatype

Description

Agent

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

Field

Datatype

Field

Datatype

Description

name

String

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.

homepage

String

The homepage of the user or client application, if available.

Semantic Resource

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.

Media Resource

Annotations that refer to a media resource require that an oa:SpecificResource object is defined so that

Optional and mandatory fields

Application Scenarios

Because annotations are a very flexible construct, in theory, any kind of information could be represented as an annotation. However, to guarantee consistency of the annotations and their proper display or reuse, a range of “use cases” for annotations were identified, modelled and implemented which we call application scenarios. This list can grow as new and relevant use cases are identified and proposed for adoption.

This section explains all the application scenarios that are presently supported with examples on how they are represented in the API.

The examples used in this Section are shortened versions of the Annotation Model which exclude administrative fields such as created, creator, generated, generator, you can find an example of a complete Annotation Data Model implementation here.

1. Tagging (without language)

A tag is a short textual label for a resource. It can be used to e.g. classify or name a resource. This scenario only applies when the language of the tag is not known, otherwise see the scenario described in the next Section.

{
  "motivation": "tagging",
  "bodyValue": "painting",
  "target": "http://data.europeana.eu/item/92062/BibliographicResource_1000126189360"
}

2. Tagging (with language)

A language tag is a short textual label for a resource that is qualified with a language. Similarly as the previous scenario, language qualified tags can be used to name or classify a resource.

{
  "motivation": "tagging",
  "body": {
    "type": "TextualBody",
    "value": "painting",
    "language": "en"
 },
  "target": "http://data.europeana.eu/item/annotations/1",
  "type": "Annotation",
  "created": "2015-03-10T14:08:07Z",
  "creator": {
    "type": "Person",
    "name": "John Smith"
  },
  "generated": "2015-04-01T09:00:00Z",
  "generator": {
      "type": "Software",
      "name": "HistoryPin",
      "homepage": "https://www.historypin.org/"
  },
  "motivation": "tagging",
  "bodyValue": "MyBeautifulTag",
  "target": "http://data.europeana.eu/item/92062/BibliographicResource_1000126189360"
}

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.

92062/BibliographicResource_1000126189360"
}

3. Semantic tagging

An annotation of a CHO with a semantic tag. A semantic tag is a tag from a controlled (linked data) vocabulary such as VIAF or AAT. As any other tag, semantic tags are typically used to classify a resource with the benefit of bring extra information to the annotation as the result of being a linked data resource.

{
  "motivation": "tagging",
  "body": "http://sws.geonames.org/2988507",
  "target": "http://data.europeana.eu/item/09102/_UEDIN_214"
}

4. Geospatial tagging witch coordinates

An annotation of a CHO with a location given in geospatial coordinates (latitude, longitude, and optionally altitude). In addition, there can be a label expressing the name or address of the location.

{
  "motivation": "tagging",
  "body": {
    "@context": "http://www.europeana.eu/schemas/context/entity.jsonld",
    "type": "Place",
    "prefLabel": {
      "en": "A label for the location, e.g., an address or place name"
    },
    "lat": "48.85341",
    "long": "2.3488"
  },
  "target": "http://data.europeana.eu/item/09102/_UEDIN_214"
}

5. Geospatial tagging with an address

An annotation of a CHO with a location given in geospatial coordinates (latitude, longitude, and optionally altitude). In addition, there can be a label expressing the name or address of the location.

{
  "motivation": "tagging",
  "bodyValuebody": "painting", {
    "target@context": "http://datawww.europeana.eu/itemschemas/92062/BibliographicResource_1000126189360"
}

Simple tags (with language)

A simple tag is a short textual description of a resource.

{
  "motivation": "tagging",
  "body": {
    "type": "TextualBody",
    "value": "painting",
    "language": "en"
 },
  "target": "http://data.europeana.eu/item/92062/BibliographicResource_1000126189360"
}

Semantic tags

context/entity.jsonld",
    "type": "Place",
    "prefLabel": {
      "en": "A label for the location, e.g., an address or place name"
    },
    "lat": "48.85341",
    "long": "2.3488"
  },
  "target": "http://data.europeana.eu/item/09102/_UEDIN_214"
}

Object links

Object links

An object link is a relationship between two (Europeana) objects. This relationship can be any.

{
  "motivation": "tagginglinking",
  "bodytarget": [
      "http://swsdata.geonames.org/2988507",europeana.eu/item/92062/BibliographicResource_1000126189360",
    "target":  "http://data.europeana.eu/item/0910292062/BibliographicResource_UEDIN_214"1000126189361"
  ]
}

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:

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.

{
  "motivation": "linkingtagging",
  "targetbodyValue": ["Folk Music",
     "target"http://data.europeana.eu/item/92062/BibliographicResource_1000126189360",
 {
    "type": "SpecificResource",
    "scope": "http://data.europeana.eu/item/92062/BibliographicResource_10001261893612059207/data_sounds_T471_5",
    "source": "http://comhaltasarchive.ie/tracks/12535"
  ]}
}

Transcriptions

A geo-tag adds a geographical location to an item.

Example:

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.

{
  "motivation": "taggingtranscribing",
  "body": {
    "@contextid": "httphttps://wwweuropeana.europeanatranscribathon.eu/schemasdocuments/story/context/entity.jsonlditem/?item=39378387",
    "typelanguage": "Placede",
    "latformat": "52.081131",text/html"
  },
  "longtarget": "4.324053"{
  },   "targetscope": "http://data.europeana.eu/item/92034/GVNRC_NFA03_kop_6_3"
}

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.

{
  "motivation": "tagging",
  "bodyValue": "Folk Music",
  "target": {
    "type": "SpecificResource",
    "scope743/_nhp5sXg",
    "source": 
    "https://glam.uni.wroc.pl/iiif/image-api/RKP_HAASE_371_62468_0001/full/full/0/default.jpg"
  }
}

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:

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

HTTP/1.1 200 OK
Content-Type: application/ld+json
{
  "@context": "http://datawww.europeanaw3.euorg/item/2059207/data_sounds_T471_5ns/anno.jsonld",
    "sourceid": "http://comhaltasarchive.ie/tracks/12535"data.europeana.eu/annotation/base/1",
  }
}

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.

{
  "motivation": "transcribing"type": "Annotation",
  "created": "2016-01-31T12:03:45Z",
  "generated": "2016-01-31T12:04:00Z",
  "generator": "http://www.europeana.eu",
  "bodyValue": "Trombone",
  "bodymotivation": {"tagging",
    "idtarget": "httpshttp://data.europeana.transcribathon.eu/documentsitem/story/item/?item=39378387",
    "language": "de",
    "format": "text/html"
  },
  "target": {
    "scope": "http://data.europeana.eu/item/743/_nhp5sXg",
    "source": 
    "https://glam.uni.wroc.pl/iiif/image-api/RKP_HAASE_371_62468_0001/full/full/0/default.jpg"
  }
}

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:

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=*:*

Authentication

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):

/search?wskey=YOUR_KEY&query=*:*

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):

/create?wskey=YOUR_KEY&userToken=YOUR_TOKEN&query=*:*

Error Codes

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:

Annotation API Methods

Search

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:

Field

Datatype

Used for Facetting

Description

motivation

keyword

yes

motivation of the Annotation

anno_uri

keyword

complete identifier of an Annotation

anno_id

keyword

local identifier of an Annotation (/<provider>/<identifier>)

generator_uri

keyword

yes

complete identifier of the generator

generator_name

keyword

yes

name of the generator

generated

date

date on which the Annotation was first provided to the API

creator_uri

keyword

yes

complete identifier of the creator

creator_name

keyword

yes

name of the user that created the annotation

created

date

date on which the Annotation was created by the annotation client application

modified

date

date on which the Annotation was last modified

moderation_score

integer

yes

sum of all reports made to an Annotation by other users

text

text

searches in all searchable text in an Annotation

body_value

text

yes

value within the body of an Annotation, applies to e.g. simple tagging

body_uri

keyword

yes

complete identifier of the resource within the body of an Annotation, applies to e.g. semantic tagging

target_uri

keyword

yes

complete identified of the target(s) of an Annotation

target_record_id

keyword

yes

local identifier of a record when the target is a record (/collectionId/objectId)

link_resource_uri

keyword

yes

complete identifier of the resource being linked to (ie. through the relation property)

link_relation

keyword

yes

property being used to link two resources.

Response

{
  "@context": "http://www.w3.org/ns/anno.jsonld",
  "id": "http://annotations.europeana.eu/annotation/search?wskey=xxxxx&query=*:*&page=0&pageSize=10",
  "items": [
    "http://data.europeana.eu/annotation/base/1",
    "http://data.europeana.eu/annotation/base/2",
    [..]
  ],
  "next": "http://annotations.europeana.eu/annotation/search?wskey=xxxxx&query=*:*&page=1&pageSize=10",
  "partOf": {
     "id": "http://annotations.europeana.eu/annotation/search?wskey=xxxxx&query=*:*",
     "total": 135610
  },
  "total": 10,
  "type": "AnnotationPage"
}

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.

09102/_UEDIN_214"
}

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

{
  "@context": "http://www.w3.org/ns/anno.jsonld",
  "id": "http://annotations.europeana.eu/annotation/search?wskey=xxxxx&query=*:*&page=0&pageSize=10",
  "items": [
    "http://data.europeana.eu/annotation/base/1",
    "http://data.europeana.eu/annotation/base/2",
    [..]
  ],
  "next": "http://annotations.europeana.eu/annotation/

Request

POST  search?wskey=xxxxx&query=*:*&page=1&pageSize=10",
  "partOf": {
     "id": "http://annotations.europeana.eu/annotation/search?wskey=YOUR_KEYxxxxx&userToken=YOUR_TOKEN HTTP/1.1
Accept: application/ld+json
Content-Type: application/ld+json
Content-Length: 999
{
  "motivation": "tagging"query=*:*",
     "total": 135610
  },
  "total": 10,
  "bodyValuetype": "TromboneAnnotationPage",
  "target": "http://data.europeana.eu/item/09102/_UEDIN_214"
}

Response

Content-Type: application/ld+json
ETag: "_87e52ce126126"
Link: <http://www.w3.org/ns/ldp#Resource>l; rel="type"
Allow: POST,GET,OPTIONS,HEAD
Vary: Accept
Content-Length: 999
{
  "@context": "http://www.w3.org/ns/anno.jsonld",
  "id": "http://data.europeana.eu/annotation/base/1",
  "type": "Annotation",
  "created": "2016-01-31T12:03:45Z",
  "creator": "http://data.europeana.eu/user/55376",
  "generated": "2016-01-31T12:04:00Z",
  "generator": "http://data.europeana.eu/provider/historypin",
  "bodyValue": "Trombone",
  "motivation": "tagging
}

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.

POST http://annotations.europeana.eu/annotation/

Request

POST  http://annotations.europeana.eu/annotation/?wskey=YOUR_KEY&userToken=YOUR_TOKEN HTTP/1.1
Accept: application/ld+json
Content-Type: application/ld+json
Content-Length: 999
{
  "motivation": "tagging",
  "bodyValue": "Trombone",
  "target": "http://data.europeana.eu/item/09102/_UEDIN_214"
}

For more examples and information on the data model for an annotation, see data model.

Read

Retrieve annotations by their identifier.

GET /{provider}/{identifier}

Response

Content-Type: application/ld+json
ETag: "_87e52ce126126"
Link: <http://www.w3.org/ns/ldp#Resource>l; rel="type"
Allow: POST,GET,OPTIONS,HEAD
Vary: Accept
Content-Length: 999
{
  "@context": "http://www.w3.org/ns/anno.jsonld",
  "id": "http://data.europeana.eu/annotation/base/1",
  "type": "Annotation",
  "created": "2016-01-31T12:03:45Z",
  "creator": "http://data.europeana.eu/user/55376",
  "generated": "2016-01-31T12:04:00Z",
  "generator": "http://wwwdata.europeana.eu/provider/historypin",
  "bodyValue": "Trombone",
  "motivation": "tagging",
  "target": "http://data.europeana.eu/item/09102/_UEDIN_214"
}

See data model for more For more examples and information on the representation of 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.

PUT /base/1 HTTP/1.1
Accept: application/ld+json
{
  "bodyValue": "Trombone",
  "motivation": "tagging",
  "target": "http://data.europeana.eu/item/09102/_UEDIN_214"
}

Response

HTTP/1.1 200 OK
Content-Type: application/ld+json
{
  "@context": "http://www.w3.org/ns/anno.jsonld",
  "id": "http://data.europeana.eu/annotation/base/1",
  "type": "Annotation",
  "created": "2016-01-31T12:03:45Z",
  "generated": "2016-01-31T12:04:00Z",
  "generator": "http://www.europeana.eu",
  "bodyValue": "Trombone",
  "motivation": "tagging",
  "target": "http://data.europeana.eu/item/09102/_UEDIN_214"
}

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

DELETE /collections/1 HTTP/1.1

Response

HTTP/1.1 204 NO CONTENT
Content-Length: 0

Console

Roadmap and Changelog

The current version of the Annotations API is 0.3.3 (August 2022)We deploy new versions of this API quite regularly. 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.