Annotations

Annotations#

Annotation object#

Each annotation returned from the API is a JSON object with the following properties:

id: (read only) The ID of the annotation.
annotation_type_id: The ID of the type of the annotation.
type: (read only) The annotation type (template) object that this annotation is based on. Embeds the same fields the type object returns from GET /annotation-template/types/{id} — at minimum id, name, and extended_data. Maps to annotation_type_id.
annotation_set_id: The ID of the annotation set which the annotation belongs to.
image_id: The ID of the image which the annotation belongs to. Only applies to annoations from image annotation sets.
target: the Web Annotation target. See Annotation target for details.
line_color: The HEX color code used for outline color of the annotation. E.g. #000000.
line_weight: The outline color shade of the annotation. The value should be one of the values of light, medium, and dark.
fields: the field data of the annotation. See Annotation fields for details.
tags: list of tags applied to the annotation. See Annotation Tags for details.
weight: (read only) The integer used to order the annotation within its annotation set. A null value indicates the annotation has not been explicitly ordered. See Reorder annotations for how this value is set.
created_at: (read only) The datetime when the annotation is created.
updated_at: (read only) The datetime when the annotation is updated.

Annotation target#

The target of an annotation is an object specified in the Web Annotation standard. For more information, please refer to the Web Annotation Data Model.

Example:

{
    "source": "https://example.com/iiif/canvas/1",
    "selector": {
        "type": "SvgSelector",
        "value": "<svg><polygon points=\"14463.65625,8689.75 15475.2490234375,8424.4140625 16550.326171875,10613.435546875 16384.490234375,11525.52734375 15721.1513671875,12006.44921875 15820.65234375,10812.4375 15173.8955078125,10248.5986328125 15207.0625,11193.857421875 14775.892578125,10928.521484375 14742.7255859375,10331.515625\"></polygon></svg>"
    }
}

Annotation fields#

The fields property of an annotation is an array of objects containing the following properties:

field: The field information of the value. It can be the field ID or an object with the basic field information:
- id: The ID of the field.
- name: The name of the field.
- type: The type of the field. The value should be one of the following: text, long_text, link, choice, date.
values: The values of the field. It is an object where each key is a language code and the value is an array of field values in that language. Each item of the array is a string value, except for the link field where each item is an object with the url and text properties.

Example of a text field:

{
    "field": {
        "id": 1,
        "name": "Title",
        "type": "text"
    },
    "values": {
        "en": [
            "Title in English"
        ],
        "zh": [
            "中文标题"
        ]
    }
}

Example of a link field:

{
    "field": {
        "id": 2,
        "name": "Link",
        "type": "link"
    },
    "values": {
        "en": [
            {
                "url": "https://example.com",
                "text": "Link 1"
            },
            {
                "url": "https://example.com",
                "text": "Link 2"
            }
        ],
        "zh": [
            {
                "url": "https://example.com",
                "text": "链接 1"
            },
            {
                "url": "https://example.com",
                "text": "链接 2"
            }
        ]
    }
}

Language codes#

The following is the list of supported language codes:

Code	Name
ar	Arabic
bn	Bangla
cs	Czech
da	Danish
de	German
el	Greek
en	English
es	Spanish
fi	Finnish
fr	French
he	Hebrew
hi	Hindi
hu	Hungarian
id	Indonesian
it	Italian
ja	Japanese
ko	Korean
nl	Dutch
no	Norwegian
pl	Polish
pt	Portugese
ro	Romanian
ru	Russian
sk	Slovak
sv	Swedish
ta	Tamil
th	Thai
tr	Turkish
zh	Chinese

Annotation Tags#

The tags property of an annotation is an array of objects containing the following properties:

term_label: (required) The label of the tagging term.
term_id: The ID of the tagging term.
vocabulary_id: The ID of the vocabulary which the tag belongs to.
vocabulary_name: The name of the vocabulary which the tag belongs to.
extended_data: An object containing additional data of the tagging term such as the description and hierarchy information of the term. For example:

{
    "description": "This group covers civil engineering.",
    "trace": [
        {
            "key": "https://linked.data.gov.au/def/anzsrc-for/2020/40",
            "label":"ENGINEERING"
        }
    ]
}

Get all annotations#

GET /annotation-sets/{annotation_set_id}/annotations

Get all annotations in an annotation set.

URL parameters#

annotation_set_id: The ID of the annotation set.

Response#

An array of annotation objects.

Create an annotation#

POST /annotation-sets/{annotation_set_id}/annotations

Create an annotation in an annotation set.

URL parameters#

annotation_set_id: The ID of the annotation set.

Request#

The request body should be an annotation object used to create a new annotation. Read only properties will be ignored.

Response#

The annotation object of the newly created annotation.

Get an annotation#

GET /annotation-sets/{annotation_set_id}/annotations/{id}

Get an annotation by its ID.

URL parameters#

annotation_set_id: The ID of the annotation set.
id: The ID of the annotation.

Response#

The annotation object of the queried annotation.

Update an annotation#

PUT /annotation-sets/{annotation_set_id}/annotations/{id}

Update an annotation by its ID.

URL parameters#

annotation_set_id: The ID of the annotation set.
id: The ID of the annotation.

Request#

The request body should be an annotation object used to update the annotation. Read only properties will be ignored.

Response#

The annotation object after the update.

Delete an annotation#

DELETE /annotation-sets/{annotation_set_id}/annotations/{id}

Delete an annotation by its ID.

URL parameters#

annotation_set_id: The ID of the annotation set.
id: The ID of the annotation.

Response#

The annotation object of the deleted annotation.

Reorder annotations#

POST /annotation-sets/{annotation_set_id}/annotations/reorder

Set the display order of annotations within an annotation set. The endpoint accepts an ordered array of annotation IDs and assigns each listed annotation a weight equal to its position in the array (starting from 0).

The list may be partial. Listed annotations receive the new weight values, while annotations not included in the request keep their existing weight (which may be null if they have never been ordered). Annotations with an explicit weight are returned before those without; ties and unordered annotations are sorted by their id in ascending order.

URL parameters#

annotation_set_id: The ID of the annotation set.

Request#

The request body should be a JSON object with the following property:

annotation_ids: (required) An ordered array of annotation IDs. All IDs must belong to the target annotation set. Duplicate IDs are not allowed. An empty array is accepted and is treated as a no-op.

Example:

{
    "annotation_ids": [12, 7, 19]
}

Response#

An array of annotation objects of the annotation set in the resulting display order, including the updated weight values.

Annotations

Contents

Annotations#

Annotation object#

Annotation target#

Annotation fields#

Language codes#

Annotation Tags#

Get all annotations#

URL parameters#

Response#

Create an annotation#

URL parameters#

Request#

Response#

Get an annotation#

URL parameters#

Response#

Update an annotation#

URL parameters#

Request#

Response#

Delete an annotation#

URL parameters#

Response#

Reorder annotations#

URL parameters#

Request#

Response#