Annotations

Annotations one of the fundamental building blocks of extracted data. They say that a portion of a source has some special meaning

Create Annotation

POST https://api.annolab.ai/v1/annotation/create

Create an annotation of some type on a source file. For text file sources, an annotation may reside over an array of character offsets or may simply be a document level (manual) annotation.

Headers

Name	Type	Description
Authorization	string	Where you put your api key. Creating an annotation requires a key with "Write" permissions. {"Authorization": "Api-key XXXXXXX-XXXXXXX-XXXXXXX"}

Request Body

Name	Type	Description
clientId	string	string or integer that will be "passed through" the request. Useful in situations where async or bulk requests are used, and relation inserts will follow annotation inserts.
offsets	array	Array of integers describing where the annotation exists in terms of character offsets inside the source text. Leave undefined for document-level annotations or image annotations.
preventDuplication	boolean	Boolean indicating whether duplication protection should be in place. By default this is set to true. Duplication being defined by any annotation with the exact same annotation type, offsets, layer, and source. Usually you only want to set this to false if you have multiple manual annotations (e.g. non-offset based) of the same type that you need to add on a source.
value	string	User defined value associated with the annotation
directoryIdentifier	string	Identifier of the directory containing the source that will have the annotation. Either the id or the unique name.
annoTypeIdentifier	string	Identifier of the annotation type associated with the annotation. Either the id or the unique name.
projectIdentifier	string	Identifier of the project containing the annotation. Either the id or the unique name.
layerIdentifier	integer	Identifier of the layer containing the annotation. Either the id or the unique name.
sourceIdentifier	integer	Identifier of the source where the annotation will be created. Either the id or the unique name.
textBounds	Geometry|Null	Polygon or MultiPolygon geometry object describing the location of the text the annotation contains within the page. IMPORTANT: Ensure coordinates are in provided clockwise order, ideally from top-left. Otherwise annotations may not render correctly in AnnoLab or other viewers utilizing polygon data. Example: { "type": "MultiPolygon", "coordinates": [ [[ [ 0.33, 0.32 ], [ 0.37, 0.32 ], [ 0.37, 0.34 ], [ 0.33, 0.34 ], [ 0.33, 0.32 ] ]], [[ [ 0.376, 0.329 ], [ 0.405, 0.329 ], [ 0.405, 0.344 ], [ 0.376, 0.344 ], [ 0.376, 0.329 ] ]] ], }
imageBounds	Geometry|Null	Polygon or MultiPolygon geometry object describing the location of the box drawn by a model or user on the page (always rectangular). IMPORTANT: Ensure coordinates are provided in clockwise order, ideally from top-left. Otherwise annotations may not render correctly in AnnoLab or other viewers utilizing polygon data. Example: { "type": "Polygon", "coordinates": [ [ [ 0.33, 0.32 ], [ 0.37, 0.32 ], [ 0.37, 0.34 ], [ 0.33, 0.34 ], [ 0.33, 0.32 ] ] ], }

200 Annotation already exists

{
  "id": 44,
  "typeId": 51,
  "typeName": "Place Name",
  "layerId": 5,
  "sourceId": 145,
  "typeId": 112,
  "value": '{latitude:"37.983810", longitude:"23.727539"}',
  "rawValue": 'Athens',
  "offsets": [0, 5]
 }

201 Annotation was successfully created

{
  "id": 44,
  "typeId": 51,
  "typeName": "Place Name",
  "layerId": 5,
  "sourceId": 145,
  "typeId": 112,
  "value": '{latitude:"37.983810", longitude:"23.727539"}',
  "rawValue": 'Athens',
  "offsets": [0, 5]
}

400 Annotation creation failed

{
    "message": "Information about why creation failed"
}

Examples of how to make an annotation create request

Python

import requests

ANNO_LAB_API_KEY = 'XXXXXXX-XXXXXXX-XXXXXXX-XXXXXXX'

annotation = {
  'annoTypeIdentifier': 'Place Name',
  'projectIdentifier': 'New NER Project',
  'layerIdentifier': 'NER Gold',
  'sourceIdentifier': 145,
  'offsets': [0, 5],
  'directoryIdentifier': 'Wikipedia Subset',
  'value': '{latitude:"37.983810", longitude:"23.727539"}'
}

headers = {
  'Authorization': 'Api-Key '+ANNO_LAB_API_KEY,
}

url = 'https://api.annolab.ai/v1/annotation/create'

response = requests.post(url, headers=headers, json=annotation)

print(response.json())

Bulk Create Annotations

POST https://api.annolab.ai/v1/annotation/bulk-create

Create a set of up to 2000 annotations in one request (can be a mix of many different annotation types and spread across many source files). 80% faster than individual inserts in most cases

Headers

Name	Type	Description
Authorization	string	Where you put your api key. Creating annotations requires a key with "write" permissions. {"Authorization": "Api-key XXXXXXX-XXXXXXX-XXXXXXX"}

Request Body

Name	Type	Description
preventDuplication	boolean	Boolean indicating whether duplication protection should be in place. By default this will be set to true Duplication being defined by any annotation with the exact same annotation type, offsets, layer, and source. We recommend only setting this to false if you are 100% sure that no duplications exist in the request, in which case it will be much quicker.
annotations	array	Array of annotation objects that you wish to insert.A maximum of 2000 annotations can be created in one request.

