Annotation API

API for presentation and discovery of media annotations.

The Annotation API is compatible with the following standards:

[Web Annotation Data Model]
Web Annotation Data Model. Edited by Robert Sanderson, Paolo Ciccarese, and Benjamin Young. Copyright © 2017 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and document use rules apply.
[IIIF Presentation API]
IIIF Presentation API 2.1. Edited by Michael Appleby, Tom Crane, Robert Sanderson, Jon Stroop, and Simeon Warner. Copyright © 2012-2016 Editors and contributors. Published by the IIIF Consortium under the CC-BY license.
[OData-Part2]
OData Version 4.0. Part 2: URL Conventions Plus Errata 03. Edited by Michael Pizzo, Ralf Handl, and Martin Zurmuehl. 02 June 2016. OASIS Standard incorporating Approved Errata 03.
[OData-JSON-Format-v4.0]
OData JSON Format Version 4.0 Plus Errata 03. Edited by Ralf Handl, Michael Pizzo, and Mark Biamonte. 02 June 2016. OASIS Standard incorporating Approved Errata 03.
Contents

Presentation Requests

Manifest Request [sc:Manifest]

GET {scheme}://{server}/annotation/{repository}/Manifest({$identifier})

Represents the entry point for a annotated media object.

Compatible with: http://iiif.io/api/presentation/2.1/#manifest

Properties

id id of this manifest
label label of this manifest
type types that describe this manifest
members list of canvas ids this manifest contains, expandable with "?$expand"
within a reference to the parent repository object, expandable with "?$expand"

Examples

Example Description
/annotation/a5-1/ Manifest (a5:test-eaf)?pretty Basic example.
/annotation/a5-1/Manifest(a5:test-eaf)?pretty&$expand=members,within Example with expanded "members" and "within" properties.

Canvas Request [sc:Canvas]

GET {scheme}://{server}/annotation/{repository}/Canvas({$identifier})

Represents a frame of reference for content resources such as annotation layers and media objects.

Compatible with: http://iiif.io/api/presentation/2.1/#canvas

Properties

id id of this canvas
label label of this canvas
type types that describe this canvas
media list of ids of media objects associated with this canvas, expandable with "?$expand"
otherContent list of ids of content resources such as annotation layers associated with this canvas

Examples

Example Description
/annotation/a5-1/ Canvas (a5:test-eaf/canvas/0)?pretty Basic example.
/annotation/a5-1/ Canvas (a5:test-eaf/canvas/0)?pretty&$expand=media Example with expanded "media" property.

AnnotationLayer Request [sc:AnnotationLayer]

GET {scheme}://{server}/annotation/{repository}/Layer({$identifier})

Represents an ordered sequence of annotations belonging together, e.g., a transcription.

Compatible with: http://iiif.io/api/presentation/2.1/#layer

Properties

id id of this annotation layer
label label for this annotation layer
type types that describe this annotation layer
total total number of resources contained in this layer
hasParent
isParentOf
resources ordered sequence of annotation resources

Examples

Example Description
/annotation/a5-1/Layer(a5:test-eaf/annotationlayer/0)?pretty Basic example.

Annotation Request [oa:Annotation]

GET {scheme}://{server}/annotation/{repository}/Annotation({$identifier})

Represents a media annotation.

Compatible with: https://www.w3.org/TR/annotation-model/#annotations

Properties

id id of this annotation
label label of this annotation
type types that describe this annotation
bodyValue the string value of this annotation
target id of the target canvas this annotation is associated with
selector fragment selector representing a reference to parts of the target canvas, see /apidoc/media#Media_Manipulation_Request

Examples

Example Description
/annotation/a5-1/Annotation(a5:test-eaf/annotation/ann8)?pretty Basic example.

Disovery Requests

Fulltext Search [$search]

GET {scheme}://{server}/annotation/{repository}/(Layers|Annotations)?$search={querystring}

Matches a query string against annotation values. The result is a collection of annotation layers or a collection of annotations.

Query strings follow the Lucene Syntax.

Example Description
/annotation/a5-1/Layers?$search=tendas&pretty Searches for the term "tendas" in the annotations of repository "a5-1" and returns a collection of matched annotation layers.
/annotation/a5-1/Annotations?$search=tendas&pretty Searches for the term "tendas" in the annotations of repository "a5-1" and returns a collection of matched annotations.

Keyword filtering [$filter]

GET {scheme}://{server}/annotation/{repository}/(Layers|Annotations)?$filter={field1 (eq|ne|gt|ge|lt|le) "term1" (and|or|not) field2 ...}

Filters annotations or annotation layers according to field values.

Example Description
/annotation/a5-1/Annotations?pretty&$filter=target eq a5:Gutob_Komplas/canvas/0 Example returns collection of annotations of repository "a5-1" associated with canvas "a5:Gutob_Komplas/canvas/0"
/annotation/a5-1/Layers?pretty&$filter=type eq eaf:TIER@Symbolic_Subdivision Example returns collection of annotation layers of repository "a5-1" with type "eaf:TIER@Symbolic_Subdivision"

Counting Hits [$count]

GET {scheme}://{server}/annotation/{repository}/(Layers|Annotations)?$count

Whether to include number of hits in the query result.

Example Description
/annotation/a5-1/Layers?$count&pretty Includes number of matched annotation layers.
/annotation/a5-1/Annotations?$count&pretty Includes number of matched annotations.

Navigating Hits [$skip, $top]

GET {scheme}://{server}/annotation/{repository}/(Layers|Annotations)?$skip={integer}&$top={integer}

Allows navigation of search results.

Example Description
/annotation/a5-1/Layers?$skip=10&$top=3&pretty Example returns 3 annotation layers, skipping 10 layers.
/annotation/a5-1/Annotations?$skip=1000&$top=100&pretty Example returns 100 annotations, skipping 1000 annotations.