Table of Contents
Label export formats
When you export your labels from your project, the Label key in the export file contains all of the annotation information. The asset is not included in Label.
The Label key has two categories of annotations:
| Includes Segmentation mask, Bounding box, Polygon, Polyline, Point, and Entity. |
| Includes Radio, Checklist, Dropdown, and Text. |
Images
Only objects on images contain a value for instanceURI.
Masks
The Image segmentation tool supports instance segmentation. Each mask instance will get its own row in the JSON export, which you can access via the instanceURI.
"Label": {
"objects": [
{
"featureId": "ckdugekv40rdv0z444h9w9v7k",
"schemaId": "ckdugeer20syt0y5t23mphorz",
"title": "Sample mask",
"value": "sample_mask",
"color": "#FF4A46",
"instanceURI": "https://api.labelbox.com/masks/feature/ckdugekv40rdv0z444h9w9v..."
},
{
"featureId": "ckdugenyj0u9p0y4e99lm3uul",
"schemaId": "ckdugeer20syt0y5t23mphorz",
"title": "Sample mask",
"value": "sample_mask",
"color": "#FF4A46",
"instanceURI": "https://api.labelbox.com/masks/feature/ckdugenyj0u9p0y4e99lm3u..."
},
{
"featureId": "ckdugenyj0u9p0y4e99lm3uul",
"schemaId": "ckdugeer20syt0y5t23mphorz",
"title": "Sample mask",
"value": "sample_mask",
"color": "#FF4A46",
"instanceURI": "https://api.labelbox.com/masks/feature/ckdugeqfs0u9q0y4e49wp7x..."
}
],
"classifications": []
}
When you export the masks from a project, each mask instanceURI will expire after 30 days. If you are accessing these masks programmatically, you can bypass the 30-day expiry by stripping the token={} parameter from the mask URL and adding your API key as a header instead.
curl 'https://api.labelbox.com/masks/feature/:id' \
-H 'Authorization: Bearer <API_KEY_HERE>' Bounding boxes
The geometric key for Bounding boxes contains coordinates for the top left corner as well as height and width measurements.
| Ymin value |
| Xmin value |
"Label": {
"objects": [
{
"featureId": "ck9bmeej61emf0yf5bgjb4tjw",
"schemaId": "ck9blmq1lnlxw08895jy7zsk4",
"title": "Sample bbox",
"value": "sample_bbox",
"color": "#FF8000",
"bbox": {
"top": 186,
"left": 192,
"height": 300,
"width": 519
},
"instanceURI": "https://api.labelbox.com/masks/feature/ck9bmeej61emf0yf5bgjb4tj..."
}
],
"classifications": []
}Polygons
The x,y coordinates for Polygons are listed in the order hey were initially created. Points added after initial creation will be inserted in the proper position.
"Label": {
"objects": [
{
"featureId": "ck9blnafk1d070yf5bhq4q1fv",
"schemaId": "ck9blmq1lnlxv0889cu4r18mx",
"title": "Sample polygon",
"value": "sample_polygon",
"color": "#FF0000",
"polygon": [
{
"x": 3665.814,
"y": 351.628
},
{
"x": 3762.93,
"y": 810.419
},
{
"x": 3042.93,
"y": 914.233
},
{
"x": 2996.047,
"y": 864
},
{
"x": 3036.233,
"y": 753.488
}
],
"instanceURI": "https://api.labelbox.com/masks/feature/ck997wbcnbkcqnpz1fv60..."
}
],
"classifications": []
}
Polylines
For Polylines, the coordinates in the geometric key are in clockwise direction.
"Label": {
"objects": [
{
"featureId": "ck9bmejeu00c20ya10woo1ml5",
"schemaId": "ck9blmq1lnlxx088964dfy107",
"title": "Sample polyline",
"value": "sample_polyline",
"color": "#FFFF00",
"line": [
{
"x": 328.535,
"y": 308.215
},
{
"x": 613.242,
"y": 735.277
},
{
"x": 958.026,
"y": 907.668
},
{
"x": 1352.437,
"y": 905.056
}
],
"instanceURI": "https://api.labelbox.com/masks/feature/ck9bmejeu00c20ya10woo1ml..."
}
],
"classifications": []
}Points
Points do not support sub-pixel placement.
"Label": {
"objects": [
{
"featureId": "ck9bmemy91hic10bogwc6sygv",
"schemaId": "ck9blmq1lnlxy0889stzln2ms",
"title": "Sample point",
"value": "sample_point",
"color": "#D4FF00",
"point": {
"x": 116,
"y": 98
},
"instanceURI": "https://api.labelbox.com/masks/feature/z2r0oi80y7mfz2r0oi80y7mf..."
}
],
"classifications": []
}
Classification
The Image classification tool produces a semantic classification with no geometric information, therefore, Classifications do not have an instanceURI. The four classification types are radio, checklist, dropdown, and text classification.
"Label": {
"objects": [],
"classifications": [
{
"featureId": "ck9bloche1fy910bom8fgji90",
"schemaId": "ck9blmq1lnlxs0889u7xa8byw",
"title": "Free text question",
"value": "free_text_question",
"answer": "sample text"
},
{
"featureId": "ck9bloham1d1b0yf5870yxzxp",
"schemaId": "ck9blmq4ifi4b09760b4ur5ih",
"title": "Radio question",
"value": "radio_question",
"answer": {
"featureId": "ck9blohbp1d1c0yf523u34azb",
"schemaId": "ck9blmq1lnlxo0889u50lm3dx",
"title": "Yes",
"value": "yes"
}
},
{
"featureId": "ck9bloipe005h10evp9txzhi6",
"schemaId": "ck9blmq4jfi4c0976jzdlk2fw",
"title": "Checklist question",
"value": "checklist_question",
"answers": [
{
"featureId": "ck9bloiqc005i10evlzlv90v5",
"schemaId": "ck9blmq1lnlxq0889oy9h5596",
"title": "Red",
"value": "red"
},
{
"featureId": "ck9blojbm1doo0zdga69rzqdj",
"schemaId": "ck9blmq1lnlxr08893iamqxcz",
"title": "Blue",
"value": "blue"
}
]
},
{
"featureId": "ck9nedyfw05v91276aqbzfsnj",
"schemaId": "ck9nedt5a1kgw0y6tnj17m2i2",
"title": "Dropdown question",
"value": "dropdown_question",
"answer": [
{
"featureId": "ck9nedyhm05va127627ypedfy",
"schemaId": "ck9nedt701kh20y6tqoxgndvv",
"title": "Answer",
"value": "answer"
},
{
"featureId": "ck9nedyi305vb12764xxeuypd",
"schemaId": "ck9nedt8a1khb0y6t37ylx1rb",
"title": "Nested answer",
"value": "nested_answer"
}
]
}
]
}Nested classification
Nested classifications appear under objects. The four classification types are radio, checklist, dropdown, and text classification.
"Label": {
"objects": [
{
"featureId": "ck9nkjj6j03341081z1d9dpd4",
"schemaId": "ck9nkgekg00vz109la501ywx2",
"title": "Sample polygon",
"value": "sample_polygon",
"color": "#FF0000",
"instanceURI": "https://api.labelbox.com/masks/feature/ck9nkjj6j03341081z1d9dpd4",
"classifications": [
{
"featureId": "ck9nkjl5d03iu0z945fhjo1gb",
"schemaId": "ck9nkjdm703bl1064fn42xtn5",
"title": "Nested classification",
"value": "nested_classification",
"answer": {
"featureId": "ck9nkjl6f03iv0z94ewv0s74j",
"schemaId": "ck9nkjdnq03bu1064oy6qimtn",
"title": "Answer 1",
"value": "answer_1"
}
}
]
}
]
}Text
Named Entity Recognition
The Named Entity Recognition (NER) tool is used to label words or phrases in unstructured text.
"Label": {
"objects": [
{
"featureId": "ck8kulppv000x0yf8pqpqqin4",
"schemaId": "ck8kukafkqx1a0880iczbrqym",
"title": "Entity type A",
"value": "entity_type_a",
"color": "#8000FF",
"version": 1,
"format": "text.location",
"data": {
"location": {
"start": 67,
"end": 128
}
}
}
]
} text field under location.Text classification
"Label":
{
"objects": [],
"classifications": [
{
"featureId": "ckeoidh3t0f0f0y51eceb1m3o",
"schemaId": "ckeoidb0w0ey20y51bb88c0di",
"title": "Radio classification",
"value": "radio_classification",
"answer":
{
"featureId": "ckeoidh4d0f0g0y51ama04lpm",
"schemaId": "ckeoidb1r0eya0y51h5n42g8m",
"title": "Answer 1",
"value": "answer_1"
}
},
{
"featureId": "ckeoidi4m0fn70y8vg2xo75rj",
"schemaId": "ckeoidb2g0eym0y51g2hdeqc0",
"title": "Nested radio",
"value": "nested_radio",
"answer":
{
"featureId": "ckeoidi550fn80y8vfsgj2rqs",
"schemaId": "ckeoidb390eyz0y515lj51i7y",
"title": "Answer 2a",
"value": "answer_2a"
}
},
{
"featureId": "ckeoidl0w0f0n0y510mz0179n",
"schemaId": "ckeoidb0w0ey40y51ci6xf29c",
"title": "Checklist classification",
"value": "checklist_classification",
"answers": [
{
"featureId": "ckeoidl8y0f0v0y51hfx5azbu",
"schemaId": "ckeoidb1z0eyk0y512rk71exe",
"title": "Answer 2",
"value": "answer_2"
}
]
},
{
"featureId": "ckeoidph50fnu0y8v4hkc7sil",
"schemaId": "ckeoidb0x0ey60y513qez9mfy",
"title": "Text classification",
"value": "text_classification",
"answer": "Text answer"
},
{
"featureId": "ckeoidqfr0f160y51crl73nwt",
"schemaId": "ckeoidb0x0ey80y51c1eqf6kl",
"title": "Dropdown classification",
"value": "dropdown_classification",
"answer": [
{
"featureId": "ckeoidqgb0f170y514e6e5xco",
"schemaId": "ckeoidb1y0eye0y512j2u8vp4",
"title": "Answer 1",
"value": "answer_1"
},
{
"featureId": "ckeoidqgn0f180y51100o3mk7",
"schemaId": "ckeoidb2n0eyo0y515vmochbv",
"title": "Answer 1a",
"value": "answer_1a"
}
]
}
]
}
Video
The video labels export contains a Label element for each video in the project. Each Label will contain a frames key with a URL to an NDJSON file containing the information for the labeled frames in that video.
An easy way to access your video frame labels is in the Postman UI.
Steps:
- Open Postman and create a new basic API request
- Copy the URL for
"frames"and paste it as the request URL - Navigate to the "Headers" tab
- Select "Authorization" as the key
- Paste your API key as the Authorization value
- Click "send"
You can also access the video frames programmatically. To access the URL containing the information for the labeled frames, place your API key in the authorization header. See examples below. The endpoint this URL points to may return a HTTP 301 response. If this happens, the HTTP response will contain a Location header with the download URL. If the label is skipped and has no data, the endpoint will return a HTTP 204 response.
"Label": {
"frames": "<URL-TO-NDJSON-FILE>"
}Bash example for accessing the frames:
curl -L -H "Authorization: Bearer $API_KEY" $FRAMES_URL > $FRAMES_FILE_LOCATIONPython example for accessing the frames:
import requests
headers = {'Authorization': f"Bearer {API_KEY}"}
ndjson_response = requests.get(frames_url, headers=headers)
Each element in the NDJSON file represents a labeled frame in the video (unlabeled frames will not be included).
Multi-frame bounding box
{
"frameNumber": 1,
"objects": [
{
"featureId": "<BBOX-OBJECT-FEATURE-ID>",
"schemaId": "<BBOX-OBJECT-SCHEMA-ID>",
"title": "<BBOX-NAME>",
"value": "<BBOX-NAME>",
"color": "#FF8000",
"bbox": {
"height": 272,
"left": 111,
"top": 137,
"width": 324
},
"classifications": [
{
"featureId": "<NESTED-RADIO-QUESTION-FEATURE-ID>",
"schemaId": "<NESTED-RADIO-QUESTION-SCHEMA-ID>",
"title": "Nested Radio question",
"value": "nested_radio_question",
"answer": {
"featureId": "<NESTED-RADIO-ANSWER-FEATURE-ID>",
"schemaId": "<NESTED-RADIO-ANSWER-SCHEMA-ID>",
"title": "Answer 1",
"value": "answer_1"
}
},
{
"featureId": "<NESTED-CHECKLIST-QUESTION-FEATURE-ID>",
"schemaId": "<NESTED-CHECKLIST-QUESTION-SCHEMA-ID>",
"title": "Nested Checklist question",
"value": "nested_checklist_question",
"answers": [
{
"featureId": "<NESTED-CHECKLIST-ANSWER-FEATURE-ID>",
"schemaId": "<NESTED-CHECKLIST-ANSWER-SCHEMA-ID>",
"title": "Option 1",
"value": "option_1"
},
...
]
}
]
}
]
}Point
{
"frameNumber": 2,
"objects": [
{
"featureId": "<POINT-OBJECT-FEATURE-ID>",
"schemaId": "<POINT-OBJECT-SCHEMA-ID>",
"title": "<POINT-NAME>",
"value": "<POINT-NAME>",
"color": "#FF8000",
"point": {
"x": 116,
"y": 98
},
"classifications": [
{
"featureId": "<NESTED-RADIO-QUESTION-FEATURE-ID>",
"schemaId": "<NESTED-RADIO-QUESTION-SCHEMA-ID>",
"title": "Nested Radio question",
"value": "nested_radio_question",
"answer": {
"featureId": "<NESTED-RADIO-ANSWER-FEATURE-ID>",
"schemaId": "<NESTED-RADIO-ANSWER-SCHEMA-ID>",
"title": "Answer 1",
"value": "answer_1"
}
},
{
"featureId": "<NESTED-CHECKLIST-QUESTION-FEATURE-ID>",
"schemaId": "<NESTED-CHECKLIST-QUESTION-SCHEMA-ID>",
"title": "Nested Checklist question",
"value": "nested_checklist_question",
"answers": [
{
"featureId": "<NESTED-CHECKLIST-ANSWER-FEATURE-ID>",
"schemaId": "<NESTED-CHECKLIST-ANSWER-SCHEMA-ID>",
"title": "Option 1",
"value": "option_1"
}
]
}
]
}
]
}Classifications
{
"frameNumber": 1,
"classifications": [
{
"featureId": "<QUESTION-FEATURE-ID>",
"schemaId": "<QUESTION-SCHEMA-ID>",
"title": "Radio question",
"value": "radio_question",
"answer": {
"featureId": "<RADIO-ANSWER-FEATURE-ID>",
"schemaId": "<RADIO-ANSWER-SCHEMA-ID>",
"title": "Yes",
"value": "yes"
}
},
{
"featureId": "<CHECKLIST-QUESTION-FEATURE-ID>",
"schemaId": "<CHECKLIST-QUESTION-SCHEMA-ID>",
"title": "Checklist question",
"value": "checklist_question",
"answers": [
{
"featureId": "<CHECKLIST-ANSWER-FEATURE-ID>",
"schemaId": "<CHECKLIST-ANSWER-SCHEMA-ID>",
"title": "Option X",
"value": "option_x"
}
]
}
]Tiled imagery
Because Tiled Imagery is only available in the Legacy editor, the Label format is slightly different. The sample below contains two Polygon annotations named "Tree" and a global classification.
"Label": {
"Tree": [
{
"geometry": [
{
"lat": 37.87392181463312,
"lng": -122.3205327987671
},
{
"lat": 37.872549831535984,
"lng": -122.32117652893068
},
{
"lat": 37.87261758438741,
"lng": -122.31958866119386
}
]
},
{
"geometry": [
{
"lat": 37.87458238997454,
"lng": -122.31956720352174
},
{
"lat": 37.87442995003686,
"lng": -122.31677770614625
},
{
"lat": 37.87361693170852,
"lng": -122.31739997863771
},
{
"lat": 37.873481427781456,
"lng": -122.31915950775148
},
{
"lat": 37.87378631126686,
"lng": -122.31945991516115
}
]
}
],
"is_the_tree_green?": "yes"
}