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
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
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 ]
]
],
}{
"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]
}Examples of how to make an annotation create request
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
Authorization
string
Where you put your api key. Creating annotations requires a key with "write" permissions.
{"Authorization": "Api-key XXXXXXX-XXXXXXX-XXXXXXX"}
Request Body
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.
Examples of how to bulk create annotations
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
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.
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",
}Last updated
Was this helpful?