200

Examples of how to bulk create annotations

Python

import requests

ANNO_LAB_API_KEY = 'XXXXXXX-XXXXXXX-XXXXXXX-XXXXXXX'

headers = {
  'Authorization': 'Api-Key '+ANNO_LAB_API_KEY,
}

bulk_request = {
  'preventDuplication': True
  'annotations': [
    {
      'annoTypeIdentifier': 'Place Name',
      'projectIdentifier': 'New NER Project',
      'schemaIdentifier': 'NER',
      'layerIdentifier': 'NER Gold',
      'sourceIdentifier': 145,
      'offsets': [0, 5],
      'directoryIdentifier': 'Wikipedia Subset',
      'value': '{latitude:"37.983810", longitude:"23.727539"}',
      'clientId': "24a"
    },
    {
      'annoTypeIdentifier': 'Place Name',
      'projectIdentifier': 'New NER Project',
      'schemaIdentifier': 'NER',
      'layerIdentifier': 'NER Gold',
      'sourceIdentifier': 145,
      'offsets': [120, 128],
      'directoryIdentifier': 'Wikipedia Subset',
      'value': '{latitude:"37.983810", longitude:"23.727539"}',
      'clientId': "24b"
    }
  ]
}

url = 'https://api.annolab.ai/v1/annotation/bulk-create'

response = requests.post(url, headers=headers, json=bulk_request)

Annotation Object

An object corresponding to a single annotation

Attribute Name	Type	Description
annotationId	Integer	Unique id for the annotation
sourceReferenceId	Integer	Unique id for the file that contains the annotation
typeName	String	Name of the type of annotation
value	String	By default is the text that the annotation contains (can be manually overidden)
pageNumber	Integer	Starting page of the annotation
endPageNumber	Integer|Null	Ending page of the annotation (if single page annotation will be null)
offsets	Integer[]	Array describing character offsets of the annotation within the source
textBounds	Geometry|Null	MultiPolygon geometry object describing the location of the text the annotation contains within the page. IMPORTANT: Ensure coordinates are in provided clockwise order, ideally from top-left. Otherwise annotations may not render correctly in AnnoLab or other viewers utilizing polygon data. Example: { "type": "MultiPolygon", "coordinates": [ [[ [ 0.33, 0.32 ], [ 0.37, 0.32 ], [ 0.37, 0.34 ], [ 0.33, 0.34 ], [ 0.33, 0.32 ] ]], [[ [ 0.376, 0.329 ], [ 0.405, 0.329 ], [ 0.405, 0.344 ], [ 0.376, 0.344 ], [ 0.376, 0.329 ] ]] ], }
imageBounds	Geometry|Null	Polygon or MultiPolygon geometry object describing the location of the box drawn by a model or user on the page (always rectangular). IMPORTANT: Ensure coordinates are provided in clockwise order, ideally from top-left. Otherwise annotations may not render correctly in AnnoLab or other viewers utilizing polygon data. Example: { "type": "Polygon", "coordinates": [ [ [ 0.33, 0.32 ], [ 0.37, 0.32 ], [ 0.37, 0.34 ], [ 0.33, 0.34 ], [ 0.33, 0.32 ] ] ], }
createdBy	Integer	User id that created the annotation (or user id that invoked the model)
updatedBy	Integer	User Id that updated the annotation
confidence	Float	Value between 0 and 100 representing the confidence of the OCR translation of any text bounds the annotation contains. If annotation contains multiple text bounds, will be an average of all containing texts.
score	Float	Value between 0 and 1 representing sureness of a machine learning model in applying the annotation. We calculate this by taking the average of the SoftMax for all tokens comprising the annotation
layerId	Integer	Id for the layer that contains the annotation
isReviewed	Boolean	Has the annotation been reviewed
reviewedBy	Integer|Null	Reviewer that reviewed the annotation
reviewedAt	DateTime|Null	Time of review
modelSourceId	Integer	Id for the model that produced the annotation
modelSource	String	Name of the model that produced the annotation

{
    'annotationId': 403992,
    'sourceReferenceId': 12341, 
    'typeName': 'Grantor', 
    'value': ' Carsuo', 
    'pageNumber': 3, 
    'endPageNumber': null, 
    'offsets': [1320, 1326], 
    'textBounds': {'type': 'MultiPolygon', 'coordinates': [[[[0.565917551517487, 0.769474387168884], [0.609824299812317, 0.769511699676514], [0.609820425510406, 0.778583765029907], [0.565913617610931, 0.778546392917633], [0.565917551517487, 0.769474387168884]]]]}, 
    'imageBounds': null, 
    'createdBy': 5, 
    'updatedBy': null, 
    'confidence': 96.7900390625, 
    'score': 0.7074922025203705, 
    'layerId': 635, 
    'isReviewed': False, 
    'reviewedBy': null, 
    'reviewedAt': null, 
    'modelSourceId': 12, 
    'modelSource': 'Party Name Extractor'
}

CanonicalAnnotation Object

An abstract form of an annotation that is not grounded in any explicit mention or context, simplified to the components of name and value.

These objects cannot be created directly, instead they exist as attributes of CanonicalTag objects.

Attribute Name	Type	Description
name	String	The annotation type name. Must already exist as an annotation type in your project
value	String	Canonical value describing the annotation

{
    "name": "Make",
    "value": "Cessna",
}