Annotations API: Getting started

Getting started with the Annotations API.

What are annotations?

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.

Web Annotation Data Model

The Annotations API uses the Web Annotation Data Model as a guideline for how to represent and model annotations.

API keys

While the Annotations API is in an Alpha state you will need to use a separate API key (other than for the main REST API) to start experimenting with the Annotations API. You can use the following keys:

  • Test environment: 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 environment: 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 format

The Annotations API currently 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

To authenticate your API client against the Annotations API for reading (GET requests) you need to pass along your API key as the wskey parameter. Example (replace xxxxxx with your API key):

search?wskey=xxxxx&query=*:*

To authenticate your API client against the Annotations API for writing (POST/PUT/DELETE requests) 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 xxxxxx with your API key and yyyyy with the user token):

create?wskey=xxxxx&userToken=yyyyy&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:

HTTP Status CodeDescription
200The request was executed successfully.
401Authentication credentials were missing or authentication failed.
404The requested annotation was not found.
429The request could be served because the application has reached its usage limit.
500Internal Server Error. Something has gone wrong, which we will correct.