Search
Search for annotations.
GET /search
Request
Parameter | Datatype | Description |
---|
query | String | The search term(s), this is mandatory. |
profile | String | 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. |
qf | String | Query filter, to search on specific fields. The list of fields is presented below. |
facet | String | 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. |
pageSize | Number | 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. |
page | Number | The page of the search results, defaults to 0 (first page). |
sort | String | Includes a field to be used for sorting. One of: created, generated or modified. |
sortOrder | String | 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:
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"
}
Example: Search for recently added tags:
/search?wskey=xxxxx&profile=minimal&query=*:*&qf=motivation:tagging&sort=created&sortOrder=desc
Example: Search for tags for Europeana record ID /92028/532E53363138382D2F290A40B3CA26B3889A6907:
/search?wskey=xxxxx&profile=minimal&query=target_id:"/92028/532E53363138382D2F290A40B3CA26B3889A6907"
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.
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
An example to create a simple tag:
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"
}
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