Annotations API methods

An overview of the API methods of the Annotations API.

Search for annotations.

GET /search

Request

ParameterDatatypeDescription
queryStringThe search term(s), this is mandatory.
profileStringSearch profile, currently only supports and defaults to "standard" which returns a list of all annotation identifiers as search result.
qfStringQuery filter, to search for additional fields. Supported: target_id (Europeana object ID), moderation_score (number of reports for this annotation, defaults to 0), motivation (e.g. "tagging" for tags), generator_id and generator_name (generator application of the annotation).
facetStringInclude a facet in the response, this field should contain the name of the facet. Supported: motivation (to facet by type of annotation).
pageSizeNumberThe number of records to return per page. Maximum is 100. Defaults to 10.
pageNumberThe page of the search results, defaults to 0 (first page).
sortStringSort by an annotation property, accepted: created or modified.
sortOrderStringOrder of sorting, either asc (ascending) or desc (descending).

Examples

Search for recently added tags:

/search?wskey=xxxxx&query=*:*&qf=motivation_key:tagging&sort=created&sortOrder=desc

Search for tags for Europeana record ID /92028/532E53363138382D2F290A40B3CA26B3889A6907:

/search?wskey=xxxxx&query=target_id:"/92028/532E53363138382D2F290A40B3CA26B3889A6907"

Don't show annotations which are reported by two or more different users:

/search?wskey=xxxxx&query=*:*&qf=moderation_score:[-1 TO *]

Note that providing *:* as a search query means you will get all annotations.

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 Annotations 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

An example to create a simple tag:

POST /annotation/?wskey=xxx&userToken=yyy 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"
}

Note that the motivation for a simple and a semantic tag is always "tagging", whereas the motivation for object linking scenarios is "linking".

Response

Response to the example request:

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",
  "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

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"
}

See data model for more information on the representation of an annotation.

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 contents as for the creation of annotations. 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. 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 /base/1

Request

DELETE /collections/1 HTTP/1.1

Response

HTTP/1.1 204 NO CONTENT
Content-Length: 0

Report

Europeana has implemented a moderation framework where users can report annotations which have no relevance to the annotated subject. When an annotation has been reported the moderation score of the annotation will be deducted with 1, allowing other API clients to filter our annotations with a certain amount of reports. For reporting you need to append /report to the annotation URI. See the search section on how to filter on moderation scores.

POST /base/1/report

Request

You can provide an empty request.

DELETE /base/1 HTTP/1.1 204 NO CONTENT
Content-Length: 0

Response

HTTP/1.1 200 OK