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.

  • 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.

  • 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.