API reference

IMPORTANT: STILL UNDER CONSTRUCTION! The endpoints, columns, fields and related models are auto-generated from the code, so these should be correct and up to date! If there are any endpoints that are not clearly documented or you would like more information, please contact us at Greybits.

Contents

API Authentication

API can be tested using a logged in browser session. To authenticate external services/scripts, you will need to activate the API_TOKEN for your account and set it in the HTTP header for requests made to the API:
  • X-auth-token="YOUR-API-TOKEN"
where YOUR-API-TOKEN is the value of your API TOKEN. You are not logged in. You need to log in to view/manage your API TOKEN.

Resource collections & API endpoints

ENDPOINTS
METHODENDPOINT
POST

/api/annotation

Create new annotation object. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • Enforce implied permissions from parent annotation_set (post_auth_preprocessor)
GET

/api/annotation

Get list of annotation objects matching API query. See Making API search queries for instructions on making search queries

Included fields:
id, created_at, updated_at, annotation_set_id, data, label, label.id, label.name, label.uuid, label.parent_id, label.label_scheme_id, point, point.media_id, point.x, point.y, user, user.id, user.username, point.t, point.data, point.annotation_set_id, likelihood, needs_review, point.id, tags, tags.id, tags.name, comment, timestamp, parent_id, color, suggested_tags, object_id, label.lineage_names (see below for more details)

Preprocessors:

  • Filter results based on permissions from parent annotation_set (get_many_auth_preprocessor)
GET

/api/annotation/<id>

Get single annotation object with pk field matching param id

Included fields:
id, created_at, updated_at, annotation_set_id, data, label, label.id, label.name, label.uuid, label.parent_id, label.label_scheme_id, point, point.media_id, point.x, point.y, user, user.id, user.username, point.t, point.data, point.annotation_set_id, likelihood, needs_review, point.id, tags, tags.id, tags.name, comment, timestamp, parent_id, color, suggested_tags, object_id, label.lineage_names, label_id, point.updated_at, observation_count, linked_observations, media, version_count (see below for more details)

Preprocessors:

  • Enforce implied permissions from parent annotation_set (get_single_auth_preprocessor)
DELETE

/api/annotation/<id>

Delete single annotation object with pk field matching param id

Preprocessors:

  • Enforce implied permissions from parent annotation_set (delete_auth_preprocessor)
PATCH

/api/annotation

Batch update annotation objects. Set q in querystring to filter selected annotations as per Making API search queries. Returned results are pre-filtered for only the annotations that come from annotation_sets where current_user_can_edit is set to true. As a safety measure, there is a limit of 200 annotations that can be updated in a single request.

CAUTION: this endpoint can batch update many annotations in a single request! If used incorrectly, you can loose your annotations and any annotations that have been shared with you for which you have been granted edit access. Please use with caution. TIP: Test your search query (q) on a GET request first to see what is returned before updating.

PATCH request data must be JSON with the following fields: 

{ "label_id": ..., "tags": [...], "comment": "..." }
Where label_id is the id of the label object that you would like to assign to the list of matched annotations. Setting label_id to false will reset the label and any assigned tags. tags is a list of tag.id's and comment is a string that can be assigned to each annotation.

# Example: batch change ALL annotations matching filter. Set label_id=7326 ("Ecklonia radiata") for all annotations in an annotation_set annotation_set_id=2171 annotated by user user_id=1 with a label matching label_id=7331 ("Sargasm spp")
# PATCH: (TIP first run as GET request to check filter before PATCHING)
/api/annotation?q={"filters": [{"name": "annotation_set_id", "op": "eq", "val": 2171}, {"name": "label_id", "op": "eq", "val": 7331}, {"name": "user_id", "op": "eq", "val": 1}]}
# JSON PATCH DATA:
{ "label_id": 7326 }
PATCH

/api/annotation/<int:id>

None
DELETE

/api/annotation/<int:annotation_id>/tag/<int:tag_id>

None
PATCH

/api/annotation/<int:id>/link/<int:link_id>

Updates parent_id of annotation to group observations of the same object. If link_id points to a child annotation, the observation will be linked to its parent. An observation group is used to link observations of the same object that has been annotated multiple times.
GET

/api/annotation/<int:id>/versions

View all previous versions of this annotation, i.e.: a change log.
DELETE

/api/annotation/<int:id>/link

Unlink this annotation from the observation group. If it is a group parent, the first child will be set as the new parent. An observation group is used to link observations of the same object that has been annotated multiple times.
PATCH

/api/annotation/<int:id>/link

Set this annotation as the parent of the observation group. An observation group is used to link observations of the same object that has been annotated multiple times.
GET

/api/annotation/export

General annotation export endpoint. This can export annotations across multiple annotation_sets. However, this endpoint is limited to a maximum of 200,000 annotations in any single query. You can export more in separate queries using a combination of limit and offset parameters. To export a single annotation_set without limits, see the export endpoint in the annotation_set resource.

Export annotations matching query define in q. Search queries are executed on the annotation model. This endpoint also supports translating to a target label_scheme (when possible)

Querystring parameters are:

?q={...}&f={...}&disposition=...&template=...&include_columns=[...]

Where q is a JSON search query (see Making API search queries) on the collection model, where f is a JSON dictionary containing a sequence of operations for transforming the data (see Data transformation API for more info), disposition defines the download type which can be attachment (default, triggers a download) or inline (displays in the browser), template is optional depending on the output of the steps in f and can be used to define the export format, include_columns is a JSON list of column fields for the exported model. Nested fields for related models delimited with a . If include_columns is omitted, all allowed columns will be returned.

Metadata for the annotation_set matching id is also returned in the response. Depending on the output format, this could be as part of the response body in a metadata field or in the response headers with the key X-Content-Metadata.

Allowed fields include:

id, tag_names, comment, label.id, label.name, label.lineage_names, label.uuid, label.color, updated_at, user.username, needs_review, likelihood, point.is_targeted, point.id, point.x, point.y, point.t, point.data, point.media.id, point.media.key, point.media.path_best, point.media.timestamp_start, point.media.timestamp_start_local, point.media.path_best_thm, point.pose.timestamp, point.pose.timestamp_local, point.pose.lat, point.pose.lon, point.pose.alt, point.pose.dep, point.pose.data, point.pose.id, point.media.deployment.id, point.media.deployment.key, point.media.deployment.name, point.media.deployment.campaign.id, point.media.deployment.campaign.key, point.media.deployment.campaign.name, object_id, supplementary_label, point.bbox, point.has_xy, point.has_polygon, point.polygon, point.pixels

See annotation model columns, relations and attributes for more information on each of the included fields.

TRANSLATING TO OTHER LABEL_SCHEMES

This endpoint also supports the translation of labels from a source to a target label_scheme. another label_scheme using the semantic translation framework. In order to do this, you need to specify the additional translate url query parameter:

&translate={"target_label_scheme_id":..., "vocab_registry_keys": ..., "mapping_override": ...}
Where target_label_scheme_id [required] is an INT with the id of the target label scheme, vocab_registry_keys [optional] is a list containing the priority order of keys for vocab_registries for which to perform the semantic translation and mapping_override defines a set of key-value pairs containing source label.id : target label.id for which to override the translation. Note: for extended schemes, labels are translated through tree_traversal and no semantic translation is required. With translation parameters you will also need to specify additional columns in the include_columns parameter to obtain the translation output.

Additional allowed columns include:

label.translated.id, label.translated.name, label.translated.lineage_names, label.translated.uuid, label.translated.translation_info,

These columns are ignored if no translate query parameter is supplied.

EXAMPLES

# TODO
GET

/api/annotation/tally/<group_by>

Get a tally of annotations grouped by different properties. group_by can be one of [month,'year_collected', 'month_collected', user, platform, campaign, deployment, label, affiliation^, usergroup^]. Set q in querystring to filter selected annotations as per Making API search queries. Note, the same query in q can be applied to all group_by types to filter the list of annotations that are included in the tally. Results are also paginated with a default of 500 and a maximum on 5000 returned per page. This can be controlled by setting the results_per_page parameter in the query string. Returned results are pre-filtered to return only the annotations that have been labeled (label_id != null). Also accepts a query string parameter template which formats the data using a predefined template. Some example templates include: data.html which returns an HTML table, json.html which returns HTML-formatted JSON, data.csv which returns a CSV file for download. If left blank, raw JSON will be returned.

^ NOTE: the counts in the affiliation and usergroup tally should be interpreted with care. If someone belongs to more than one group, then their annotations will contribute to both so they may be double counted. The corollary of that is if someone has not linked themselves to an affiliation or group, then their annotations will not be counted in the tally.

TRANSLATING TO OTHER LABEL_SCHEMES

When using group_by=label it is possible translate labels from a source to a target label_scheme using the semantic translation framework. In order to do this, you need to specify the additional translate url query parameter:

&translate={"target_label_scheme_id":..., "vocab_registry_keys": ..., "mapping_override": ...}
Where target_label_scheme_id [required] is an INT with the id of the target label scheme, vocab_registry_keys [optional] is a list containing the priority order of keys for vocab_registries for which to perform the semantic translation and mapping_override defines a set of key-value pairs containing source label.id : target label.id for which to override the translation. Note: for extended schemes, labels are translated through tree_traversal and no semantic translation is required. When passing translation parameters, there will the following additional output columns: label_lineage_names, translated_id, translated_lineage_names, translated_name, translated_label_scheme_name, translated_info.

# Example: tally of annotations for top 500 most commonly used labels returned as an HTML table
/api/annotation/tally/label?template=data.html&results_per_page=500
# Example: tally of annotations for the top 1000 users returned as a CSV file
/api/annotation/tally/user?&results_per_page=1000&template=data.csv
# Example: tally of annotations for the top 20 affiliations returned as an HTML table
/api/annotation/tally/affiliation?&results_per_page=20&template=data.html
# Example: tally of annotations by the top 200 usergroups returned as an HTML table
/api/annotation/tally/usergroup?&template=data.html&results_per_page=200
# Example: tally of annotations by month between 2020-01-01 and 2021-01-01 returned as an HTML table
/api/annotation/tally/month?q={"filters": [{"name":"updated_at","op":"gt","val":"2020-01-01"}, {"name":"updated_at","op":"lt","val":"2021-01-01"}] }&template=data.html
# Example: tally of annotations by platform returned as raw JSON
/api/annotation/tally/platform
# Example: tally of annotations by campaign returned as a HTML-formatted JSON
/api/annotation/tally/campaign?&template=json.html
# Example: tally of annotations for top 2000 deployments returned as an HTML table
/api/annotation/tally/deployment?&template=data.html&results_per_page=2000
# Example: tally annotations by deployment filtered by annotation_set.usergroup with ID=63 returned as an HTML table
/api/annotation/tally/deployment?&results_per_page=2000&template=data.html&q={"filters": [{"name":"annotation_set","op":"has","val": {"name":"usergroups","op":"any","val": {"name":"id","op":"eq","val":63}}}]}
# Example: tally of annotations for the top 20 users for platform(s) containing "IMOS" in their name that were labeled during the year 2020. Return the result as an HTML table using the template "data.html", GET:
/api/annotation/tally/user?q={"filters": [{"name":"point","op":"has","val": {"name":"media","op":"has","val": {"name":"deployment","op":"has","val": {"name":"platform","op":"has","val": {"name":"name","op":"ilike","val":"%IMOS%"}}}}}, {"name":"created_at","op":"gt","val":"2020-01-01"}, {"name":"created_at","op":"lt","val":"2021-01-01"}] }&results_per_page=20&template=data.html
# Example: tally of annotations by top 100 labels for a give deployment (id=10306) returned as an HTML table
# Translated into the catami annotation scheme (id=2) using the "caab" and "worms" vocab_registries (only works with compatible schemas)
/api/annotation/tally/label?q={"filters":[{"name":"point","op":"has","val":{"name":"media","op":"has","val":{"name":"deployment_id","op":"eq","val":10306}}}]}&results_per_page=100&unannotated_point_count=294&translate={"vocab_registry_keys":["caab","worms"],"target_label_scheme_id":"2"}&template=data.html
# Example: tally annotations by label in a deployment matching the key "r20200131_021337_NG02_middleton_22", filtered for occurrences between 20-30m, showing only primary observation (no linked children, i.e. only count an observation group/object once)
/api/annotation/tally/label?q={"filters":[{"name":"point","op":"has","val":{"name":"media","op":"has","val":{"name":"deployment","op":"has","val":{"name":"key","op":"eq","val":"r20200131_021337_NG02_middleton_22"}}}},{"name":"point","op":"has","val": {"name":"media","op":"has","val": {"name":"poses","op":"any","val": {"name":"dep","op":"gt","val":20}}}},{"name":"point","op":"has","val": {"name":"media","op":"has","val": {"name":"poses","op":"any","val": {"name":"dep","op":"lt","val":30}}}},{"name":"is_child","op":"eq","val":false}]}
MODEL COLUMNS FILTERABLE
These attributes map to database columns and can be used when building filters (for endpoints that support filtering, see Making API queries )
NAME TYPE DEFAULT NULLABLE UNIQUE PRIM_KEY FORGN_KEY DESCRIPTION
id Integer() None False None True -

Primary key id
data JSON() {} True None - -

Text field containing JSON properties for this resource
label_id Integer() None True None - label.id

Foreign key id for related label (or class label)
likelihood Float() 1.0 True None - -

(Optional) likelihood/probability of the label assignment
needs_review Boolean() False True None - -

Whether or not this annotation requires review
created_at DateTime() function True None - -

Creation time (UTC)
updated_at TIMESTAMP() function True None - -

Updated time (UTC)
user_id Integer() None False None - users.id

Foriegn key id for owner user object
point_id Integer() None False None - point.id

Foriegn key id for point object
annotation_set_id Integer() None False None - annotation_set.id

Foriegn key id for annotation_set object
comment Text() None True None - -

User comment
parent_id Integer() None True None - annotation.id

id of parent annotation for group of linked observations
RELATED MODELS FILTERABLE
These attributes expose related objects. Relations can either be single elements or a collection of elements. Related models can be used to contruct filters (for endpoints that support filtering, see Making API queries )
FIELD RELATION DIRECTION DESCRIPTION
label label MANYTOONE

Related label object
user users MANYTOONE

Related owner user object
point point MANYTOONE

Related point object
annotation_set annotation_set MANYTOONE

Related annotation_set object
parent annotation MANYTOONE

Parent annotation in a linked set of observations
children annotation ONETOMANY

Collection of linked child observations
annotation_tags annotation_tags ONETOMANY

Collection of annotation_tags associations
versions annotation_version ONETOMANY

None
ASSOCIATION PROXIES FILTERABLE
These attributes map linked objects from collections (eg: many-to-many relationships that have an association table) Association proxies can be used when building filters (for endpoints that support filtering, see Making API queries )
ATTRIBUTE MODEL COLLECTION DESCRIPTION
tags tag annotation_tags Proxy attribute that presents the linked tag objects from the annotation_tags collection
HYBRID ATTRIBUTES FILTERABLE
These are special defined attributes return dynamically processed results and support both query and instance property operations. HYBRID ATTRIBUTES can be used when building filters (for endpoints that support filtering, see Making API queries ). Note HYBRID METHODS may require input parameters.
NAME TYPE ARGS DESCRIPTION
is_child property -

BOOLEAN, whether or not this annotation has a linked parent annotation (queryable)
timestamp property -

The in-situ timestamp for when the annotated object was captured/sampled in the media frame. Returns media.timestamp_start + point.t if point.t is set, otherwise it just returns media.timestamp_start

timestamp_proximity method ts

Absolute difference in seconds of the in-situ timestamp and input ts, which is datetime string eg: "2020-09-25T00:57:11.945009" (or in a format that is parsable by dateutil.parser.parse)
distance method lat, lon

FLOAT, distance (in meters) of closest linked pose relative to lat and lon (which are both in decimal degrees)
xy_distance method x, y

FLOAT, euclidean distance to x and y (which are proportions of the image width and height)
OTHER MODEL ATTRIBUTES FILTERABLE
These are special defined attributes return dynamically processed results. These attributes do not work in filter queries.
NAME TYPE DESCRIPTION
color method

Implied color code for this annotation based on label assignment
current_user_can_edit method

BOOLEAN, whether or not the current user has edit rights for this annotation as implied by the permissions of the parent annotation_set
observation_count method

INT, denoting the number of linked observations of this object
pose method

Properties for related pose item excluding posedata fields
pose_data method

Properties for related pose item including any linked posedata fields
suggested_tags method

List of suggested tag implied from label definition
version_count method

INT, denoting the number of changes in the version history of this object
linked_observations property

List of annotation objects (as dicts) linked with the same object_id
media property

media object information for this annotation via point.media link
object_id property

ID of observation group: ID of primary observation (parent annotation) if linked, otherwise own ID.
supplementary_label property

Selected fiedls of supplementary labels for relates point. Returns id, likelihood, name, lineage_names, username. Can optionally filter through URL param: supplementary_annotation_set_id, which will filter for specific supplementary annotation_set. If not supplied will return all.
tag_names property

Comma-delimited names of applied tags. Can also be used to set tags using comma-delimited tags when creating annotaions
translated_label_id property

Returns id of label.translated for label if defined and if a match is found, otherwise None.
ENDPOINTS
METHODENDPOINT
POST

/api/annotation_set

Create new annotation_set object. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • Restrict request to LOGGED IN users only (post_auth_preprocessor)
PATCH

/api/annotation_set/<id>

Update single annotation_set object with pk field matching param id. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • None (patch_auth_preprocessor)
GET

/api/annotation_set

Get list of annotation_set objects matching API query. See Making API search queries for instructions on making search queries

Included fields:
id, name, parent_id, description, user, user.id, user.username, user.first_name, user.last_name, created_at, children, media_collection, media_collection.id, media_collection.name, label_scheme, label_scheme.id, label_scheme.name, data, current_user_can_view, current_user_is_owner, current_user_is_member, current_user_can_edit, is_public, is_exemplar, is_full_bio_score, is_real_science, is_qaqc, is_final, annotation_count, usergroup_count (see below for more details)

Preprocessors:

  • Assert object view permission from shared usergroups. Restricts objects to the ones that current_user can view (get_many_auth_preprocessor)
GET

/api/annotation_set/<id>

Get single annotation_set object with pk field matching param id

Included fields:
id, name, parent_id, description, user, user.id, user.username, user.first_name, user.last_name, created_at, children, media_collection, media_collection.id, media_collection.name, label_scheme, label_scheme.id, label_scheme.name, data, current_user_can_view, current_user_is_owner, current_user_is_member, current_user_can_edit, is_public, is_exemplar, is_full_bio_score, is_real_science, is_qaqc, is_final, annotation_count, usergroup_count, files, files.id, files.name, files.file_url, files.created_at, media_count, point_count, unannotated_point_count (see below for more details)

Preprocessors:

  • Assert object view permission from shared usergroups. Checks current_user has view permission. Also allows owner of parent to view children or supplementary annotation_sets (get_single_auth_preprocessor)
DELETE

/api/annotation_set/<id>

Delete single annotation_set object with pk field matching param id

Preprocessors:

  • Assert object delete permission from shared usergroups. Checks current user is owner and object is not shared in a usergroup. Also allows owner of parent to delete the child (delete_auth_preprocessor)
POST

/api/annotation_set/<int:instance_id>/group/<int:group_id>

Add object with id instance_id to group with id group_id
DELETE

/api/annotation_set/<int:instance_id>/group/<int:group_id>

Remove resource with id instance_id from group with id group_id
GET

/api/annotation_set/<int:id>/export

Export annotations from annotation_set matching id.

Export annotations matching query define in q. Search queries are executed on the annotation model. This endpoint also supports translating to a target label_scheme (when possible)

Querystring parameters are:

?q={...}&f={...}&disposition=...&template=...&include_columns=[...]

Where q is a JSON search query (see Making API search queries) on the collection model, where f is a JSON dictionary containing a sequence of operations for transforming the data (see Data transformation API for more info), disposition defines the download type which can be attachment (default, triggers a download) or inline (displays in the browser), template is optional depending on the output of the steps in f and can be used to define the export format, include_columns is a JSON list of column fields for the exported model. Nested fields for related models delimited with a . If include_columns is omitted, all allowed columns will be returned.

Metadata for the annotation_set matching id is also returned in the response. Depending on the output format, this could be as part of the response body in a metadata field or in the response headers with the key X-Content-Metadata.

Allowed fields include:

id, tag_names, comment, label.id, label.name, label.lineage_names, label.uuid, label.color, updated_at, user.username, needs_review, likelihood, point.is_targeted, point.id, point.x, point.y, point.t, point.data, point.media.id, point.media.key, point.media.path_best, point.media.timestamp_start, point.media.timestamp_start_local, point.media.path_best_thm, point.pose.timestamp, point.pose.timestamp_local, point.pose.lat, point.pose.lon, point.pose.alt, point.pose.dep, point.pose.data, point.pose.id, point.media.deployment.id, point.media.deployment.key, point.media.deployment.name, point.media.deployment.campaign.id, point.media.deployment.campaign.key, point.media.deployment.campaign.name, object_id, supplementary_label, point.bbox, point.has_xy, point.has_polygon, point.polygon, point.pixels

See annotation model columns, relations and attributes for more information on each of the included fields.

TRANSLATING TO OTHER LABEL_SCHEMES

This endpoint also supports the translation of labels from a source to a target label_scheme. another label_scheme using the semantic translation framework. In order to do this, you need to specify the additional translate url query parameter:

&translate={"target_label_scheme_id":..., "vocab_registry_keys": ..., "mapping_override": ...}
Where target_label_scheme_id [required] is an INT with the id of the target label scheme, vocab_registry_keys [optional] is a list containing the priority order of keys for vocab_registries for which to perform the semantic translation and mapping_override defines a set of key-value pairs containing source label.id : target label.id for which to override the translation. Note: for extended schemes, labels are translated through tree_traversal and no semantic translation is required. With translation parameters you will also need to specify additional columns in the include_columns parameter to obtain the translation output.

Additional allowed columns include:

label.translated.id, label.translated.name, label.translated.lineage_names, label.translated.uuid, label.translated.translation_info,

These columns are ignored if no translate query parameter is supplied.

EXAMPLES

# Example1: get all columns as a downloaded CSV file, only point annotations - filter out whole frame labels
/api/annotation_set/2194/export?template=dataframe.csv&f={"operations":[{"module":"pandas", "method":"json_normalize"}]}&q={"filters":[{"name":"point", "op":"has", "val":{"name":"has_xy", "op":"eq","val":true}}]}
# Example2: aggregate label counts per frame (percent cover, no point information) as a downloaded csv
/api/annotation_set/2171/export?template=dataframe.csv&include_columns=["label.name", "label.lineage_names", "point.media.key", "point.pose.timestamp", "point.pose.lat", "point.pose.lon", "point.pose.alt", "point.pose.dep"]&f={"operations":[{"module":"pandas", "method":"json_normalize"},{"method":"fillna", "kwargs":{"value":"-"}},{"module":"pandas", "method":"count_unstack", "kwargs":{"columns":["label.id", "label.uuid", "label.name", "label.lineage_names", "comment", "tag_names"]}}]}
# Example3: show selected columns as an HTML table in the browser, filter out unlabeled annotations
/api/annotation_set/2171/export?template=dataframe.html&disposition=inline&include_columns=["label.name","label.lineage_names", "updated_at", "point.x", "point.y", "point.media.key", "point.pose.timestamp", "point.pose.lat", "point.pose.lon", "point.pose.alt", "point.pose.dep", "point.media.deployment.key", "point.media.deployment.campaign.key"]&f={"operations":[{"module":"pandas", "method":"json_normalize"}]}&q={"filters":[{"name":"label_id", "op":"is_not_null"}]}
# Example4: show HTML table in browser with tally of label counts (can be refreshed for readable live summary)
/api/annotation_set/2171/export?template=dataframe.html&disposition=inline&include_columns=["label.uuid","label.name","label.lineage_names","label.id"]&f={"operations":[{"module":"pandas","method":"json_normalize"},{"module":"pandas","method":"groupby_count"}]}&q={"filters":[{"name":"label_id","op":"is_not_null"}]}

NB: the UI contains an "ADVANCED" option which can help build more complex export queries.
GET

/api/annotation_set/<int:id>/media

None
GET

/api/annotation_set/<int:id>/annotations

Returns list of annotation objects contained in the annotation_set with an ID matching id. The results can be filtered and searched. See Making API search queries for instructions on making search queries. In addition it accepts include_columns and include_methods query parameters which override returned fields of annotation model.
GET

/api/annotation_set/<int:id>/annotations/<group_by>

THIS ENDPOINT IS DEPRECATED! USE /api/annotation/tally/ in the annotation resource

Returns lists of the labels used in the annotation_set with an ID matching id. The group_by parameter must one of [label_updated, label_frequency, deployment] which returns the most recently used labels, counts by label (most frequently used) or counts by deployment, respectively. The number of results and page can be controlled with the results_per_page and page query parameters, respectively.
POST

/api/annotation_set/<int:annotation_set_id>/media/<int:media_id>

Add the media object with the ID media_id to the media_collection of the annotation_set matching annotation_set_id
DELETE

/api/annotation_set/<int:annotation_set_id>/media/<int:media_id>

Remove the media object with the ID media_id from the media_collection of the annotation_set matching annotation_set_id
POST

/api/annotation_set/<int:id>/clone

Clone the annotation_set matching id to create a new one under the same collection. This will clone all annotation_set properties along with all points, annotations, tags, labels including all annotation properties (needs_review, likelihood, comment). Note: this does not currently preserve linking between annotations in observation groups.

This endpoint also supports the translation of labels from a source to a target label_scheme using the semantic translation framework. In order to do this, you need to specify the additional translate url query parameter:

&translate={"target_label_scheme_id":..., "vocab_registry_keys": ..., "mapping_override": ...}
Where target_label_scheme_id [required] is an INT with the id of the target label scheme, vocab_registry_keys [optional] is a list containing the priority order of keys for vocab_registries for which to perform the semantic translation and mapping_override defines a set of key-value pairs containing source label.id : target label.id for which to override the translation. Note: for extended schemes, labels are translated through tree_traversal and no semantic translation is required.
MODEL COLUMNS FILTERABLE
These attributes map to database columns and can be used when building filters (for endpoints that support filtering, see Making API queries )
NAME TYPE DEFAULT NULLABLE UNIQUE PRIM_KEY FORGN_KEY DESCRIPTION
id Integer() None False None True -

Primary key id
data JSON() {} True None - -

Text field containing JSON properties for this resource
name String(length=80) None False None - -

None
description Text() None True None - -

None
media_collection_id Integer() None False None - media_collection.id

None
label_scheme_id Integer() None False None - label_scheme.id

None
user_id Integer() None False None - users.id

Foreign key reference for ID of related owner users model
created_at DateTime() function False None - -

None
parent_id Integer() None True None - annotation_set.id

None
is_exemplar Boolean() False True None - -

None
is_full_bio_score Boolean() False True None - -

whether or not the intent was full biodiversity scoring, or just targeted scoring
is_real_science Boolean() False True None - -

whether or not this is for science, or was for education / training / testing
is_qaqc Boolean() False True None - -

whether or not the annotation set has been QA/QC'd
is_final Boolean() False True None - -

whether or not the annotator has completed annotating
type String(length=80) base True None - -

None
RELATED MODELS FILTERABLE
These attributes expose related objects. Relations can either be single elements or a collection of elements. Related models can be used to contruct filters (for endpoints that support filtering, see Making API queries )
FIELD RELATION DIRECTION DESCRIPTION
media_collection media_collection MANYTOONE

None
label_scheme label_scheme MANYTOONE

None
user users MANYTOONE

Related owner users model
parent annotation_set MANYTOONE

None
usergroups groups MANYTOMANY

List of groups objects that contain this resource
points point ONETOMANY

List of point objects
annotations annotation ONETOMANY

List of related annotation objects
children annotation_set ONETOMANY

None
files annotation_set_file ONETOMANY

None
HYBRID ATTRIBUTES FILTERABLE
These are special defined attributes return dynamically processed results and support both query and instance property operations. HYBRID ATTRIBUTES can be used when building filters (for endpoints that support filtering, see Making API queries ). Note HYBRID METHODS may require input parameters.
NAME TYPE ARGS DESCRIPTION
media_count property -

Number of media items in the media_collection
annotation_count property -

Total number of labeled annotations this annotation_set
is_child property -

BOOLEAN, whether or not this annotation has a linked parent annotation
is_public property -

Whether or not this object is public (i.e. shared in a public group)
current_user_is_owner property -

Whether or not the currently logged in user is the owner of this object
current_user_is_member property -

Whether or not the current logged in user is a member of a group that includes this object
current_user_is_edit_member property -

Whether or not the current logged in user is a member with edit permission of a group that includes this object
current_user_can_view property -

Whether or not the current user has permission to view this object
current_user_can_edit property -

Whether or not the current logged in user has edit permission (owner or edit_member)
OTHER MODEL ATTRIBUTES FILTERABLE
These are special defined attributes return dynamically processed results. These attributes do not work in filter queries.
NAME TYPE DESCRIPTION
point_count method

None
unannotated_point_count method

None
usergroup_count method

None
ENDPOINTS
METHODENDPOINT
POST

/api/annotation_set_file

Create new annotation_set_file object. Expects JSON. Fields shown in MODEL COLUMNS below. Add user_id to post payload if not supplied

Preprocessors:

  • Restrict request to LOGGED IN users only (post_auth_preprocessor)
PATCH

/api/annotation_set_file/<id>

Update single annotation_set_file object with pk field matching param id. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • Restrict request to OWNER only (patch_auth_preprocessor)
GET

/api/annotation_set_file

Get list of annotation_set_file objects matching API query. See Making API search queries for instructions on making search queries

Included fields:
user_id, description, iscompressed, annotation_set_id, file_url, id, name, last_save (see below for more details)

Preprocessors:

  • Allow all requests (get_many_auth_preprocessor)
GET

/api/annotation_set_file/<id>

Get single annotation_set_file object with pk field matching param id

Included fields:
user_id, description, iscompressed, annotation_set_id, file_url, id, name, last_save (see below for more details)

Preprocessors:

  • Allow all requests (get_single_auth_preprocessor)
DELETE

/api/annotation_set_file/<id>

Delete single annotation_set_file object with pk field matching param id

Preprocessors:

  • Restrict request to OWNER only (delete_auth_preprocessor)
GET

/api/annotation_set_file/<int:fid>/data

Annotation Set File resource. Get the data for the file resource matching fid. This endpoint also provides options to manipulate, transform and save data to the database. The querystring takes the following form: 

?f={...}&save={...}&disposition=...&template=...
where f is a JSON dictionary containing a sequence of operations for transforming the data (see Data transformation API for more info), disposition is optional and defines the download type which can be inline (default, displays in the browser) or attachment (triggers a download) , template is optional depending on the output of the steps in f and can be used to define the export format, save is a JSON dictionary that defines batch save operations. This can be used to save the file content or the output of the operations in f to a related database model collection.

Example1: TODO 

/api/annotation_set_file/2/data?save={"collection": "annotations"}&f={"operations": [{"module": "pandas", "method": "read_csv", "kwargs": {"parse_dates": ["time"], "skiprows": 2, "usecols": [2, 3, 4, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15]}}, {"method": "rename", "kwargs": {"columns": {"image_filename": "key", "longitude": "pose.lon", "latitude": "pose.lat", "depth_sensor": "pose.data.dep", "altitude_sensor": "pose.alt", "depth": "pose.dep", "sea_water_temperature": "pose.data.temp", "sea_water_salinity": "pose.data.salinity", "chlorophyll_concentration_in_sea_water": "pose.data.chlorophyll", "backscattering_ratio": "pose.data.backscater", "colored_dissolved_organic_matter": "pose.data.colored_dissolved_organic_matter", "time": "timestamp_start", "cluster_tag": "pose.data.cluster_tag"}}}, {"method": "to_dict", "kwargs": {"orient": "records"}}, {"module": "data", "method": "unflatten_dicts", "kwargs": {}}]}
POST

/api/annotation_set_file/data

Save file data to database. Use this if it is not possible to dynamically link the file using the file_url or if the file_url is potentially unstable / ephemeral. This should be a multipart form post with file parameter set to the uploaded file and all other fields as in the object definition below.
MODEL COLUMNS FILTERABLE
These attributes map to database columns and can be used when building filters (for endpoints that support filtering, see Making API queries )
NAME TYPE DEFAULT NULLABLE UNIQUE PRIM_KEY FORGN_KEY DESCRIPTION
id Integer() None False None True -

Primary key id
last_save JSON() None True None - -

Sequence of file operations performed at last save
name Text() None False False - -

The name of the file (optional). Defaults to basename of either file_url or the path of the uploaded file
file_url Text() None True False - -

The URL of the file to be loaded dynamically (if data field is not set)
description Text() None True None - -

The description of the file (optional)
_rawfiledata LargeBinary() None True None - -

The raw file storage for the file. This is not directly accessible through the API
iscompressed Boolean() False True None - -

Whether or not the file is compressed or not. If so, it will be automatically decompressed upon access.
user_id Integer() None False None - users.id

None
annotation_set_id Integer() None False None - annotation_set.id

None
created_at DateTime() function False None - -

None
updated_at DateTime() function True None - -

Updated time (UTC)
RELATED MODELS FILTERABLE
These attributes expose related objects. Relations can either be single elements or a collection of elements. Related models can be used to contruct filters (for endpoints that support filtering, see Making API queries )
FIELD RELATION DIRECTION DESCRIPTION
user users MANYTOONE

None
annotation_set annotation_set MANYTOONE

None
OTHER MODEL ATTRIBUTES FILTERABLE
These are special defined attributes return dynamically processed results. These attributes do not work in filter queries.
NAME TYPE DESCRIPTION
data property

None
ENDPOINTS
METHODENDPOINT
POST

/api/annotation_tags

Create new annotation_tags object. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • Restrict request to LOGGED IN users only (post_auth_preprocessor)
GET

/api/annotation_tags

Get list of annotation_tags objects matching API query. See Making API search queries for instructions on making search queries

Preprocessors:

  • Allow all requests (get_many_auth_preprocessor)
GET

/api/annotation_tags/<annotation_id>

Get single annotation_tags object with pk field matching param annotation_id

Preprocessors:

  • Allow all requests (get_single_auth_preprocessor)
DELETE

/api/annotation_tags/<annotation_id>

Delete single annotation_tags object with pk field matching param annotation_id

Preprocessors:

  • Restrict request to OWNER only (delete_auth_preprocessor)
MODEL COLUMNS FILTERABLE
These attributes map to database columns and can be used when building filters (for endpoints that support filtering, see Making API queries )
NAME TYPE DEFAULT NULLABLE UNIQUE PRIM_KEY FORGN_KEY DESCRIPTION
annotation_id Integer() None False None True annotation.id

id of linked annotation
tag_id Integer() None False None True tag.id

id of linked tag
assoc_created_at DateTime() function True None - -

None
RELATED MODELS FILTERABLE
These attributes expose related objects. Relations can either be single elements or a collection of elements. Related models can be used to contruct filters (for endpoints that support filtering, see Making API queries )
FIELD RELATION DIRECTION DESCRIPTION
annotation annotation MANYTOONE

Linked annotation object
tag tag MANYTOONE

Linked tag object
ENDPOINTS
METHODENDPOINT
GET

/api/campaign-deployment/<resource>

:param resource: :return:

Examples:

# search campaign-deployments for "gbr" /api/campaign-deployment/deployment?q={"filters":[{"or":[{"name":"key","op":"ilike","val":"%gbr%"},{"name":"campaign","op":"has","val":{"name":"key","op":"ilike","val":"%gbr%"}}]}]} # match list of deployment keys (campaign-deployment) /api/campaign-deployment?q={"filters":[{"name":"key","op":"in","val":["r20071004_013437_gbr_05_noggin_grids","r20071010_230932_gbr_09_hydrographers_leg"]}]} # as above but for deployments /api/campaign-deployment/deployment?q={"filters":[{"name":"key","op":"in","val":["r20071004_013437_gbr_05_noggin_grids","r20071010_230932_gbr_09_hydrographers_leg"]}]} # as above but for IDs and not keys /api/campaign-deployment/deployment?q={"filters":[{"name":"id","op":"in","val":[9495,9491]}]}
GET

/api/campaign-deployment

:param resource: :return:

Examples:

# search campaign-deployments for "gbr" /api/campaign-deployment/deployment?q={"filters":[{"or":[{"name":"key","op":"ilike","val":"%gbr%"},{"name":"campaign","op":"has","val":{"name":"key","op":"ilike","val":"%gbr%"}}]}]} # match list of deployment keys (campaign-deployment) /api/campaign-deployment?q={"filters":[{"name":"key","op":"in","val":["r20071004_013437_gbr_05_noggin_grids","r20071010_230932_gbr_09_hydrographers_leg"]}]} # as above but for deployments /api/campaign-deployment/deployment?q={"filters":[{"name":"key","op":"in","val":["r20071004_013437_gbr_05_noggin_grids","r20071010_230932_gbr_09_hydrographers_leg"]}]} # as above but for IDs and not keys /api/campaign-deployment/deployment?q={"filters":[{"name":"id","op":"in","val":[9495,9491]}]}
ENDPOINTS
METHODENDPOINT
POST

/api/campaign

Create new campaign object. Expects JSON. Fields shown in MODEL COLUMNS below. Add user_id to post payload if not supplied

Preprocessors:

  • Restrict request to LOGGED IN users only (post_auth_preprocessor)

Postprocessors:

  • Clears the request cache object for this resource (to cause cache refresh on next request) (_clear_cache)
PATCH

/api/campaign/<id>

Update single campaign object with pk field matching param id. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • Restrict request to OWNER only (patch_auth_preprocessor)

Postprocessors:

  • Clears the request cache object for this resource (to cause cache refresh on next request) (_clear_cache)
GET

/api/campaign

Get list of campaign objects matching API query. See Making API search queries for instructions on making search queries

Included fields:
color, id, key, name, description, deployment_count, media_count, total_annotation_count, public_annotation_count, latlon (see below for more details)

Preprocessors:

  • Allow all requests (get_many_auth_preprocessor)
GET

/api/campaign/<id>

Get single campaign object with pk field matching param id

Included fields:
color, id, key, name, description, deployment_count, media_count, total_annotation_count, public_annotation_count, latlon, user_id, stats, platforms, total_annotation_count, public_annotation_count (see below for more details)

Preprocessors:

  • Allow all requests (get_single_auth_preprocessor)
DELETE

/api/campaign/<id>

Delete single campaign object with pk field matching param id

Preprocessors:

  • Restrict request to OWNER only (delete_auth_preprocessor)
GET

/api/campaign/map

Deployment resource

Minimal Deployment Resource for map data - result is cached for fast loading. Cache is cleared when new deployments are saved.

:param GET: json: q: restless search query. :returns GET: json: a json string containing the structure of stuff
MODEL COLUMNS FILTERABLE
These attributes map to database columns and can be used when building filters (for endpoints that support filtering, see Making API queries )
NAME TYPE DEFAULT NULLABLE UNIQUE PRIM_KEY FORGN_KEY DESCRIPTION
id Integer() None False None True -

Primary key id
name String(length=80) None False None - -

Name of this campaign
key String(length=80) None False True - -

Key of this campaign (used for generating paths and links in repo)
path Text() None True None - -

None
color String(length=10) function True False - -

Hex colour code for this campaign
description Text() None True None - -

Description for this campaign
user_id Integer() None False None - users.id

ID of the [user][#users] who created this campaign
created_at DateTime() function False None - -

Datetime of creation
media_path_pattern Text() None True None - -

None
thm_path_pattern Text() None True None - -

None
RELATED MODELS FILTERABLE
These attributes expose related objects. Relations can either be single elements or a collection of elements. Related models can be used to contruct filters (for endpoints that support filtering, see Making API queries )
FIELD RELATION DIRECTION DESCRIPTION
user users MANYTOONE

None
campaign_mv campaigns_mv ONETOMANY

None
deployments deployment ONETOMANY

None
info campaigninfo ONETOMANY

None
files campaign_file ONETOMANY

None
HYBRID ATTRIBUTES FILTERABLE
These are special defined attributes return dynamically processed results and support both query and instance property operations. HYBRID ATTRIBUTES can be used when building filters (for endpoints that support filtering, see Making API queries ). Note HYBRID METHODS may require input parameters.
NAME TYPE ARGS DESCRIPTION
deployment_count property -

Total number of deployments contained in this campaign
media_count property -

Total number of media objects contained in this campaign
geom property -

The centroid geom point of all the poses contained in this campaign
timestamp property -

A timestamp from the poses contained in this campaign
total_annotation_count property -

Total number of labeled annotations linked to media objects from this campaign
public_annotation_count property -

Total number of publicly shared labeled annotations linked to media objects from this campaign
OTHER MODEL ATTRIBUTES FILTERABLE
These are special defined attributes return dynamically processed results. These attributes do not work in filter queries.
NAME TYPE DESCRIPTION
extent method

Compute spatial extent of Campaign :return: list with format [[SW_LAT, SW_LON],[NE_LAT,NE_LON]]
file_count method

None
platforms method

None
stats method

None
timestamp_range method

None
latlon property

None
ENDPOINTS
METHODENDPOINT
POST

/api/campaign_file

Create new campaign_file object. Expects JSON. Fields shown in MODEL COLUMNS below. Add user_id to post payload if not supplied

Preprocessors:

  • Restrict request to LOGGED IN users only (post_auth_preprocessor)
PATCH

/api/campaign_file/<id>

Update single campaign_file object with pk field matching param id. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • Restrict request to OWNER only (patch_auth_preprocessor)
GET

/api/campaign_file

Get list of campaign_file objects matching API query. See Making API search queries for instructions on making search queries

Included fields:
user_id, description, iscompressed, campaign_id, file_url, id, name (see below for more details)

Preprocessors:

  • Allow all requests (get_many_auth_preprocessor)
GET

/api/campaign_file/<id>

Get single campaign_file object with pk field matching param id

Included fields:
user_id, description, iscompressed, campaign_id, file_url, id, name (see below for more details)

Preprocessors:

  • Allow all requests (get_single_auth_preprocessor)
DELETE

/api/campaign_file/<id>

Delete single campaign_file object with pk field matching param id

Preprocessors:

  • Restrict request to OWNER only (delete_auth_preprocessor)
GET

/api/campaign_file/<int:fid>/data

Get the data for the file resource matching fid. This endpoint also provides options to manipulate, transform and save data to the database. The querystring takes the following form: 

?f={...}&save={...}&disposition=...&template=...
where f is a JSON dictionary containing a sequence of operations for transforming the data (see Data transformation API for more info), disposition is optional and defines the download type which can be inline (default, displays in the browser) or attachment (triggers a download) , template is optional depending on the output of the steps in f and can be used to define the export format, save is a JSON dictionary that defines batch save operations. This can be used to save the file content or the output of the operations in f to a related database model collection.
POST

/api/campaign_file/data

Save file data to database. Use this if it is not possible to dynamically link the file using the file_url or if the file_url is potentially unstable / ephemeral. This should be a multipart form post with file parameter set to the uploaded file and all other fields as in the object definition below.
MODEL COLUMNS FILTERABLE
These attributes map to database columns and can be used when building filters (for endpoints that support filtering, see Making API queries )
NAME TYPE DEFAULT NULLABLE UNIQUE PRIM_KEY FORGN_KEY DESCRIPTION
id Integer() None False None True -

Primary key id
last_save JSON() None True None - -

Sequence of file operations performed at last save
name Text() None False False - -

The name of the file (optional). Defaults to basename of either file_url or the path of the uploaded file
file_url Text() None True False - -

The URL of the file to be loaded dynamically (if data field is not set)
description Text() None True None - -

The description of the file (optional)
_rawfiledata LargeBinary() None True None - -

The raw file storage for the file. This is not directly accessible through the API
iscompressed Boolean() False True None - -

Whether or not the file is compressed or not. If so, it will be automatically decompressed upon access.
user_id Integer() None False None - users.id

None
campaign_id Integer() None False None - campaign.id

None
created_at DateTime() function True None - -

None
updated_at DateTime() function True None - -

Updated time (UTC)
RELATED MODELS FILTERABLE
These attributes expose related objects. Relations can either be single elements or a collection of elements. Related models can be used to contruct filters (for endpoints that support filtering, see Making API queries )
FIELD RELATION DIRECTION DESCRIPTION
user users MANYTOONE

None
campaign campaign MANYTOONE

None
OTHER MODEL ATTRIBUTES FILTERABLE
These are special defined attributes return dynamically processed results. These attributes do not work in filter queries.
NAME TYPE DESCRIPTION
data property

None
ENDPOINTS
METHODENDPOINT
POST

/api/campaigninfo

Create new campaigninfo object. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • Restrict request to LOGGED IN users only (post_auth_preprocessor)
GET

/api/campaigninfo

Get list of campaigninfo objects matching API query. See Making API search queries for instructions on making search queries

Included fields:
name, description, created_at, campaign_id, id (see below for more details)

Preprocessors:

  • Allow all requests (get_many_auth_preprocessor)
GET

/api/campaigninfo/<id>

Get single campaigninfo object with pk field matching param id

Included fields:
name, description, created_at, campaign_id, id (see below for more details)

Preprocessors:

  • Allow all requests (get_single_auth_preprocessor)
DELETE

/api/campaigninfo/<id>

Delete single campaigninfo object with pk field matching param id

Preprocessors:

  • Restrict request to OWNER only (delete_auth_preprocessor)
MODEL COLUMNS FILTERABLE
These attributes map to database columns and can be used when building filters (for endpoints that support filtering, see Making API queries )
NAME TYPE DEFAULT NULLABLE UNIQUE PRIM_KEY FORGN_KEY DESCRIPTION
id Integer() None False None True -

Primary key id
name String(length=80) None False None - -

None
description Text() None False None - -

None
created_at DateTime() function False None - -

None
campaign_id Integer() None False None - campaign.id

None
RELATED MODELS FILTERABLE
These attributes expose related objects. Relations can either be single elements or a collection of elements. Related models can be used to contruct filters (for endpoints that support filtering, see Making API queries )
FIELD RELATION DIRECTION DESCRIPTION
campaign campaign MANYTOONE

None
ENDPOINTS
METHODENDPOINT
POST

/api/datasource

Create new datasource object. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • Restrict request to ADMIN user only (assert_current_user_is_admin)
  • Restrict request to LOGGED IN users only (post_auth_preprocessor)
PATCH

/api/datasource/<id>

Update single datasource object with pk field matching param id. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • Restrict request to ADMIN user only (assert_current_user_is_admin)
  • Restrict request to OWNER only (patch_auth_preprocessor)
GET

/api/datasource

Get list of datasource objects matching API query. See Making API search queries for instructions on making search queries

Included fields:
id, name, campaign_search, datafile_pattern, datafile_search, deployment_search, media_pattern, mediadir_search, thumb_pattern, thumbdir_search, urlbase_browse, datafile_operations, datasource_type, datasource_type.id, datasource_type.name, platform, platform.id, platform.name, user_id, created_at, credential_key (see below for more details)

Preprocessors:

  • Allow all requests (get_many_auth_preprocessor)
GET

/api/datasource/<id>

Get single datasource object with pk field matching param id

Included fields:
id, name, campaign_search, datafile_pattern, datafile_search, deployment_search, media_pattern, mediadir_search, thumb_pattern, thumbdir_search, urlbase_browse, datafile_operations, datasource_type, datasource_type.id, datasource_type.name, platform, platform.id, platform.name, user_id, created_at, credential_key (see below for more details)

Preprocessors:

  • Allow all requests (get_single_auth_preprocessor)
DELETE

/api/datasource/<id>

Delete single datasource object with pk field matching param id

Preprocessors:

  • Restrict request to ADMIN user only (assert_current_user_is_admin)
  • Restrict request to OWNER only (delete_auth_preprocessor)
MODEL COLUMNS FILTERABLE
These attributes map to database columns and can be used when building filters (for endpoints that support filtering, see Making API queries )
NAME TYPE DEFAULT NULLABLE UNIQUE PRIM_KEY FORGN_KEY DESCRIPTION
id Integer() None False None True -

Primary key id
name String(length=80) None False True - -

None
campaign_search Text() None True None - -

None
datafile_pattern Text() None True None - -

None
datafile_search Text() None True None - -

None
deployment_search Text() None True None - -

None
media_pattern Text() None True None - -

None
mediadir_search Text() None True None - -

None
thumb_pattern Text() None True None - -

None
thumbdir_search Text() None True None - -

None
urlbase_browse Text() None True None - -

None
credential_key Text() None True None - -

None
datafile_operations JSON() None True None - -

None
datasource_type_id Integer() None False None - datasource_type.id

None
platform_id Integer() None False None - platform.id

None
user_id Integer() None False None - users.id

None
created_at DateTime() function False None - -

None
RELATED MODELS FILTERABLE
These attributes expose related objects. Relations can either be single elements or a collection of elements. Related models can be used to contruct filters (for endpoints that support filtering, see Making API queries )
FIELD RELATION DIRECTION DESCRIPTION
datasource_type datasource_type MANYTOONE

None
platform platform MANYTOONE

None
user users MANYTOONE

None
deployments deployment ONETOMANY

None
ENDPOINTS
METHODENDPOINT
GET

/api/datasource_type

Get list of datasource_type objects matching API query. See Making API search queries for instructions on making search queries

Included fields:
id, name, created_at (see below for more details)

Preprocessors:

  • Allow all requests (get_many_auth_preprocessor)
GET

/api/datasource_type/<id>

Get single datasource_type object with pk field matching param id

Included fields:
id, name, created_at (see below for more details)

Preprocessors:

  • Allow all requests (get_single_auth_preprocessor)
MODEL COLUMNS FILTERABLE
These attributes map to database columns and can be used when building filters (for endpoints that support filtering, see Making API queries )
NAME TYPE DEFAULT NULLABLE UNIQUE PRIM_KEY FORGN_KEY DESCRIPTION
id Integer() None False None True -

Primary key id
name String(length=80) None False True - -

None
created_at DateTime() function False None - -

None
RELATED MODELS FILTERABLE
These attributes expose related objects. Relations can either be single elements or a collection of elements. Related models can be used to contruct filters (for endpoints that support filtering, see Making API queries )
FIELD RELATION DIRECTION DESCRIPTION
datasources datasource ONETOMANY

None
ENDPOINTS
METHODENDPOINT
POST

/api/deployment

Create new deployment object. Expects JSON. Fields shown in MODEL COLUMNS below. Add user_id to post payload if not supplied

Preprocessors:

  • Restrict request to LOGGED IN users only (post_auth_preprocessor)
PATCH

/api/deployment/<id>

Update single deployment object with pk field matching param id. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • Restrict request to OWNER only (patch_auth_preprocessor)
GET

/api/deployment

Get list of deployment objects matching API query. See Making API search queries for instructions on making search queries

Included fields:
name, key, id, created_at, campaign, campaign.id, campaign.name, platform, platform.id, platform.name, is_valid, color, pose (see below for more details)

Preprocessors:

  • Allow all requests (get_many_auth_preprocessor)
GET

/api/deployment/<id>

Get single deployment object with pk field matching param id

Included fields:
name, key, id, created_at, campaign, campaign.id, campaign.name, platform, platform.id, platform.name, is_valid, color, pose, user_id, created_at, description, campaign.key, platform, platform.id, platform.name, platform.key, files, files.id, files.name, files.file_url, media_count, pose_stats, layers, total_annotation_count, public_annotation_count, annotated_media_count, extent (see below for more details)

Preprocessors:

  • Allow all requests (get_single_auth_preprocessor)
DELETE

/api/deployment/<id>

Delete single deployment object with pk field matching param id

Preprocessors:

  • Restrict request to OWNER only (delete_auth_preprocessor)
GET

/api/deployment/map

Deployment resource

Minimal Deployment Resource for map data - result is cached for fast loading. Cache is cleared when new deployments are saved.

:param GET: json: q: restless search query. :returns GET: json: a json string containing the structure of stuff
GET

/api/deployment/<int:id>/export

Export deployment information for a deployment matching id. Parameters:

?format=...&file=...&return=[...]

Where: format is one of either [csv or json] file is one of either [attachment or text] return list of attributes / properties to include in the export, which can be a combination of:

datasetkeys: media, deployment and campaign keys

mediapaths: saved path of media file (in most cases, you'll want mediapaths-resolved instead)

mediapaths-resolved: generated path of media file (from datasource plugin - USE THIS)

pose: lat, long, alt, depth, timestamp info

posedata: if pose is requested, all auxiliary pose_data will be added. Otherwise, returns nothing.

EXAMPLES

# Example
/api/deployment/11/export?format=csv&file=attachment&return=datasetkeys&return=mediapaths-resolved&return=pose&return=posedata

WARNING!: this endpoint will be changed in a future update to be more consistent with other export endpoints. For now, feel free to use it, with the caveat that any third-party integrations may require updating the query format / parameters (reminder: this project is still in active development mode).
GET

/api/deployment/<int:id>/ecoregion

Get ecoregion info from ESRI API Marine Ecoregions Of the World (MEOW) feature layer. Uses latlon of deployment to determine the relevant ecoregion. Accepts querystring parameter: fields which is a comma-separated list of properties to return, which can be a subset of: fields = FID, ECO_CODE, ECOREGION, PROV_CODE, PROVINCE, RLM_CODE, REALM, ALT_CODE, ECO_CODE_X, Lat_Zone, Shape__Area, Shape__Length if not set, it will default to fields=*, which will return all properties.
MODEL COLUMNS FILTERABLE
These attributes map to database columns and can be used when building filters (for endpoints that support filtering, see Making API queries )
NAME TYPE DEFAULT NULLABLE UNIQUE PRIM_KEY FORGN_KEY DESCRIPTION
id Integer() None False None True -

Primary key id
name String(length=80) None False None - -

None
key String(length=80) None False None - -

None
path Text() None True None - -

None
campaign_id Integer() None False None - campaign.id

None
user_id Integer() None False None - users.id

None
description Text() None True None - -

None
created_at DateTime() function False None - -

None
platform_id Integer() None False None - platform.id

None
datasource_id Integer() None False None - datasource.id

None
is_valid Boolean() True True None - -

None
RELATED MODELS FILTERABLE
These attributes expose related objects. Relations can either be single elements or a collection of elements. Related models can be used to contruct filters (for endpoints that support filtering, see Making API queries )
FIELD RELATION DIRECTION DESCRIPTION
campaign campaign MANYTOONE

None
user users MANYTOONE

None
platform platform MANYTOONE

None
datasource datasource MANYTOONE

None
deployment_mv deployments_mv ONETOMANY

None
media media ONETOMANY

None
events deployment_event ONETOMANY

None
files deployment_file ONETOMANY

None
HYBRID ATTRIBUTES FILTERABLE
These are special defined attributes return dynamically processed results and support both query and instance property operations. HYBRID ATTRIBUTES can be used when building filters (for endpoints that support filtering, see Making API queries ). Note HYBRID METHODS may require input parameters.
NAME TYPE ARGS DESCRIPTION
media_count property -

Total number of media objects contained in this deployment
annotated_media_count property -

Number of media objects with one or more labeled annotations in this deployment
geom property -

The centroid geom point of all the poses contained in this deployment
timestamp property -

A timestamp from the poses contained in this deployment
total_annotation_count property -

Total number of labeled annotations linked to media objects from this deployment
public_annotation_count property -

Total number of publicly shared labeled annotations linked to media objects from this deployment
OTHER MODEL ATTRIBUTES FILTERABLE
These are special defined attributes return dynamically processed results. These attributes do not work in filter queries.
NAME TYPE DESCRIPTION
color method

None
extent method

Compute spatial extent of Campaign :return: list with format [[SW_LAT, SW_LON],[NE_LAT,NE_LON]]
layers method

None
pose_stats method

None
timestamp_range method

None
latlon property

None
pose property

None
ENDPOINTS
METHODENDPOINT
POST

/api/deployment_event

Create new deployment_event object. Expects JSON. Fields shown in MODEL COLUMNS below. A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance's class are allowed. These could be, for example, any mapped columns or relationships.

Preprocessors:

  • Restrict request to LOGGED IN users only (post_auth_preprocessor)
PATCH

/api/deployment_event/<id>

Update single deployment_event object with pk field matching param id. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • Restrict request to OWNER only (patch_auth_preprocessor)
GET

/api/deployment_event

Get list of deployment_event objects matching API query. See Making API search queries for instructions on making search queries

Included fields:
media, media.id, media.key, media.path_best, media.path_best_thm, user_id, description, timestamp, created_at, pose, pose.lat, pose.lon, pose.alt, pose.dep, pose.timestamp, deployment, deployment.name, deployment.key, deployment.id, deployment.created_at, deployment.campaign_id, deployment_event_type, user, user.username, user.info, user.first_name, user.last_name, user.email, user.id, deployment_event_type_id, media_id, deployment_id, id (see below for more details)

Preprocessors:

  • Allow all requests (get_many_auth_preprocessor)
GET

/api/deployment_event/<id>

Get single deployment_event object with pk field matching param id

Included fields:
media, media.id, media.key, media.path_best, media.path_best_thm, user_id, description, timestamp, created_at, pose, pose.lat, pose.lon, pose.alt, pose.dep, pose.timestamp, deployment, deployment.name, deployment.key, deployment.id, deployment.created_at, deployment.campaign_id, deployment_event_type, user, user.username, user.info, user.first_name, user.last_name, user.email, user.id, deployment_event_type_id, media_id, deployment_id, id (see below for more details)

Preprocessors:

  • Allow all requests (get_single_auth_preprocessor)
DELETE

/api/deployment_event/<id>

Delete single deployment_event object with pk field matching param id

Preprocessors:

  • Restrict request to OWNER only (delete_auth_preprocessor)
MODEL COLUMNS FILTERABLE
These attributes map to database columns and can be used when building filters (for endpoints that support filtering, see Making API queries )
NAME TYPE DEFAULT NULLABLE UNIQUE PRIM_KEY FORGN_KEY DESCRIPTION
id Integer() None False None True -

Primary key id
description Text() None False None - -

None
user_id Integer() None False None - users.id

None
created_at DateTime() function False None - -

None
timestamp DateTime() function False None - -

None
pose_id Integer() None True None - pose.id

None
media_id Integer() None True None - media.id

None
deployment_event_type_id Integer() None False None - deployment_event_type.id

None
deployment_id Integer() None False None - deployment.id

None
RELATED MODELS FILTERABLE
These attributes expose related objects. Relations can either be single elements or a collection of elements. Related models can be used to contruct filters (for endpoints that support filtering, see Making API queries )
FIELD RELATION DIRECTION DESCRIPTION
user users MANYTOONE

None
pose pose MANYTOONE

None
media media MANYTOONE

None
deployment_event_type deployment_event_type MANYTOONE

None
deployment deployment MANYTOONE

None
ENDPOINTS
METHODENDPOINT
POST

/api/deployment_event_type

Create new deployment_event_type object. Expects JSON. Fields shown in MODEL COLUMNS below. A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance's class are allowed. These could be, for example, any mapped columns or relationships.

Preprocessors:

  • Restrict request to LOGGED IN users only (post_auth_preprocessor)
PATCH

/api/deployment_event_type/<id>

Update single deployment_event_type object with pk field matching param id. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • Restrict request to OWNER only (patch_auth_preprocessor)
GET

/api/deployment_event_type

Get list of deployment_event_type objects matching API query. See Making API search queries for instructions on making search queries

Included fields:
name, id, data (see below for more details)

Preprocessors:

  • Allow all requests (get_many_auth_preprocessor)
GET

/api/deployment_event_type/<id>

Get single deployment_event_type object with pk field matching param id

Included fields:
name, id, data (see below for more details)

Preprocessors:

  • Allow all requests (get_single_auth_preprocessor)
DELETE

/api/deployment_event_type/<id>

Delete single deployment_event_type object with pk field matching param id

Preprocessors:

  • Restrict request to OWNER only (delete_auth_preprocessor)
MODEL COLUMNS FILTERABLE
These attributes map to database columns and can be used when building filters (for endpoints that support filtering, see Making API queries )
NAME TYPE DEFAULT NULLABLE UNIQUE PRIM_KEY FORGN_KEY DESCRIPTION
id Integer() None False None True -

Primary key id
data JSON() {} True None - -

Text field containing JSON properties for this resource
name String(length=80) None False True - -

None
RELATED MODELS FILTERABLE
These attributes expose related objects. Relations can either be single elements or a collection of elements. Related models can be used to contruct filters (for endpoints that support filtering, see Making API queries )
FIELD RELATION DIRECTION DESCRIPTION
deployment_events deployment_event ONETOMANY

None
ENDPOINTS
METHODENDPOINT
POST

/api/deployment_file

Create new deployment_file object. Expects JSON. Fields shown in MODEL COLUMNS below. Add user_id to post payload if not supplied

Preprocessors:

  • Restrict request to LOGGED IN users only (post_auth_preprocessor)
PATCH

/api/deployment_file/<id>

Update single deployment_file object with pk field matching param id. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • Restrict request to OWNER only (patch_auth_preprocessor)
GET

/api/deployment_file

Get list of deployment_file objects matching API query. See Making API search queries for instructions on making search queries

Included fields:
user_id, description, iscompressed, campaign_id, file_url, id, name, last_save (see below for more details)

Preprocessors:

  • Allow all requests (get_many_auth_preprocessor)
GET

/api/deployment_file/<id>

Get single deployment_file object with pk field matching param id

Included fields:
user_id, description, iscompressed, campaign_id, file_url, id, name, last_save (see below for more details)

Preprocessors:

  • Allow all requests (get_single_auth_preprocessor)
DELETE

/api/deployment_file/<id>

Delete single deployment_file object with pk field matching param id

Preprocessors:

  • Restrict request to OWNER only (delete_auth_preprocessor)
GET

/api/deployment_file/<int:fid>/data

Deployment file resource. Get the data for the file resource matching fid. This endpoint also provides options to manipulate, transform and save data to the database. The querystring takes the following form: 

?f={...}&save={...}&disposition=...&template=...
where f is a JSON dictionary containing a sequence of operations for transforming the data (see Data transformation API for more info), disposition is optional and defines the download type which can be inline (default, displays in the browser) or attachment (triggers a download) , template is optional depending on the output of the steps in f and can be used to define the export format, save is a JSON dictionary that defines batch save operations. This can be used to save the file content or the output of the operations in f to a related database model collection.

Example1: convert CSV file into serialized, nested JSON expected for media resource and batch save rows to the related deployment.media collection for this model 

/api/deployment_file/2/data?save={"collection": "deployment.media"}&f={"operations": [{"module": "pandas", "method": "read_csv", "kwargs": {"parse_dates": ["time"], "skiprows": 2, "usecols": [2, 3, 4, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15]}}, {"method": "rename", "kwargs": {"columns": {"image_filename": "key", "longitude": "pose.lon", "latitude": "pose.lat", "depth_sensor": "pose.data.dep", "altitude_sensor": "pose.alt", "depth": "pose.dep", "sea_water_temperature": "pose.data.temp", "sea_water_salinity": "pose.data.salinity", "chlorophyll_concentration_in_sea_water": "pose.data.chlorophyll", "backscattering_ratio": "pose.data.backscater", "colored_dissolved_organic_matter": "pose.data.colored_dissolved_organic_matter", "time": "timestamp_start", "cluster_tag": "pose.data.cluster_tag"}}}, {"method": "to_dict", "kwargs": {"orient": "records"}}, {"module": "data", "method": "unflatten_dicts", "kwargs": {}}]}

Example 2: similar to above, but perform an update rather than an insert. Can optinally create missing. This is slower. 

/api/deployment_file/4/data?save={"collection": "deployment.media", "update_existing": true, "match_on": ["key"], "create_missing": true}&f={"operations": [{"module": "pandas", "method": "read_csv", "kwargs": {"parse_dates": ["time"], "skiprows": 2, "usecols": [2, 3, 4, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15]}}, {"method": "rename", "kwargs": {"columns": {"image_filename": "key", "longitude": "pose.lon", "latitude": "pose.lat", "depth_sensor": "pose.data.dep", "altitude_sensor": "pose.alt", "depth": "pose.dep", "sea_water_temperature": "pose.data.temp", "sea_water_salinity": "pose.data.salinity", "chlorophyll_concentration_in_sea_water": "pose.data.chlorophyll", "backscattering_ratio": "pose.data.backscater", "colored_dissolved_organic_matter": "pose.data.colored_dissolved_organic_matter", "time": "timestamp_start", "cluster_tag": "pose.data.cluster_tag"}}}, {"method": "to_dict", "kwargs": {"orient": "records"}}, {"module": "data", "method": "unflatten_dicts", "kwargs": {}}]}
POST

/api/deployment_file/data

Save file data to database. Use this if it is not possible to dynamically link the file using the file_url or if the file_url is potentially unstable / ephemeral. This should be a multipart form post with file parameter set to the uploaded file and all other fields as in the object definition below.
MODEL COLUMNS FILTERABLE
These attributes map to database columns and can be used when building filters (for endpoints that support filtering, see Making API queries )
NAME TYPE DEFAULT NULLABLE UNIQUE PRIM_KEY FORGN_KEY DESCRIPTION
id Integer() None False None True -

Primary key id
last_save JSON() None True None - -

Sequence of file operations performed at last save
name Text() None False False - -

The name of the file (optional). Defaults to basename of either file_url or the path of the uploaded file
file_url Text() None True False - -

The URL of the file to be loaded dynamically (if data field is not set)
description Text() None True None - -

The description of the file (optional)
_rawfiledata LargeBinary() None True None - -

The raw file storage for the file. This is not directly accessible through the API
iscompressed Boolean() False True None - -

Whether or not the file is compressed or not. If so, it will be automatically decompressed upon access.
user_id Integer() None False None - users.id

None
deployment_id Integer() None False None - deployment.id

None
created_at DateTime() function False None - -

None
updated_at DateTime() function True None - -

Updated time (UTC)
RELATED MODELS FILTERABLE
These attributes expose related objects. Relations can either be single elements or a collection of elements. Related models can be used to contruct filters (for endpoints that support filtering, see Making API queries )
FIELD RELATION DIRECTION DESCRIPTION
user users MANYTOONE

None
deployment deployment MANYTOONE

None
OTHER MODEL ATTRIBUTES FILTERABLE
These are special defined attributes return dynamically processed results. These attributes do not work in filter queries.
NAME TYPE DESCRIPTION
data property

None
ENDPOINTS
METHODENDPOINT
GET

/api/group_types

Get list of group_types objects matching API query. See Making API search queries for instructions on making search queries

Preprocessors:

  • Allow all requests (get_many_auth_preprocessor)
GET

/api/group_types/<id>

Get single group_types object with pk field matching param id

Preprocessors:

  • Allow all requests (get_single_auth_preprocessor)
MODEL COLUMNS FILTERABLE
These attributes map to database columns and can be used when building filters (for endpoints that support filtering, see Making API queries )
NAME TYPE DEFAULT NULLABLE UNIQUE PRIM_KEY FORGN_KEY DESCRIPTION
id Integer() None False None True -

Primary key id
name String(length=128) None False None - -

None
ENDPOINTS
METHODENDPOINT
POST

/api/groups

Create new groups object. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • Handle group_type_name parameter and secure against membership/dataset tampering (group_data_preprocessor)

Postprocessors:

  • None (post_postprocessor)
PATCH

/api/groups/<id>

Update single groups object with pk field matching param id. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • Handle group_type_name parameter and secure against membership/dataset tampering (group_data_preprocessor)
  • Restrict request to OWNER only (patch_auth_preprocessor)
GET

/api/groups

Get list of groups objects matching API query. See Making API search queries for instructions on making search queries

Included fields:
id, name, is_public, dua_link, user, user.id, user.first_name, user.last_name, user.username, is_restricted, group_type, groupinfo, created_at, current_user_is_edit_member, current_user_is_member, current_user_is_owner, current_user_can_share_data, current_user_can_add_member, current_user_has_agreed, current_user_is_pending_approval, requires_agreement, requires_approval, member_count, pending_member_count (see below for more details)

Preprocessors:

  • Allow all requests (get_many_auth_preprocessor)
GET

/api/groups/<id>

Get single groups object with pk field matching param id

Included fields:
id, name, is_public, dua_link, user, user.id, user.first_name, user.last_name, user.username, is_restricted, group_type, groupinfo, created_at, current_user_is_edit_member, current_user_is_member, current_user_is_owner, current_user_can_share_data, current_user_can_add_member, current_user_has_agreed, current_user_is_pending_approval, requires_agreement, requires_approval, member_count, pending_member_count, description, dataset_counts (see below for more details)

Preprocessors:

  • Allow all requests (get_single_auth_preprocessor)
DELETE

/api/groups/<id>

Delete single groups object with pk field matching param id

Preprocessors:

  • Restrict request to OWNER only (delete_auth_preprocessor)
MODEL COLUMNS FILTERABLE
These attributes map to database columns and can be used when building filters (for endpoints that support filtering, see Making API queries )
NAME TYPE DEFAULT NULLABLE UNIQUE PRIM_KEY FORGN_KEY DESCRIPTION
id Integer() None False None True -

Primary key id
name String(length=128) None False None - -

Name of Group
is_public Boolean() False True None - -

Whether or not contents are publicly viewable
is_restricted Boolean() True True None - -

Whether or not members can see other member's datasets
requires_approval Boolean() True True None - -

Whether or not custodian approval is required
requires_agreement Boolean() False True None - -

Whether or not members need to agree to Data Usage Agreement (DUA)
description Text() None True None - -

Extra information about the Group
dua_link Text() None True None - -

Data Usage Agreement (DUA) link. Must be an HTTP accessible, embeddable document
user_id Integer() None True None - users.id

id of group custodian user
group_type_id Integer() None False None - group_types.id

id of related group_type
groupinfo Text() None True None - -

Shorter description / tagline of Group
created_at DateTime() function False None - -

Datetime of creation
RELATED MODELS FILTERABLE
These attributes expose related objects. Relations can either be single elements or a collection of elements. Related models can be used to contruct filters (for endpoints that support filtering, see Making API queries )
FIELD RELATION DIRECTION DESCRIPTION
user users MANYTOONE

Related user for group custodian
group_type group_types MANYTOONE

related group_type object
members users MANYTOMANY

None
usergroups usergroups ONETOMANY

None
shared_label_schemes label_scheme MANYTOMANY

None
shared_annotation_sets annotation_set MANYTOMANY

None
shared_media_collections media_collection MANYTOMANY

None
HYBRID ATTRIBUTES FILTERABLE
These are special defined attributes return dynamically processed results and support both query and instance property operations. HYBRID ATTRIBUTES can be used when building filters (for endpoints that support filtering, see Making API queries ). Note HYBRID METHODS may require input parameters.
NAME TYPE ARGS DESCRIPTION
current_user_is_owner property -

:return:
current_user_is_pending_approval property -

:return:
current_user_is_member property -

:return:
current_user_is_edit_member property -

:return:
current_user_can_share_data property -

BOOL, whether current_user has permission to share
current_user_can_add_member property -

BOOL, whether current_user has permission to share
current_user_has_agreed property -

BOOL, whether current_user has permission to share
OTHER MODEL ATTRIBUTES FILTERABLE
These are special defined attributes return dynamically processed results. These attributes do not work in filter queries.
NAME TYPE DESCRIPTION
dataset_counts method

the number of different datasets that are shared in this group
member_count method

None
pending_member_count method

None
ENDPOINTS
METHODENDPOINT
POST

/api/label

Create new label object. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • if parent_id is set, checks that nominated parent class label is valid, i.e.: that the parent_id exists, is from the same annotation scheme (label_scheme_id) and is not a circular reference to itself (witch can break things). (validate_preprocessor)
  • None (post_auth_preprocessor)
PATCH

/api/label/<id>

Update single label object with pk field matching param id. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • if parent_id is set, checks that nominated parent class label is valid, i.e.: that the parent_id exists, is from the same annotation scheme (label_scheme_id) and is not a circular reference to itself (witch can break things). (validate_preprocessor)
  • checks that the current user has permission to edit this class label. (patch_auth_preprocessor)
GET

/api/label

Get list of label objects matching API query. See Making API search queries for instructions on making search queries

Included fields:
user_id, name, color, parent_id, label_scheme_id, id, uuid, is_child, is_parent, created_at, updated_at, is_approved, origin_code, parent_origin_code, name_path, lineage (see below for more details)

Preprocessors:

  • Allow all requests (get_many_auth_preprocessor)
GET

/api/label/<id>

Get single label object with pk field matching param id

Included fields:
user_id, name, color, parent_id, label_scheme_id, id, uuid, is_child, is_parent, created_at, updated_at, is_approved, origin_code, parent_origin_code, name_path, lineage, info, info.name, info.value, info.id, tags, tags.id, tags.name, label_scheme, label_scheme.id, label_scheme.name, label_scheme.user_id, parent, parent.id, parent.name, user, user.id, user.username, user.last_login, user.first_name, user.last_name, user.active, user.info, user.role, annotation_count, descendant_count, exemplar_annotation_sets, label_scheme_custodian, current_user_can_edit, current_user_is_custodian (see below for more details)

Preprocessors:

  • Allow all requests (get_single_auth_preprocessor)
DELETE

/api/label/<id>

Delete single label object with pk field matching param id

Preprocessors:

  • checks that the class label does not have any children or annotations which may be orphaned by delete. (delete_auth_preprocessor)
DELETE

/api/label/<int:id>/tag/<int:tag_id>

None
POST

/api/label/<int:id>/tag/<int:tag_id>

None
GET

/api/label/<int:id>/exemplars

Get list of exemplar images for the label_scheme with the ID matching id. Optionally you can specify an exemplar annontation_set_id if there are more than one for this scheme. If not annotation_set_id is specified. All will be returned. :param id: :param annotation_set_id: :return:
GET

/api/label/<int:id>/exemplars/<int:annotation_set_id>

Get list of exemplar images for the label_scheme with the ID matching id. Optionally you can specify an exemplar annontation_set_id if there are more than one for this scheme. If not annotation_set_id is specified. All will be returned. :param id: :param annotation_set_id: :return:
MODEL COLUMNS FILTERABLE
These attributes map to database columns and can be used when building filters (for endpoints that support filtering, see Making API queries )
NAME TYPE DEFAULT NULLABLE UNIQUE PRIM_KEY FORGN_KEY DESCRIPTION
id Integer() None False None True -

Primary key id
uuid UUID(as_uuid=True) None True True - -

A universally unique identifier for this object
name String(length=160) None False False - -

The name of this class label
color String(length=10) function True False - -

The colour of this class label (hex code, including #)
user_id Integer() None False None - users.id

The id of the user who owns or created this class label
label_scheme_id Integer() None False None - label_scheme.id

The id of the annotation scheme (label_scheme) containing this class label
parent_id Integer() None True None - label.id

id of the parent class label
is_approved Boolean() False True None - -

Whether this class label has been approved by the custodian
created_at DateTime() function True None - -

Creation time (UTC)
updated_at TIMESTAMP() function True None - -

Updated time (UTC)
origin_code String(length=80) None True False - -

None
parent_origin_code String(length=80) None True False - -

None
RELATED MODELS FILTERABLE
These attributes expose related objects. Relations can either be single elements or a collection of elements. Related models can be used to contruct filters (for endpoints that support filtering, see Making API queries )
FIELD RELATION DIRECTION DESCRIPTION
user users MANYTOONE

The user who owns or created this class label
label_scheme label_scheme MANYTOONE

The annotation scheme containing this class label
parent label MANYTOONE

The parent class label (linked observation)
vocab_elements vocab_element MANYTOMANY

A list of vocab_elements linked to this label
children label ONETOMANY

None
label_tags label_tags ONETOMANY

None
info label_info ONETOMANY

None
label_vocab_element label_vocab_element ONETOMANY

None
annotations annotation ONETOMANY

List of related annotation objects
ASSOCIATION PROXIES FILTERABLE
These attributes map linked objects from collections (eg: many-to-many relationships that have an association table) Association proxies can be used when building filters (for endpoints that support filtering, see Making API queries )
ATTRIBUTE MODEL COLLECTION DESCRIPTION
tags tag label_tags Proxy attribute that presents the linked tag objects from the label_tags collection
HYBRID ATTRIBUTES FILTERABLE
These are special defined attributes return dynamically processed results and support both query and instance property operations. HYBRID ATTRIBUTES can be used when building filters (for endpoints that support filtering, see Making API queries ). Note HYBRID METHODS may require input parameters.
NAME TYPE ARGS DESCRIPTION
is_child property -

BOOLEAN, whether or not this class label has a parent class label
is_mapped property -

BOOLEAN, whether this label has one or more vocab_element mappings
OTHER MODEL ATTRIBUTES FILTERABLE
These are special defined attributes return dynamically processed results. These attributes do not work in filter queries.
NAME TYPE DESCRIPTION
annotation_count method

Number of annotations that have been assigned with this label
descendant_count method

Number of direct children labels nested under this label
exemplar_annotation_sets method

None
label_scheme_custodian method

None
current_user_can_edit property

None
current_user_is_custodian property

None
name_path property

None
tag_names property

Comma-delimited names of applied tags. Can also be used to set tags using comma-delimited tags when creating annotaions
translated property

Special API property returns label object in target label scheme. Requires translate query parameter containing target_label_scheme_id and optional vocab_registry_keys parameters. See Label Translation for more information.
vocab_registry property

Dictionary representation of vocab_elements by registry key (conveniently formatted for exporting schemes)
ENDPOINTS
METHODENDPOINT
POST

/api/label_info

Create new label_info object. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • Restrict request to LOGGED IN users only (post_auth_preprocessor)
PATCH

/api/label_info/<id>

Update single label_info object with pk field matching param id. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • Restrict request to OWNER only (patch_auth_preprocessor)
GET

/api/label_info

Get list of label_info objects matching API query. See Making API search queries for instructions on making search queries

Preprocessors:

  • Allow all requests (get_many_auth_preprocessor)
GET

/api/label_info/<id>

Get single label_info object with pk field matching param id

Preprocessors:

  • Allow all requests (get_single_auth_preprocessor)
DELETE

/api/label_info/<id>

Delete single label_info object with pk field matching param id

Preprocessors:

  • Restrict request to OWNER only (delete_auth_preprocessor)
MODEL COLUMNS FILTERABLE
These attributes map to database columns and can be used when building filters (for endpoints that support filtering, see Making API queries )
NAME TYPE DEFAULT NULLABLE UNIQUE PRIM_KEY FORGN_KEY DESCRIPTION
id Integer() None False None True -

Primary key id
name String(length=80) None False False - -

None
value Text() None True None - -

None
label_id Integer() None True None - label.id

None
RELATED MODELS FILTERABLE
These attributes expose related objects. Relations can either be single elements or a collection of elements. Related models can be used to contruct filters (for endpoints that support filtering, see Making API queries )
FIELD RELATION DIRECTION DESCRIPTION
label label MANYTOONE

None
ENDPOINTS
METHODENDPOINT
POST

/api/label_scheme

Create new label_scheme object. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • Restrict request to LOGGED IN users only (post_auth_preprocessor)
PATCH

/api/label_scheme/<id>

Update single label_scheme object with pk field matching param id. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • Assert object edit permission from shared usergroups. Checks current_user has edit permission. (patch_auth_preprocessor)
GET

/api/label_scheme

Get list of label_scheme objects matching API query. See Making API search queries for instructions on making search queries

Included fields:
user_id, description, is_hierarchy, id, name, user, user.username, user.first_name, user.last_name, user.id, label_scheme_files, label_scheme_files.description, label_scheme_files.file_url, label_scheme_files.id, label_scheme_files.name, current_user_can_view, current_user_is_owner, current_user_is_member, current_user_can_edit, is_public, is_child, parent_label_scheme, parent_label_scheme.id, parent_label_scheme.name, created_at, updated_at, usergroup_count, annotation_set_count, exemplar_annotation_set_count (see below for more details)

Preprocessors:

  • Assert object view permission from shared usergroups. Restricts objects to the ones that current_user can view (get_many_auth_preprocessor)
GET

/api/label_scheme/<id>

Get single label_scheme object with pk field matching param id

Included fields:
user_id, description, is_hierarchy, id, name, user, user.username, user.first_name, user.last_name, user.id, label_scheme_files, label_scheme_files.description, label_scheme_files.file_url, label_scheme_files.id, label_scheme_files.name, current_user_can_view, current_user_is_owner, current_user_is_member, current_user_can_edit, is_public, is_child, parent_label_scheme, parent_label_scheme.id, parent_label_scheme.name, created_at, updated_at, usergroup_count, annotation_set_count, exemplar_annotation_set_count, parent_label_scheme_ids (see below for more details)

Preprocessors:

  • Assert object view permission from shared usergroups. Checks current_user has view permission. (get_single_auth_preprocessor)
DELETE

/api/label_scheme/<id>

Delete single label_scheme object with pk field matching param id

Preprocessors:

  • checks that the scheme does not contain annotation sets or children. (delete_preprocessor)
  • Assert object delete permission from shared usergroups. Checks current user is owner and object is not shared in a usergroup (delete_auth_preprocessor)
POST

/api/label_scheme/<int:instance_id>/group/<int:group_id>

Add object with id instance_id to group with id group_id
DELETE

/api/label_scheme/<int:instance_id>/group/<int:group_id>

Remove resource with id instance_id from group with id group_id
PATCH

/api/label_scheme/<int:label_scheme_id>/reset_label_parents

Reset labels parents for label_scheme with id matching label_scheme_id. Uses origin_code and parent_origin_code to match up labels. Accepts optional query string argument replace_existing=true, which will reset parent_ids for labels that are already set. By default this is set to false
GET

/api/label_scheme/<int:label_scheme_id>/export

Export labels collection from label_scheme matching id. Search queries are executed on the label model.

Querystring parameters are:

?q={...}&f={...}&disposition=...&template=...&include_columns=[...]

Where q is a JSON search query (see Making API search queries) on the collection model, where f is a JSON dictionary containing a sequence of operations for transforming the data (see Data transformation API for more info), disposition defines the download type which can be attachment (default, triggers a download) or inline (displays in the browser), template is optional depending on the output of the steps in f and can be used to define the export format, include_columns is a JSON list of column fields for the exported model. Nested fields for related models delimited with a . If include_columns is omitted, all allowed columns will be returned.

Metadata for the annotation_set matching id is also returned in the response. Depending on the output format, this could be as part of the response body in a metadata field or in the response headers with the key X-Content-Metadata.

Allowed fields include:

id, parent_id, uuid, name, color, user.id, user.full_name, label_scheme.id, label_scheme.name, lineage_names, is_approved, tags, vocab_registry, created_at, updated_at, origin_code, parent_origin_code, is_mapped

See label model columns, relations and attributes for more information on each of the included fields.

TRANSLATING TO OTHER LABEL_SCHEMES

This endpoint also supports the translation of labels from a source to a target label_scheme. another label_scheme using the semantic translation framework. In order to do this, you need to specify the additional translate url query parameter:

&translate={"target_label_scheme_id":..., "vocab_registry_keys": ..., "mapping_override": ...}
Where target_label_scheme_id [required] is an INT with the id of the target label scheme, vocab_registry_keys [optional] is a list containing the priority order of keys for vocab_registries for which to perform the semantic translation and mapping_override defines a set of key-value pairs containing source label.id : target label.id for which to override the translation. Note: for extended schemes, labels are translated through tree_traversal and no semantic translation is required.

NOTE: you also need to add the translated.* columns to obtain the translation output. These columns are ignored if no translate query parameter is supplied.

EXAMPLES

# Example1: get all columns as an HTML table in the browser (including all labels from base scheme)
/api/label_scheme/7/export?template=data.html&disposition=inline
# Example2: get all columns as a downloaded CSV file (including all labels from base scheme)
/api/label_scheme/7/export?template=data.csv&disposition=inline
# Example3: get all columns as an HTML table in the browser, but only for labels defined in the extended scheme (not the base scheme)
/api/label_scheme/7/export?template=data.html&disposition=inline&q={"filters":[{"name":"label_scheme_id","op":"eq","val":7}]}
# Example4: get translation lookup between schemes, and only return specific columns
/api/label_scheme/8/export?disposition=inline&translate={"vocab_registry_keys":["worms","caab","catami"],"target_label_scheme_id":"7"}
  &include_columns=["label_scheme.name","lineage_names","name","id","translated.id","translated.name","translated.lineage_names",
  "translated.translation_info","translated.label_scheme.name"]
# MORE TO COME... Need something else or an example added here, please ask...
GET

/api/label_scheme/<int:label_scheme_id>/labels

None
GET

/api/label_scheme/<int:label_scheme_id>/labels/<int:label_parent_id>

None
MODEL COLUMNS FILTERABLE
These attributes map to database columns and can be used when building filters (for endpoints that support filtering, see Making API queries )
NAME TYPE DEFAULT NULLABLE UNIQUE PRIM_KEY FORGN_KEY DESCRIPTION
id Integer() None False None True -

Primary key id
name String(length=80) None False False - -

None
description Text() None True None - -

None
user_id Integer() None False None - users.id

Foreign key reference for ID of related owner users model
is_hierarchy Boolean() False True None - -

None
created_at DateTime() function True None - -

Creation time (UTC)
updated_at TIMESTAMP() function True None - -

Updated time (UTC)
parent_label_scheme_id Integer() None True None - label_scheme.id

None
RELATED MODELS FILTERABLE
These attributes expose related objects. Relations can either be single elements or a collection of elements. Related models can be used to contruct filters (for endpoints that support filtering, see Making API queries )
FIELD RELATION DIRECTION DESCRIPTION
user users MANYTOONE

Related owner users model
parent_label_scheme label_scheme MANYTOONE

None
annotation_sets annotation_set ONETOMANY

None
usergroups groups MANYTOMANY

List of groups objects that contain this resource
label_scheme_files label_scheme_file ONETOMANY

None
children label_scheme ONETOMANY

None
labels label ONETOMANY

None
HYBRID ATTRIBUTES FILTERABLE
These are special defined attributes return dynamically processed results and support both query and instance property operations. HYBRID ATTRIBUTES can be used when building filters (for endpoints that support filtering, see Making API queries ). Note HYBRID METHODS may require input parameters.
NAME TYPE ARGS DESCRIPTION
is_child property -

BOOLEAN, whether or not this class label has a parent class label
is_public property -

Whether or not this object is public (i.e. shared in a public group)
current_user_is_owner property -

Whether or not the currently logged in user is the owner of this object
current_user_is_member property -

Whether or not the current logged in user is a member of a group that includes this object
current_user_is_edit_member property -

Whether or not the current logged in user is a member with edit permission of a group that includes this object
current_user_can_view property -

Whether or not the current user has permission to view this object
current_user_can_edit property -

Whether or not the current logged in user has edit permission (owner or edit_member)
OTHER MODEL ATTRIBUTES FILTERABLE
These are special defined attributes return dynamically processed results. These attributes do not work in filter queries.
NAME TYPE DESCRIPTION
annotation_set_count method

None
exemplar_annotation_set_count method

None
label_count method

None
usergroup_count method

None
ENDPOINTS
METHODENDPOINT
POST

/api/label_scheme_file

Create new label_scheme_file object. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • Restrict request to LOGGED IN users only (post_auth_preprocessor)
PATCH

/api/label_scheme_file/<id>

Update single label_scheme_file object with pk field matching param id. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • Restrict request to OWNER only (patch_auth_preprocessor)
GET

/api/label_scheme_file

Get list of label_scheme_file objects matching API query. See Making API search queries for instructions on making search queries

Included fields:
description, iscompressed, label_scheme, file_url, label_scheme_id, id, name, last_save (see below for more details)

Preprocessors:

  • Allow all requests (get_many_auth_preprocessor)
GET

/api/label_scheme_file/<id>

Get single label_scheme_file object with pk field matching param id

Included fields:
description, iscompressed, label_scheme, file_url, label_scheme_id, id, name, last_save (see below for more details)

Preprocessors:

  • Allow all requests (get_single_auth_preprocessor)
DELETE

/api/label_scheme_file/<id>

Delete single label_scheme_file object with pk field matching param id

Preprocessors:

  • Restrict request to OWNER only (delete_auth_preprocessor)
GET

/api/label_scheme_file/<int:fid>/data

Get the data for the file resource matching fid. This endpoint also provides options to manipulate, transform and save data to the database. The querystring takes the following form: 

?f={...}&save={...}&disposition=...&template=...
where f is a JSON dictionary containing a sequence of operations for transforming the data (see Data transformation API for more info), disposition is optional and defines the download type which can be inline (default, displays in the browser) or attachment (triggers a download) , template is optional depending on the output of the steps in f and can be used to define the export format, save is a JSON dictionary that defines batch save operations. This can be used to save the file content or the output of the operations in f to a related database model collection.
POST

/api/label_scheme_file/data

Save file data to database. Use this if it is not possible to dynamically link the file using the file_url or if the file_url is potentially unstable / ephemeral. This should be a multipart form post with file parameter set to the uploaded file and all other fields as in the object definition below.
MODEL COLUMNS FILTERABLE
These attributes map to database columns and can be used when building filters (for endpoints that support filtering, see Making API queries )
NAME TYPE DEFAULT NULLABLE UNIQUE PRIM_KEY FORGN_KEY DESCRIPTION
id Integer() None False None True -

Primary key id
last_save JSON() None True None - -

Sequence of file operations performed at last save
name Text() None False False - -

The name of the file (optional). Defaults to basename of either file_url or the path of the uploaded file
file_url Text() None True False - -

The URL of the file to be loaded dynamically (if data field is not set)
description Text() None True None - -

The description of the file (optional)
_rawfiledata LargeBinary() None True None - -

The raw file storage for the file. This is not directly accessible through the API
iscompressed Boolean() False True None - -

Whether or not the file is compressed or not. If so, it will be automatically decompressed upon access.
label_scheme_id Integer() None False None - label_scheme.id

None
RELATED MODELS FILTERABLE
These attributes expose related objects. Relations can either be single elements or a collection of elements. Related models can be used to contruct filters (for endpoints that support filtering, see Making API queries )
FIELD RELATION DIRECTION DESCRIPTION
label_scheme label_scheme MANYTOONE

None
OTHER MODEL ATTRIBUTES FILTERABLE
These are special defined attributes return dynamically processed results. These attributes do not work in filter queries.
NAME TYPE DESCRIPTION
data property

None
ENDPOINTS
METHODENDPOINT
POST

/api/label_tags

Create new label_tags object. Expects JSON. Fields shown in MODEL COLUMNS below. A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance's class are allowed. These could be, for example, any mapped columns or relationships.

Preprocessors:

  • Restrict request to LOGGED IN users only (post_auth_preprocessor)
PATCH

/api/label_tags/<label_id>

Update single label_tags object with pk field matching param label_id. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • Restrict request to OWNER only (patch_auth_preprocessor)
GET

/api/label_tags

Get list of label_tags objects matching API query. See Making API search queries for instructions on making search queries

Preprocessors:

  • Allow all requests (get_many_auth_preprocessor)
GET

/api/label_tags/<label_id>

Get single label_tags object with pk field matching param label_id

Preprocessors:

  • Allow all requests (get_single_auth_preprocessor)
DELETE

/api/label_tags/<label_id>

Delete single label_tags object with pk field matching param label_id

Preprocessors:

  • Restrict request to OWNER only (delete_auth_preprocessor)
MODEL COLUMNS FILTERABLE
These attributes map to database columns and can be used when building filters (for endpoints that support filtering, see Making API queries )
NAME TYPE DEFAULT NULLABLE UNIQUE PRIM_KEY FORGN_KEY DESCRIPTION
label_id Integer() None False None True label.id

None
tag_id Integer() None False None True tag.id

None
assoc_created_at DateTime() function True None - -

None
RELATED MODELS FILTERABLE
These attributes expose related objects. Relations can either be single elements or a collection of elements. Related models can be used to contruct filters (for endpoints that support filtering, see Making API queries )
FIELD RELATION DIRECTION DESCRIPTION
label label MANYTOONE

None
tag tag MANYTOONE

None
ENDPOINTS
METHODENDPOINT
POST

/api/maplayer

Create new maplayer object. Expects JSON. Fields shown in MODEL COLUMNS below. A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance's class are allowed. These could be, for example, any mapped columns or relationships.

Preprocessors:

  • Restrict request to ADMIN user only (assert_current_user_is_admin)
  • Restrict request to LOGGED IN users only (post_auth_preprocessor)
PATCH

/api/maplayer/<id>

Update single maplayer object with pk field matching param id. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • Restrict request to ADMIN user only (assert_current_user_is_admin)
  • Restrict request to OWNER only (patch_auth_preprocessor)
GET

/api/maplayer

Get list of maplayer objects matching API query. See Making API search queries for instructions on making search queries

Preprocessors:

  • Allow all requests (get_many_auth_preprocessor)
GET

/api/maplayer/<id>

Get single maplayer object with pk field matching param id

Preprocessors:

  • Allow all requests (get_single_auth_preprocessor)
DELETE

/api/maplayer/<id>

Delete single maplayer object with pk field matching param id

Preprocessors:

  • Restrict request to ADMIN user only (assert_current_user_is_admin)
  • Restrict request to OWNER only (delete_auth_preprocessor)
MODEL COLUMNS FILTERABLE
These attributes map to database columns and can be used when building filters (for endpoints that support filtering, see Making API queries )
NAME TYPE DEFAULT NULLABLE UNIQUE PRIM_KEY FORGN_KEY DESCRIPTION
id Integer() None False None True -

Primary key id
name String(length=255) None False None - -

None
baseurl String(length=255) None False None - -

None
layertype String(length=128) None False None - -

None
properties JSON(astext_type=Text()) None True None - -

None
filters JSON(astext_type=Text()) None True None - -

None
is_active Boolean() False True None - -

None
disabled Boolean() False True None - -

None
maplayer_group_id Integer() None False None - maplayer_group.id

None
RELATED MODELS FILTERABLE
These attributes expose related objects. Relations can either be single elements or a collection of elements. Related models can be used to contruct filters (for endpoints that support filtering, see Making API queries )
FIELD RELATION DIRECTION DESCRIPTION
maplayer_group maplayer_group MANYTOONE

None
ENDPOINTS
METHODENDPOINT
POST

/api/maplayer_group

Create new maplayer_group object. Expects JSON. Fields shown in MODEL COLUMNS below. A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance's class are allowed. These could be, for example, any mapped columns or relationships.

Preprocessors:

  • Restrict request to ADMIN user only (assert_current_user_is_admin)
  • Restrict request to LOGGED IN users only (post_auth_preprocessor)
PATCH

/api/maplayer_group/<id>

Update single maplayer_group object with pk field matching param id. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • Restrict request to ADMIN user only (assert_current_user_is_admin)
  • Restrict request to OWNER only (patch_auth_preprocessor)
GET

/api/maplayer_group

Get list of maplayer_group objects matching API query. See Making API search queries for instructions on making search queries

Preprocessors:

  • Allow all requests (get_many_auth_preprocessor)
GET

/api/maplayer_group/<id>

Get single maplayer_group object with pk field matching param id

Preprocessors:

  • Allow all requests (get_single_auth_preprocessor)
DELETE

/api/maplayer_group/<id>

Delete single maplayer_group object with pk field matching param id

Preprocessors:

  • Restrict request to ADMIN user only (assert_current_user_is_admin)
  • Restrict request to OWNER only (delete_auth_preprocessor)
MODEL COLUMNS FILTERABLE
These attributes map to database columns and can be used when building filters (for endpoints that support filtering, see Making API queries )
NAME TYPE DEFAULT NULLABLE UNIQUE PRIM_KEY FORGN_KEY DESCRIPTION
id Integer() None False None True -

Primary key id
name String(length=255) None False None - -

None
pane String(length=255) None True None - -

None
zindex Integer() None False None - -

None
RELATED MODELS FILTERABLE
These attributes expose related objects. Relations can either be single elements or a collection of elements. Related models can be used to contruct filters (for endpoints that support filtering, see Making API queries )
FIELD RELATION DIRECTION DESCRIPTION
maplayers maplayer ONETOMANY

None
ENDPOINTS
METHODENDPOINT
PATCH

/api/media/<id>

Update single media object with pk field matching param id. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • Restrict request to object OWNER only (patch_auth_preprocessor)

Postprocessors:

  • Clears the request cache object for this resource (to cause cache refresh on next request) (_clear_cache)
GET

/api/media

Get list of media objects matching API query. See Making API search queries for instructions on making search queries

Included fields:
created_at, timestamp_start, is_valid, key, deployment, deployment.id, deployment.key, campaign, campaign.id, campaign.key, deployment_id, data, id, media_type, media_type.id, media_type.name, path_best, path_best_thm (see below for more details)

Preprocessors:

  • Allow all requests (get_many_auth_preprocessor)
GET

/api/media/<id>

Get single media object with pk field matching param id

Included fields:
created_at, timestamp_start, is_valid, key, deployment, deployment.id, deployment.key, campaign, campaign.id, campaign.key, deployment_id, data, id, media_type, media_type.id, media_type.name, path_best, path_best_thm, current_user_can_edit (see below for more details)

Preprocessors:

  • Allow all requests (get_single_auth_preprocessor)

Postprocessors:

  • None (get_single_postprocessor)
DELETE

/api/media/<id>

Delete single media object with pk field matching param id

Preprocessors:

  • None (delete_auth_preprocessor)
GET

/api/media/<int:media_id>/annotations/<int:annotation_set_id>

None
POST

/api/media/save

Media UPLOAD resource.

Used to upload Media to predefined location set out in server config file.

file: file data input containing image file to upload. json: json string containing parameters for new media item
POST

/api/media

In addition to the MODEL COLUMNS below, the JSON body can contain the following parameters: pose: a dict containing parameters for a single pose including associated pose data, poses: a list of dicts as above if linking multiple poses to a single media object (eg: video), media_type: OPTIONAL (default="image"), a string containing the media_type name.

Here are some example payloads for creating media objects: 

# example JSON payload for media item with a single pose (eg: still image)
{
    "pose": {"lat":-35.53153264, "lon":150.43962917, "alt":3.558, "dep":28.85, "data":[
        {"name":"temperature","value":16.602},
        {"name":"salinity","value":35.260222}
    ]},
    "key": "PR_20101117_002241_698_LC16",
    "deployment_id": 5,
    "timestamp_start": "2018-06-07T00:47:17.273514"
}
# Same as above, but with dict data
{
    "pose": {"lat":-35.53153264, "lon":150.43962917, "alt":3.558, "dep":28.85, "data":{
        "temperature":16.602,
        "salinity":35.260222
    }},
    "key": "TEST_20101117_002241_698_LC16",
    "deployment_id": 13170,
    "timestamp_start": "2018-06-07T00:47:17.273514"
}
# To add multiple poses to a media object (i.e. video)
{
    "poses":
        [{
            "timestamp": "2018-06-07T00:47:17.273517",
            "lat":-35.53153264,
            "lon":150.43962917,
            "alt":3.558,
            "dep":28.85,
            "data":{
                "temperature":16.602,
                "salinity":35.260222
            }
        },{
            "timestamp": "2018-06-07T00:47:18.273517",
            "lat":-35.531532654,
            "lon":150.439629345,
            "alt":6.558,
            "dep":29.85,
            "data":{
                "temperature":16.602,
                "salinity":35.260222
            }
        },{
            "timestamp": "2018-06-07T00:47:19.273517",
            "lat":-35.531534564,
            "lon":150.43962934,
            "alt":4.558,
            "dep":28.85,
            "data":{
                "temperature":16.60256,
                "salinity":35.260234
            }
        }],
    "key": "KEY_OF_VIDEO_FILE_NAME",
    "deployment_id": 13170,
    "timestamp_start": "2018-06-07T00:47:17.273514",
    "media_type": "rawvideo"
}
GET

/api/media/<int:id>/poses

The list of pose for the media item matching id. For still images, it will normally just be a single pose, but video-like media_types can have more.
GET

/api/media/<int:id>/thumbnail

Dynamically create thumbnail.

If user is logged in, then they can request different sizes
GET

/api/media/<int:id>/download

Download media object with associated metadata as a zip file
MODEL COLUMNS FILTERABLE
These attributes map to database columns and can be used when building filters (for endpoints that support filtering, see Making API queries )
NAME TYPE DEFAULT NULLABLE UNIQUE PRIM_KEY FORGN_KEY DESCRIPTION
id Integer() None False None True -

Primary key id
data JSON() {} True None - -

Text field containing JSON properties for this resource
key String(length=128) None False None - -

None
path Text() None True None - -

None
path_thm Text() None True None - -

None
is_valid Boolean() True True None - -

None
deployment_id Integer() None False None - deployment.id

None
media_type_id Integer() None False None - media_type.id

None
timestamp_start DateTime() function True None - -

None
created_at DateTime() function True None - -

None
parent_id Integer() None True None - media.id

None
RELATED MODELS FILTERABLE
These attributes expose related objects. Relations can either be single elements or a collection of elements. Related models can be used to contruct filters (for endpoints that support filtering, see Making API queries )
FIELD RELATION DIRECTION DESCRIPTION
deployment deployment MANYTOONE

None
media_type media_type MANYTOONE

None
parent media MANYTOONE

None
annotations point ONETOMANY

List of point objects
poses pose ONETOMANY

None
children media ONETOMANY

None
media_collection_media media_collection_media ONETOMANY

None
events deployment_event ONETOMANY

None
ASSOCIATION PROXIES FILTERABLE
These attributes map linked objects from collections (eg: many-to-many relationships that have an association table) Association proxies can be used when building filters (for endpoints that support filtering, see Making API queries )
ATTRIBUTE MODEL COLLECTION DESCRIPTION
media_collections media_collection media_collection_media Proxy attribute that presents the linked media_collection objects from the media_collection_media collection
HYBRID ATTRIBUTES FILTERABLE
These are special defined attributes return dynamically processed results and support both query and instance property operations. HYBRID ATTRIBUTES can be used when building filters (for endpoints that support filtering, see Making API queries ). Note HYBRID METHODS may require input parameters.
NAME TYPE ARGS DESCRIPTION
geom property -

None
is_child property -

BOOLEAN, whether or not this has a parent
has_unlabeled_annotations method annotation_set_id

BOOL, whether or not the media object contains unlabeled annotations from the annotation_set with the id annotation_set_id
has_points method annotation_set_id

BOOL, whether or not the media object contains points from the annotation_set with the id annotation_set_id
has_annotations method annotation_set_id

BOOL, whether or not the media object contains any annotations from the annotation_set with the id annotation_set_id
distance method lat, lon

FLOAT, distance (in meters) of closest linked pose relative to lat and lon (which are both in decimal degrees)
timestamp_proximity method ts

Absolute difference in seconds of the in-situ timestamp and input ts, which is datetime string eg: "2020-09-25T00:57:11.945009" (or in a format that is parsable by dateutil.parser.parse)
OTHER MODEL ATTRIBUTES FILTERABLE
These are special defined attributes return dynamically processed results. These attributes do not work in filter queries.
NAME TYPE DESCRIPTION
current_user_can_edit method

Whether or not the current user owns the deployment and can edit this media item
event_log method

None
color property

None
path_best property

None
path_best_thm property

None
pixel_height property

Height of media item in pixels. Not implemented yet...
pixel_width property

Width of media item in pixels. Not implemented yet...
pose property

The first pose from related poses or if child media item, it gets the closest matching pose from the parent_media item based on timestamp_start
timestamp_start_local property

LOCAL datetime, converted using pose.lat, pose.lon and timestamp_start
ENDPOINTS
METHODENDPOINT
POST

/api/media_collection

Create new media_collection object. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • Restrict request to LOGGED IN users only (post_auth_preprocessor)
PATCH

/api/media_collection/<id>

Update single media_collection object with pk field matching param id. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • Assert object edit permission from shared usergroups. Checks current_user has edit permission. (patch_auth_preprocessor)
GET

/api/media_collection

Get list of media_collection objects matching API query. See Making API search queries for instructions on making search queries

Included fields:
id, name, parent_collection_id, description, user, created_at, user.id, user.first_name, user.last_name, user.username, current_user_can_view, current_user_is_owner, current_user_is_member, current_user_can_edit, is_public, usergroup_count (see below for more details)

Preprocessors:

  • Assert object view permission from shared usergroups. Restricts objects to the ones that current_user can view (get_many_auth_preprocessor)
GET

/api/media_collection/<id>

Get single media_collection object with pk field matching param id

Included fields:
id, name, parent_collection_id, description, user, created_at, user.id, user.first_name, user.last_name, user.username, current_user_can_view, current_user_is_owner, current_user_is_member, current_user_can_edit, is_public, usergroup_count, media_count, data, extent (see below for more details)

Preprocessors:

  • Assert object view permission from shared usergroups. Checks current_user has view permission. (get_single_auth_preprocessor)
DELETE

/api/media_collection/<id>

Delete single media_collection object with pk field matching param id

Preprocessors:

  • Assert object delete permission from shared usergroups. Checks current user is owner and object is not shared in a usergroup (delete_auth_preprocessor)
POST

/api/media_collection/<int:instance_id>/group/<int:group_id>

Add instance with ID of instance_id to the group with the ID group_id
DELETE

/api/media_collection/<int:instance_id>/group/<int:group_id>

Remove instance with ID of instance_id from the group with the ID group_id
GET

/api/media_collection/<int:id>/export

Export media collection from media_collection matching id. Search queries are executed on the media model.

Querystring parameters are:

?q={...}&f={...}&disposition=...&template=...&include_columns=[...]

Where q is a JSON search query (see Making API search queries) on the collection model, where f is a JSON dictionary containing a sequence of operations for transforming the data (see Data transformation API for more info), disposition defines the download type which can be attachment (default, triggers a download) or inline (displays in the browser), template is optional depending on the output of the steps in f and can be used to define the export format, include_columns is a JSON list of column fields for the exported model. Nested fields for related models delimited with a . If include_columns is omitted, all allowed columns will be returned.

Metadata for the annotation_set matching id is also returned in the response. Depending on the output format, this could be as part of the response body in a metadata field or in the response headers with the key X-Content-Metadata.

Allowed columns include: id, key, timestamp_start, path_best, path_best_thm, pose.timestamp, pose.lat, pose.lon, pose.alt, pose.dep, pose.data, pose.id, deployment.key, deployment.campaign.key, deployment.id, deployment.campaign.id, event_log

# Example1:
/api/media_collection/1776/export?template=dataframe.csv&f={"operations": [{"module": "pandas", "method": "json_normalize"}]}

NB: the UI contains an "ADVANCED" option which can help build more complex export queries.
GET

/api/media_collection/<int:media_collection_id>/media

Get list of media objects contained in the media_collection with an ID matching media_collection_id. Accepts search query parameters. See Making API search queries for instructions on making search queries
POST

/api/media_collection/<int:media_collection_id>/media

Add media objects matching the search query defined in the json post parameter q to the media_collection with an ID matching media_collection_id. q is a search query in the format defined in Making API search queries section and is sent as either a URL parameter or form post parameter. Request returns the corresponding media_collection.
GET

/api/media_collection/<int:media_collection_id>/media/<int:media_id>

Get the single media object with the ID media_id from the media_collection with the ID media_collection_id
POST

/api/media_collection/<int:media_collection_id>/media/<int:media_id>

Add the media object with the ID media_id to the media_collection with the ID media_collection_id
DELETE

/api/media_collection/<int:media_collection_id>/media/<int:media_id>

Remove the media object with the ID media_id from the media_collection with the ID media_collection_id
MODEL COLUMNS FILTERABLE
These attributes map to database columns and can be used when building filters (for endpoints that support filtering, see Making API queries )
NAME TYPE DEFAULT NULLABLE UNIQUE PRIM_KEY FORGN_KEY DESCRIPTION
id Integer() None False None True -

Primary key id
data JSON() {} True None - -

Text field containing JSON properties for this resource
name String(length=80) None False None - -

The name of the media_collection
description Text() None True None - -

A concise description of the media_collection
parent_collection_id Integer() None True None - media_collection.id

A reference to the ID of a parent media_collection
created_at DateTime() function False None - -

The creation date-time
user_id Integer() None True None - users.id

Foreign key reference for ID of related owner users model
RELATED MODELS FILTERABLE
These attributes expose related objects. Relations can either be single elements or a collection of elements. Related models can be used to contruct filters (for endpoints that support filtering, see Making API queries )
FIELD RELATION DIRECTION DESCRIPTION
parent media_collection MANYTOONE

The parent media_collection instance
media media MANYTOMANY

A list of media contained in this media_collection
user users MANYTOONE

Related owner users model
usergroups groups MANYTOMANY

List of groups objects that contain this resource
annotation_sets annotation_set ONETOMANY

None
children media_collection ONETOMANY

A list of childen media_collections that belong to this one
media_collection_media media_collection_media ONETOMANY

None
HYBRID ATTRIBUTES FILTERABLE
These are special defined attributes return dynamically processed results and support both query and instance property operations. HYBRID ATTRIBUTES can be used when building filters (for endpoints that support filtering, see Making API queries ). Note HYBRID METHODS may require input parameters.
NAME TYPE ARGS DESCRIPTION
media_count property -

Number of Media objects in this MediaCollection
is_public property -

Whether or not this object is public (i.e. shared in a public group)
current_user_is_owner property -

Whether or not the currently logged in user is the owner of this object
current_user_is_member property -

Whether or not the current logged in user is a member of a group that includes this object
current_user_is_edit_member property -

Whether or not the current logged in user is a member with edit permission of a group that includes this object
current_user_can_view property -

Whether or not the current user has permission to view this object
current_user_can_edit property -

Whether or not the current logged in user has edit permission (owner or edit_member)
OTHER MODEL ATTRIBUTES FILTERABLE
These are special defined attributes return dynamically processed results. These attributes do not work in filter queries.
NAME TYPE DESCRIPTION
extent method

Compute spatial extent of Media Collection :return: list with format [[SW_LAT, SW_LON],[NE_LAT,NE_LON]]
usergroup_count method

None
ENDPOINTS
METHODENDPOINT
POST

/api/media_collection_media

Create new media_collection_media object. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • None (edit_auth_preprocessor)
  • Restrict request to LOGGED IN users only (post_auth_preprocessor)
GET

/api/media_collection_media

Get list of media_collection_media objects matching API query. See Making API search queries for instructions on making search queries

Included fields:
created_at, media_id, media_collection_id (see below for more details)

Preprocessors:

  • Allow all requests (get_many_auth_preprocessor)
GET

/api/media_collection_media/<media_collection_id>

Get single media_collection_media object with pk field matching param media_collection_id

Included fields:
created_at, media_id, media_collection_id (see below for more details)

Preprocessors:

  • Allow all requests (get_single_auth_preprocessor)
DELETE

/api/media_collection_media/<media_collection_id>

Delete single media_collection_media object with pk field matching param media_collection_id

Preprocessors:

  • None (edit_auth_preprocessor)
  • Restrict request to OWNER only (delete_auth_preprocessor)
MODEL COLUMNS FILTERABLE
These attributes map to database columns and can be used when building filters (for endpoints that support filtering, see Making API queries )
NAME TYPE DEFAULT NULLABLE UNIQUE PRIM_KEY FORGN_KEY DESCRIPTION
media_id Integer() None False None True media.id

None
media_collection_id Integer() None False None True media_collection.id

None
created_at DateTime() function False None - -

None
RELATED MODELS FILTERABLE
These attributes expose related objects. Relations can either be single elements or a collection of elements. Related models can be used to contruct filters (for endpoints that support filtering, see Making API queries )
FIELD RELATION DIRECTION DESCRIPTION
media media MANYTOONE

None
media_collection media_collection MANYTOONE

None
ENDPOINTS
METHODENDPOINT
POST

/api/media_type

Create new media_type object. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • Restrict request to ADMIN user only (assert_current_user_is_admin)
  • Restrict request to LOGGED IN users only (post_auth_preprocessor)
GET

/api/media_type

Get list of media_type objects matching API query. See Making API search queries for instructions on making search queries

Included fields:
id, name (see below for more details)

Preprocessors:

  • Allow all requests (get_many_auth_preprocessor)
GET

/api/media_type/<id>

Get single media_type object with pk field matching param id

Included fields:
id, name (see below for more details)

Preprocessors:

  • Allow all requests (get_single_auth_preprocessor)
DELETE

/api/media_type/<id>

Delete single media_type object with pk field matching param id

Preprocessors:

  • Restrict request to ADMIN user only (assert_current_user_is_admin)
  • Restrict request to OWNER only (delete_auth_preprocessor)
MODEL COLUMNS FILTERABLE
These attributes map to database columns and can be used when building filters (for endpoints that support filtering, see Making API queries )
NAME TYPE DEFAULT NULLABLE UNIQUE PRIM_KEY FORGN_KEY DESCRIPTION
id Integer() None False None True -

Primary key id
name String(length=80) None False None - -

The name of the media type
RELATED MODELS FILTERABLE
These attributes expose related objects. Relations can either be single elements or a collection of elements. Related models can be used to contruct filters (for endpoints that support filtering, see Making API queries )
FIELD RELATION DIRECTION DESCRIPTION
media media ONETOMANY

None
ENDPOINTS
METHODENDPOINT
POST

/api/platform

Create new platform object. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • Restrict request to ADMIN user only (assert_current_user_is_admin)
  • Restrict request to LOGGED IN users only (post_auth_preprocessor)
PATCH

/api/platform/<id>

Update single platform object with pk field matching param id. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • Restrict request to ADMIN user only (assert_current_user_is_admin)
  • Restrict request to OWNER only (patch_auth_preprocessor)
GET

/api/platform

Get list of platform objects matching API query. See Making API search queries for instructions on making search queries

Included fields:
created_at, description, id, name, reference, user_id (see below for more details)

Preprocessors:

  • Allow all requests (get_many_auth_preprocessor)
GET

/api/platform/<id>

Get single platform object with pk field matching param id

Included fields:
created_at, description, id, name, reference, user_id, datasources, data (see below for more details)

Preprocessors:

  • Allow all requests (get_single_auth_preprocessor)
DELETE

/api/platform/<id>

Delete single platform object with pk field matching param id

Preprocessors:

  • Restrict request to ADMIN user only (assert_current_user_is_admin)
  • Restrict request to OWNER only (delete_auth_preprocessor)
MODEL COLUMNS FILTERABLE
These attributes map to database columns and can be used when building filters (for endpoints that support filtering, see Making API queries )
NAME TYPE DEFAULT NULLABLE UNIQUE PRIM_KEY FORGN_KEY DESCRIPTION
id Integer() None False None True -

Primary key id
data JSON() {} True None - -

Text field containing JSON properties for this resource
name String(length=80) None False None - -

None
key String(length=80) None False True - -

None
description Text() None True None - -

None
reference Text() None True None - -

None
user_id Integer() None True None - users.id

None
created_at DateTime() function False None - -

None
RELATED MODELS FILTERABLE
These attributes expose related objects. Relations can either be single elements or a collection of elements. Related models can be used to contruct filters (for endpoints that support filtering, see Making API queries )
FIELD RELATION DIRECTION DESCRIPTION
user users MANYTOONE

None
deployments deployment ONETOMANY

None
datasources datasource ONETOMANY

None
layers platform_maplayer ONETOMANY

None
OTHER MODEL ATTRIBUTES FILTERABLE
These are special defined attributes return dynamically processed results. These attributes do not work in filter queries.
NAME TYPE DESCRIPTION
current_user_is_owner method

None
ENDPOINTS
METHODENDPOINT
POST

/api/platform_maplayer

Create new platform_maplayer object. Expects JSON. Fields shown in MODEL COLUMNS below. A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance's class are allowed. These could be, for example, any mapped columns or relationships.

Preprocessors:

  • Restrict request to ADMIN user only (assert_current_user_is_admin)
  • Restrict request to LOGGED IN users only (post_auth_preprocessor)
PATCH

/api/platform_maplayer/<id>

Update single platform_maplayer object with pk field matching param id. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • Restrict request to ADMIN user only (assert_current_user_is_admin)
  • Restrict request to OWNER only (patch_auth_preprocessor)
GET

/api/platform_maplayer

Get list of platform_maplayer objects matching API query. See Making API search queries for instructions on making search queries

Included fields:
id, name, baseurl, layertype, minzoom, properties, platform, platform.id, platform.name, platform.key, platform.description (see below for more details)

Preprocessors:

  • Allow all requests (get_many_auth_preprocessor)
GET

/api/platform_maplayer/<id>

Get single platform_maplayer object with pk field matching param id

Included fields:
id, name, baseurl, layertype, minzoom, properties, platform, platform.id, platform.name, platform.key, platform.description (see below for more details)

Preprocessors:

  • Allow all requests (get_single_auth_preprocessor)
DELETE

/api/platform_maplayer/<id>

Delete single platform_maplayer object with pk field matching param id

Preprocessors:

  • Restrict request to ADMIN user only (assert_current_user_is_admin)
  • Restrict request to OWNER only (delete_auth_preprocessor)
MODEL COLUMNS FILTERABLE
These attributes map to database columns and can be used when building filters (for endpoints that support filtering, see Making API queries )
NAME TYPE DEFAULT NULLABLE UNIQUE PRIM_KEY FORGN_KEY DESCRIPTION
id Integer() None False None True -

Primary key id
name String(length=255) None False None - -

None
baseurl String(length=255) None False None - -

None
layertype String(length=128) None False None - -

None
minzoom Integer() None True None - -

None
properties JSON(astext_type=Text()) None True None - -

None
platform_id Integer() None True None - platform.id

None
RELATED MODELS FILTERABLE
These attributes expose related objects. Relations can either be single elements or a collection of elements. Related models can be used to contruct filters (for endpoints that support filtering, see Making API queries )
FIELD RELATION DIRECTION DESCRIPTION
platform platform MANYTOONE

None
ENDPOINTS
METHODENDPOINT
PATCH

/api/point/<id>

Update single point object with pk field matching param id. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • Enforce implied permissions from parent annotation_set (patch_auth_preprocessor)
GET

/api/point

Get list of point objects matching API query. See Making API search queries for instructions on making search queries

Included fields:
media_id, annotation_set_id, t, x, y, supplementary_annotations, data, id, timestamp, annotations, annotations.id, annotations.annotation_set_id, updated_at, is_targeted, has_polygon (see below for more details)

Preprocessors:

  • Filter results based on permissions from parent annotation_set (get_many_auth_preprocessor)
GET

/api/point/<id>

Get single point object with pk field matching param id

Included fields:
media_id, annotation_set_id, t, x, y, supplementary_annotations, data, id, timestamp, annotations, annotations.id, annotations.annotation_set_id, updated_at, is_targeted, has_polygon (see below for more details)

Preprocessors:

  • Enforce implied permissions from parent annotation_set (get_single_auth_preprocessor)

Postprocessors:

  • Adds annotations and supplementary_annotations fields to the response (get_single_postprocessor)
DELETE

/api/point/<id>

Delete single point object with pk field matching param id

Preprocessors:

  • Enforce implied permissions from parent annotation_set (delete_auth_preprocessor)
POST

/api/point

Custom post endpoint
MODEL COLUMNS FILTERABLE
These attributes map to database columns and can be used when building filters (for endpoints that support filtering, see Making API queries )
NAME TYPE DEFAULT NULLABLE UNIQUE PRIM_KEY FORGN_KEY DESCRIPTION
id Integer() None False None True -

Primary key id
data JSON() {} True None - -

Text field containing JSON properties for this resource
x Float(precision=53) None True False - -

X location of point as a proportion across the frame width (0-1.0, measured from the left, positive right) or latitude for map objects
y Float(precision=53) None True False - -

Y location of point as a proportion across the frame height (0-1.0, measured from the top, positive down) or longitude for map objects
t Float(precision=53) None True False - -

Number of seconds of annotation relative to media.start_time (eg: for video)
media_id Integer() None False None - media.id

Foreign key id of media object linked to point
annotation_set_id Integer() None False None - annotation_set.id

Foreign key id of the parent/origin annotation_set. I.e.: the one linked to the initial creation of the point
updated_at TIMESTAMP() function True None - -

Updated time (UTC)
is_targeted BOOLEAN() False True None - -

Flag denoting whether the Point was manually created to target a specific object
RELATED MODELS FILTERABLE
These attributes expose related objects. Relations can either be single elements or a collection of elements. Related models can be used to contruct filters (for endpoints that support filtering, see Making API queries )
FIELD RELATION DIRECTION DESCRIPTION
media media MANYTOONE

Related media object
annotation_set annotation_set MANYTOONE

Parent/origin annotation_set object
annotations annotation ONETOMANY

List of annotation objects
HYBRID ATTRIBUTES FILTERABLE
These are special defined attributes return dynamically processed results and support both query and instance property operations. HYBRID ATTRIBUTES can be used when building filters (for endpoints that support filtering, see Making API queries ). Note HYBRID METHODS may require input parameters.
NAME TYPE ARGS DESCRIPTION
timestamp property -

The in-situ timestamp for when the annotated object was captured/sampled in the media frame. Returns media.timestamp_start + t if t is set, otherwise it just returns media.timestamp_start

has_xy property -

BOOLEAN, whether or not the point has x-y coordinates. If false, it is a whole-frame annotation, not a point annotation
has_polygon property -

BOOLEAN, whether or not the point has a polygon defined
xy_distance method x, y

FLOAT, euclidean distance to x and y (which are proportions of the image width and height)
OTHER MODEL ATTRIBUTES FILTERABLE
These are special defined attributes return dynamically processed results. These attributes do not work in filter queries.
NAME TYPE DESCRIPTION
annotation_label property

Returns list of dicts [{annotation_id:...,label_id:...}, ...]

SETTER used to set a label based on lookup condition / parameters during batch annotation importing. Parameters are passed by scalar value with query string properties or by setting value as dict. The property value can be scalar, dict, list of dicts or list of scalars.

Examples 

# using a query
point.annotation_label = {"filters":[{"name":...,"op":...,"val":...}],"comment":...,"likelihood":...,"needs_review":...}
# using the origin code for the label
point.annotation_label = {"origin_code":...,"comment":...,"likelihood":...,"needs_review":...}
# using the label UUID
point.annotation_label = {"uuid":...,"comment":...,"likelihood":...,"needs_review":...}
# using the label ID (fastest)
point.annotation_label = {"id":...,"comment":...,"likelihood":...,"needs_review":...}
# To set multiple annotation labels per point, formulate dicts as above but combine in a list:
point.annotation_label = [{...}, ...]
where comment, likelihood and needs_review are optional. Label search can be done using origin_code, uuid, id and/or defining filters, which is a list of filter objects for the label resource. See Making API search queries.

Coming soon: setting labels using semantic translation (or vocab elements)
pixels property

Use to convert between native normalised x, y and polygon to pixel coordinates from top left.

Returns x, y and polygon converted to col, row and polygon values in pixel coordinates from top left of frame using the pixel width and height of the associated media object and are set by the model definition as per the pixel_width and pixel_height properties defined in the media object resource, but can be overridden by url parameters: &pixel_width=&pixel_height=.

SETTER convert from pixel coordinates col, row and polygon to to native normalised coords. As above, pixel with and height can be overridden by the url parameters: &pixel_width=&pixel_height=, and in addition, they can be set by dict parameters width and height. If no row or col are defined, a centroid point is automatically computed for the polygon. See examples below.

Examples 

# Convert x and y pixels to proportions using url params
# URL QS params &pixel_width=&pixel_height=
point.pixels = {"col":...,"row":...}
# Convert x and y pixels to proportions using property imports for each row/entry
point.pixels = {"col":...,"row":...,"width":...,"height":...}
# As above, but include a polygon in pixel coordinates that also needs to be converted
point.pixels = {..., "polygon": [[p1x, p1y],...]}
where col and row are the point coordinates in pixels from the top-left of the frame. polygon is optional and defines a list of lists containing x-y coordinates of polygon in pixels from top-left of the frame.
polygon property

List of lists containing coordinated of vertices for polygons. Coordinates are in proportions of the image (0-1.0). For point annotations, measurements are relative to point's xy location. For whole-frame annotations, they are absolute. When setting this property, it can be a list of lists or a JSON string which will automatically be converted to a list of lists.
pose property

Get closest linked pose to timestamp
set_media property

Returns media.key

SETTER used to link the media object to the point annotation during batch annotation importing. If the matched media object is not already in the associated media_collection, it is added. Matching is done on media.key and optionally deployment.key or deployment.id. Matching on media.key can be very slow, plus it is not always guaranteed to be unique, so it is highly recommended you include deployment info. If multiple matches are found, it will raise an error. Deployment info can be set as a dict property or as a query string parameter.

Examples 

# Set media key as a scalar and use deployment ID from query string
# URL QS params: &deployment_id=407
point.set_media = "PR_20150301_220629_593_LC16"
# Set media key as a scalar and use deployment key from query string
# URL QS params: &deployment_key=r20150301_211555_01_TF_ABCDE_South_West_Mew_Stone
point.set_media = "PR_20150301_220629_593_LC16"
# Set media key and deployment key as dict
point.set_media = {"key":"PR_20150301_220629_593_LC16", "deployment_key":"r20150301_211555_01_TF_ABCDE_South_West_Mew_Stone"}
ENDPOINTS
METHODENDPOINT
POST

/api/pose

Create new pose object. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • Restrict request to LOGGED IN users only (post_auth_preprocessor)
GET

/api/pose

Get list of pose objects matching API query. See Making API search queries for instructions on making search queries

Included fields:
id, dep, alt, lat, lon, events, timestamp, data, media, media.key, media.id, media.timestamp_start, media.path_best_thm, deployment, campaign, platform, color, media.path_best_thm (see below for more details)

Preprocessors:

  • Allow all requests (get_many_auth_preprocessor)
GET

/api/pose/<id>

Get single pose object with pk field matching param id

Included fields:
id, dep, alt, lat, lon, events, timestamp, data, media, media.key, media.id, media.timestamp_start, media.path_best_thm, deployment, campaign, platform, color, media.path_best_thm (see below for more details)

Preprocessors:

  • Allow all requests (get_single_auth_preprocessor)
DELETE

/api/pose/<id>

Delete single pose object with pk field matching param id

Preprocessors:

  • Restrict request to OWNER only (delete_auth_preprocessor)
GET

/api/pose/stats

None
MODEL COLUMNS FILTERABLE
These attributes map to database columns and can be used when building filters (for endpoints that support filtering, see Making API queries )
NAME TYPE DEFAULT NULLABLE UNIQUE PRIM_KEY FORGN_KEY DESCRIPTION
id Integer() None False None True -

Primary key id
lat Float(precision=53) None True False - -

None
lon Float(precision=53) None True False - -

None
alt Float() None True False - -

None
dep Float() None True False - -

None
timestamp DateTime() function False None - -

None
media_id Integer() None False None - media.id

None
geom Geometry(geometry_type='POINT', srid=4326, from_text='ST_GeomFromEWKT', name='geometry') None True None - -

None
RELATED MODELS FILTERABLE
These attributes expose related objects. Relations can either be single elements or a collection of elements. Related models can be used to contruct filters (for endpoints that support filtering, see Making API queries )
FIELD RELATION DIRECTION DESCRIPTION
media media MANYTOONE

None
_data posedata ONETOMANY

None
events deployment_event ONETOMANY

None
HYBRID ATTRIBUTES FILTERABLE
These are special defined attributes return dynamically processed results and support both query and instance property operations. HYBRID ATTRIBUTES can be used when building filters (for endpoints that support filtering, see Making API queries ). Note HYBRID METHODS may require input parameters.
NAME TYPE ARGS DESCRIPTION
distance method lat, lng

FLOAT, distance (in meters) to lat and lon (which are both in decimal degrees)
proximity method lat, lon

None
timestamp_proximity method ts

Absolute difference in seconds of the in-situ timestamp and input ts, which is datetime string eg: "2020-09-25T00:57:11.945009" (or in a format that is parsable by dateutil.parser.parse)
OTHER MODEL ATTRIBUTES FILTERABLE
These are special defined attributes return dynamically processed results. These attributes do not work in filter queries.
NAME TYPE DESCRIPTION
campaign property

None
color property

None
data property

Properties for related pose item including any linked posedata fields
deployment property

None
platform property

None
timestamp_local property

LOCAL datetime, converted using lat, lon and timestamp. SETTER converts Local to UTC
ENDPOINTS
METHODENDPOINT
POST

/api/posedata

Create new posedata object. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • Restrict request to LOGGED IN users only (post_auth_preprocessor)
GET

/api/posedata

Get list of posedata objects matching API query. See Making API search queries for instructions on making search queries

Preprocessors:

  • Allow all requests (get_many_auth_preprocessor)
GET

/api/posedata/<id>

Get single posedata object with pk field matching param id

Preprocessors:

  • Allow all requests (get_single_auth_preprocessor)
DELETE

/api/posedata/<id>

Delete single posedata object with pk field matching param id

Preprocessors:

  • Restrict request to OWNER only (delete_auth_preprocessor)
MODEL COLUMNS FILTERABLE
These attributes map to database columns and can be used when building filters (for endpoints that support filtering, see Making API queries )
NAME TYPE DEFAULT NULLABLE UNIQUE PRIM_KEY FORGN_KEY DESCRIPTION
id Integer() None False None True -

Primary key id
name String(length=80) None False None - -

None
value Float() None True False - -

None
pose_id Integer() None False None - pose.id

None
RELATED MODELS FILTERABLE
These attributes expose related objects. Relations can either be single elements or a collection of elements. Related models can be used to contruct filters (for endpoints that support filtering, see Making API queries )
FIELD RELATION DIRECTION DESCRIPTION
pose pose MANYTOONE

None
ENDPOINTS
METHODENDPOINT
POST

/api/roles

Create new roles object. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • Restrict request to ADMIN user only (assert_current_user_is_admin)
  • Restrict request to LOGGED IN users only (post_auth_preprocessor)
PATCH

/api/roles/<id>

Update single roles object with pk field matching param id. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • Restrict request to ADMIN user only (assert_current_user_is_admin)
  • Restrict request to OWNER only (patch_auth_preprocessor)
GET

/api/roles

Get list of roles objects matching API query. See Making API search queries for instructions on making search queries

Preprocessors:

  • Allow all requests (get_many_auth_preprocessor)
GET

/api/roles/<id>

Get single roles object with pk field matching param id

Preprocessors:

  • Allow all requests (get_single_auth_preprocessor)
DELETE

/api/roles/<id>

Delete single roles object with pk field matching param id

Preprocessors:

  • Restrict request to ADMIN user only (assert_current_user_is_admin)
  • Restrict request to OWNER only (delete_auth_preprocessor)
MODEL COLUMNS FILTERABLE
These attributes map to database columns and can be used when building filters (for endpoints that support filtering, see Making API queries )
NAME TYPE DEFAULT NULLABLE UNIQUE PRIM_KEY FORGN_KEY DESCRIPTION
id Integer() None False None True -

Primary key id
name String(length=80) None False True - -

None
ENDPOINTS
METHODENDPOINT
POST

/api/tag

Create new tag object. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • None (post_preprocessor)
  • Restrict request to LOGGED IN users only (post_auth_preprocessor)
PATCH

/api/tag/<id>

Update single tag object with pk field matching param id. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • Restrict request to OWNER only (patch_auth_preprocessor)
GET

/api/tag

Get list of tag objects matching API query. See Making API search queries for instructions on making search queries

Included fields:
user_id, name, type_id, synonym_tag_id, type, id, is_synonym, type, synonyms, synonyms.name, synonyms.id, synonyms.user_id (see below for more details)

Preprocessors:

  • Allow all requests (get_many_auth_preprocessor)
GET

/api/tag/<id>

Get single tag object with pk field matching param id

Included fields:
user_id, name, type_id, synonym_tag_id, type, id, is_synonym, type, synonyms, synonyms.name, synonyms.id, synonyms.user_id (see below for more details)

Preprocessors:

  • Allow all requests (get_single_auth_preprocessor)
DELETE

/api/tag/<id>

Delete single tag object with pk field matching param id

Preprocessors:

  • Restrict request to OWNER only (delete_auth_preprocessor)
MODEL COLUMNS FILTERABLE
These attributes map to database columns and can be used when building filters (for endpoints that support filtering, see Making API queries )
NAME TYPE DEFAULT NULLABLE UNIQUE PRIM_KEY FORGN_KEY DESCRIPTION
id Integer() None False None True -

Primary key id
name String(length=80) None False None - -

None
user_id Integer() None False None - users.id

None
type_id Integer() None True None - tag_type.id

None
description Text() None True None - -

None
synonym_tag_id Integer() None True None - tag.id

None
RELATED MODELS FILTERABLE
These attributes expose related objects. Relations can either be single elements or a collection of elements. Related models can be used to contruct filters (for endpoints that support filtering, see Making API queries )
FIELD RELATION DIRECTION DESCRIPTION
user users MANYTOONE

None
type tag_type MANYTOONE

None
synonym_tag tag MANYTOONE

None
synonyms tag ONETOMANY

None
label_tags label_tags ONETOMANY

None
annotation_tags annotation_tags ONETOMANY

Collection of annotation_tags associations
ASSOCIATION PROXIES FILTERABLE
These attributes map linked objects from collections (eg: many-to-many relationships that have an association table) Association proxies can be used when building filters (for endpoints that support filtering, see Making API queries )
ATTRIBUTE MODEL COLLECTION DESCRIPTION
labels label label_tags Proxy attribute that presents the linked label objects from the label_tags collection
HYBRID ATTRIBUTES FILTERABLE
These are special defined attributes return dynamically processed results and support both query and instance property operations. HYBRID ATTRIBUTES can be used when building filters (for endpoints that support filtering, see Making API queries ). Note HYBRID METHODS may require input parameters.
NAME TYPE ARGS DESCRIPTION
is_synonym property -

None
ENDPOINTS
METHODENDPOINT
POST

/api/tag_type

Create new tag_type object. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • Restrict request to LOGGED IN users only (post_auth_preprocessor)
PATCH

/api/tag_type/<id>

Update single tag_type object with pk field matching param id. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • Restrict request to OWNER only (patch_auth_preprocessor)
GET

/api/tag_type

Get list of tag_type objects matching API query. See Making API search queries for instructions on making search queries

Preprocessors:

  • Allow all requests (get_many_auth_preprocessor)
GET

/api/tag_type/<id>

Get single tag_type object with pk field matching param id

Preprocessors:

  • Allow all requests (get_single_auth_preprocessor)
DELETE

/api/tag_type/<id>

Delete single tag_type object with pk field matching param id

Preprocessors:

  • Restrict request to OWNER only (delete_auth_preprocessor)
MODEL COLUMNS FILTERABLE
These attributes map to database columns and can be used when building filters (for endpoints that support filtering, see Making API queries )
NAME TYPE DEFAULT NULLABLE UNIQUE PRIM_KEY FORGN_KEY DESCRIPTION
id Integer() None False None True -

Primary key id
name String(length=80) None False True - -

None
description Text() None True None - -

None
RELATED MODELS FILTERABLE
These attributes expose related objects. Relations can either be single elements or a collection of elements. Related models can be used to contruct filters (for endpoints that support filtering, see Making API queries )
FIELD RELATION DIRECTION DESCRIPTION
tags tag ONETOMANY

None
ENDPOINTS
METHODENDPOINT
GET

/api/usergroups

Get list of usergroups objects matching API query. See Making API search queries for instructions on making search queries

Included fields:
created_at, approved, can_edit, added_by_user, added_by_user.id, added_by_user.first_name, added_by_user.last_name, user, user.id, user.username, user.created_at, user.last_login, user.first_name, user.last_name, user.active, user.is_admin, group, group.id, group.name, can_add_members, can_share_data, has_agreed, group.is_public, group.is_restricted, group.user_id, group.requires_approval, group.requires_agreement, group.group_type_id, group.groupinfo, group.created_at (see below for more details)

Preprocessors:

  • Allow all requests (get_many_auth_preprocessor)
GET

/api/usergroups/<group_id>

Get single usergroups object with pk field matching param group_id

Included fields:
created_at, approved, can_edit, added_by_user, added_by_user.id, added_by_user.first_name, added_by_user.last_name, user, user.id, user.username, user.created_at, user.last_login, user.first_name, user.last_name, user.active, user.is_admin, group, group.id, group.name, can_add_members, can_share_data, has_agreed, group.is_public, group.is_restricted, group.user_id, group.requires_approval, group.requires_agreement, group.group_type_id, group.groupinfo, group.created_at (see below for more details)

Preprocessors:

  • Allow all requests (get_single_auth_preprocessor)
MODEL COLUMNS FILTERABLE
These attributes map to database columns and can be used when building filters (for endpoints that support filtering, see Making API queries )
NAME TYPE DEFAULT NULLABLE UNIQUE PRIM_KEY FORGN_KEY DESCRIPTION
user_id Integer() None False None True users.id

None
group_id Integer() None False None True groups.id

None
created_at DateTime() function True None - -

None
approved Boolean() False True None - -

None
can_edit Boolean() False True None - -

None
can_add_members Boolean() False True None - -

None
can_share_data Boolean() False True None - -

None
has_agreed Boolean() False True None - -

None
added_by_user_id Integer() None True None - users.id

None
RELATED MODELS FILTERABLE
These attributes expose related objects. Relations can either be single elements or a collection of elements. Related models can be used to contruct filters (for endpoints that support filtering, see Making API queries )
FIELD RELATION DIRECTION DESCRIPTION
user users MANYTOONE

None
added_by_user users MANYTOONE

None
group groups MANYTOONE

None
ENDPOINTS
METHODENDPOINT
GET

/api/users

Get list of users objects matching API query. See Making API search queries for instructions on making search queries

Included fields:
id, user_created_at, last_login, first_name, last_name, username, active, info, role, affiliations, affiliations.name, affiliations.groupinfo, affiliations.id, affiliations_names (see below for more details)

Preprocessors:

  • Allow all requests (get_many_auth_preprocessor)
GET

/api/users/<id>

Get single users object with pk field matching param id

Included fields:
id, user_created_at, last_login, first_name, last_name, username, active, info, role, affiliations, affiliations.name, affiliations.groupinfo, affiliations.id, affiliations_names (see below for more details)

Preprocessors:

  • Allow all requests (get_single_auth_preprocessor)

Postprocessors:

  • None (get_single_postprocessor)
DELETE

/api/users/<id>

Delete single users object with pk field matching param id

Preprocessors:

  • Restrict request to ADMIN user only (assert_current_user_is_admin)
  • Restrict request to OWNER only (delete_auth_preprocessor)
GET

/api/users/api_token

Manage API token
PATCH

/api/users/api_token

Manage API token
DELETE

/api/users/api_token

Manage API token
POST

/api/users/<int:user_id>/group/<int:group_id>

Manage group membership
DELETE

/api/users/<int:user_id>/group/<int:group_id>

Manage group membership
PATCH

/api/users/<int:user_id>/group/<int:group_id>

Manage group membership
POST

/api/users/login

Log in. Requires form parameters username and password.
DELETE

/api/users/login

Log out the current session
GET

/api/users/login

Get information about current logged in user
POST

/api/users

Update user information
PATCH

/api/users/<int:user_id>

Update user information
POST

/api/users/reset_password

None
GET

/api/users/reset_password

None
POST

/api/users/reset_password/<token>

None
GET

/api/users/reset_password/<token>

None
POST

/api/users/<int:user_id>/email

Send an email to the user. Requires json post body containing message and optionally subject. If no subject, default subject will be "User message from PROJECT_NAME"
MODEL COLUMNS FILTERABLE
These attributes map to database columns and can be used when building filters (for endpoints that support filtering, see Making API queries )
NAME TYPE DEFAULT NULLABLE UNIQUE PRIM_KEY FORGN_KEY DESCRIPTION
id Integer() None False None True -

Primary key id
username String(length=80) None False True - -

None
email String(length=80) None False True - -

None
password String(length=128) None False None - -

None
created_at DateTime() function False None - -

None
last_login DateTime() now() True None - -

None
first_name String(length=30) None False None - -

None
last_name String(length=30) None False None - -

None
active Boolean() True True None - -

None
is_admin Boolean() False True None - -

None
info Text() None True None - -

None
role_id Integer() None True None - roles.id

None
api_token String(length=80) None True True - -

None
RELATED MODELS FILTERABLE
These attributes expose related objects. Relations can either be single elements or a collection of elements. Related models can be used to contruct filters (for endpoints that support filtering, see Making API queries )
FIELD RELATION DIRECTION DESCRIPTION
role roles MANYTOONE

None
affiliations_usergroups usergroups ONETOMANY

None
usergroups usergroups ONETOMANY

None
ASSOCIATION PROXIES FILTERABLE
These attributes map linked objects from collections (eg: many-to-many relationships that have an association table) Association proxies can be used when building filters (for endpoints that support filtering, see Making API queries )
ATTRIBUTE MODEL COLLECTION DESCRIPTION
affiliations group affiliations_usergroups Proxy attribute that presents the linked group objects from the affiliations_usergroups collection
OTHER MODEL ATTRIBUTES FILTERABLE
These are special defined attributes return dynamically processed results. These attributes do not work in filter queries.
NAME TYPE DESCRIPTION
affiliations_names method

None
full_name method

None
get_id method

None
is_active method

None
is_anonymous method

None
is_authenticated method

None
ENDPOINTS
METHODENDPOINT
POST

/api/vocab_element

Create new vocab_element object. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • Restrict request to LOGGED IN users only (post_auth_preprocessor)
PATCH

/api/vocab_element/<id>

Update single vocab_element object with pk field matching param id. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • Restrict request to OWNER only (patch_auth_preprocessor)
GET

/api/vocab_element

Get list of vocab_element objects matching API query. See Making API search queries for instructions on making search queries

Included fields:
id, name, key, parent_key, vocab_registry, vocab_registry.key, vocab_registry.vocab_element_key_name, vocab_registry.name, vocab_registry.description, created_at, updated_at, user, user.id, lineage, user.first_name, mapped_registries, user.last_name, other_names, other_names.id, other_names.name, origin_updated_at, reference_url, reference_url_parent (see below for more details)

Preprocessors:

  • Allow all requests (get_many_auth_preprocessor)
GET

/api/vocab_element/<id>

Get single vocab_element object with pk field matching param id

Included fields:
id, name, key, parent_key, vocab_registry, vocab_registry.key, vocab_registry.vocab_element_key_name, vocab_registry.name, vocab_registry.description, created_at, updated_at, user, user.id, lineage, user.first_name, mapped_registries, user.last_name, other_names, other_names.id, other_names.name, origin_updated_at, reference_url, reference_url_parent, data, description, mapped_labels (see below for more details)

Preprocessors:

  • Allow all requests (get_single_auth_preprocessor)
DELETE

/api/vocab_element/<id>

Delete single vocab_element object with pk field matching param id

Preprocessors:

  • Restrict request to OWNER only (delete_auth_preprocessor)
GET

/api/vocab_element/<registry_key>/<element_key>

None
POST

/api/vocab_element/<registry_key>/<element_key>

None
PATCH

/api/vocab_element/<registry_key>/<element_key>

None
POST

/api/vocab_element/<registry_key>/<element_key>/label/<label_id>

None
DELETE

/api/vocab_element/<registry_key>/<element_key>/label/<label_id>

None
GET

/api/vocab_element/nested

None
MODEL COLUMNS FILTERABLE
These attributes map to database columns and can be used when building filters (for endpoints that support filtering, see Making API queries )
NAME TYPE DEFAULT NULLABLE UNIQUE PRIM_KEY FORGN_KEY DESCRIPTION
id Integer() None False None True -

Primary key id
name String(length=128) None False False - -

None
key String(length=96) None False None - -

None
lineage JSON() None True None - -

None
data JSON() None True None - -

None
mapped_registries JSON() None True None - -

None
description Text() None True None - -

None
parent_key String(length=96) None True None - -

None
vocab_registry_key String(length=96) None False None - vocab_registry.key

The id of the vocab_registry
user_id Integer() None False None - users.id

The id of the user who created and owns this record
created_at DateTime() function True None - -

None
updated_at TIMESTAMP() function True None - -

Updated time (UTC)
origin_updated_at DateTime() None True None - -

None
RELATED MODELS FILTERABLE
These attributes expose related objects. Relations can either be single elements or a collection of elements. Related models can be used to contruct filters (for endpoints that support filtering, see Making API queries )
FIELD RELATION DIRECTION DESCRIPTION
vocab_registry vocab_registry MANYTOONE

The vocab_registry that contains this vocab_element
user users MANYTOONE

The user who owns or created and owns this record
labels label MANYTOMANY

A list of labels linked to this vocab_element
other_names vocab_element_names ONETOMANY

None
label_vocab_element label_vocab_element ONETOMANY

None
OTHER MODEL ATTRIBUTES FILTERABLE
These are special defined attributes return dynamically processed results. These attributes do not work in filter queries.
NAME TYPE DESCRIPTION
mapped_labels method

None
reference_url method

None
reference_url_parent method

None
ENDPOINTS
METHODENDPOINT
POST

/api/vocab_element_names

Create new vocab_element_names object. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • Restrict request to LOGGED IN users only (post_auth_preprocessor)
PATCH

/api/vocab_element_names/<id>

Update single vocab_element_names object with pk field matching param id. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • Restrict request to OWNER only (patch_auth_preprocessor)
GET

/api/vocab_element_names

Get list of vocab_element_names objects matching API query. See Making API search queries for instructions on making search queries

Preprocessors:

  • Allow all requests (get_many_auth_preprocessor)
GET

/api/vocab_element_names/<id>

Get single vocab_element_names object with pk field matching param id

Preprocessors:

  • Allow all requests (get_single_auth_preprocessor)
DELETE

/api/vocab_element_names/<id>

Delete single vocab_element_names object with pk field matching param id

Preprocessors:

  • Restrict request to OWNER only (delete_auth_preprocessor)
MODEL COLUMNS FILTERABLE
These attributes map to database columns and can be used when building filters (for endpoints that support filtering, see Making API queries )
NAME TYPE DEFAULT NULLABLE UNIQUE PRIM_KEY FORGN_KEY DESCRIPTION
id Integer() None False None True -

Primary key id
name String(length=128) None False False - -

None
vocab_element_id Integer() None False None - vocab_element.id

None
RELATED MODELS FILTERABLE
These attributes expose related objects. Relations can either be single elements or a collection of elements. Related models can be used to contruct filters (for endpoints that support filtering, see Making API queries )
FIELD RELATION DIRECTION DESCRIPTION
vocab_element vocab_element MANYTOONE

None
ENDPOINTS
METHODENDPOINT
POST

/api/vocab_registry

Create new vocab_registry object. Expects JSON. Fields shown in MODEL COLUMNS below. A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance's class are allowed. These could be, for example, any mapped columns or relationships.

Preprocessors:

  • Restrict request to ADMIN user only (assert_current_user_is_admin)
  • Restrict request to LOGGED IN users only (post_auth_preprocessor)
PATCH

/api/vocab_registry/<key>

Update single vocab_registry object with pk field matching param key. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • Restrict request to ADMIN user only (assert_current_user_is_admin)
  • Restrict request to OWNER only (patch_auth_preprocessor)
GET

/api/vocab_registry

Get list of vocab_registry objects matching API query. See Making API search queries for instructions on making search queries

Included fields:
key, name, description, created_at, updated_at, user, user.id, user.first_name, user.last_name, vocab_element_key_name, registry_urls (see below for more details)

Preprocessors:

  • Allow all requests (get_many_auth_preprocessor)
GET

/api/vocab_registry/<key>

Get single vocab_registry object with pk field matching param key

Included fields:
key, name, description, created_at, updated_at, user, user.id, user.first_name, user.last_name, vocab_element_key_name, registry_urls (see below for more details)

Preprocessors:

  • Allow all requests (get_single_auth_preprocessor)
DELETE

/api/vocab_registry/<key>

Delete single vocab_registry object with pk field matching param key

Preprocessors:

  • Restrict request to ADMIN user only (assert_current_user_is_admin)
  • Restrict request to OWNER only (delete_auth_preprocessor)
GET

/api/vocab_registry/<key>/match

None
GET

/api/vocab_registry/<key>/get_element

None
GET

/api/vocab_registry/<key>/get_all_elements

None
GET

/api/vocab_registry/<key>/get_children

None
MODEL COLUMNS FILTERABLE
These attributes map to database columns and can be used when building filters (for endpoints that support filtering, see Making API queries )
NAME TYPE DEFAULT NULLABLE UNIQUE PRIM_KEY FORGN_KEY DESCRIPTION
key String(length=96) None False True True -

None
name String(length=128) None False True - -

None
module String(length=96) None False None - -

None
module_kwargs JSON() None True None - -

None
vocab_element_key_name String(length=96) None True None - -

None
description Text() None True None - -

None
user_id Integer() None False None - users.id

The id of the user who created and owns this record
created_at DateTime() function True None - -

None
updated_at TIMESTAMP() function True None - -

Updated time (UTC)
RELATED MODELS FILTERABLE
These attributes expose related objects. Relations can either be single elements or a collection of elements. Related models can be used to contruct filters (for endpoints that support filtering, see Making API queries )
FIELD RELATION DIRECTION DESCRIPTION
user users MANYTOONE

The user who owns or created and owns this record
vocab_elements vocab_element ONETOMANY

None
OTHER MODEL ATTRIBUTES FILTERABLE
These are special defined attributes return dynamically processed results. These attributes do not work in filter queries.
NAME TYPE DESCRIPTION
registry_urls method

None
registry_plugin property

None

Making API queries

Pagination

/api/resource?results_per_page=...&page=...

Responses to most GET requests (with the exception of the export endpoints) are paginated by default, with at most ten objects per page. To request a specific page, add a page=N query parameter to the request URL, where N is a positive integer (the first page is page one). If no page query parameter is specified, the first page will be returned.

In order to specify the number of results per page, add the query parameter results_per_page=N where N is a positive integer. If results_per_page is greater than the maximum number of results per page as configured by the server, then the query parameter will be ignored.

In addition to the "objects" list, the response JSON object will have a "page" key with the current page number, a "num_pages" key with total number of pages into which the set of matching instances is divided, and a "num_results" key with total number of instances which match the requested search.

Query format:

/api/resource?q={"filters":[...],"limit":...,"offset":...,"order_by":[...],"group_by":[...],"single":...}

The query parameter q must be a JSON string. It can have the following mappings, all of which are optional:

filters

A list of <filterobjects> of one of the following forms:

{"name": <fieldname>, "op": <operatorname>, "val": <argument>}

Where <operatorname> is one of the strings described below, <argument> is a value to be used as the second argument to the given operator and <fieldname> is the name of the field of the model to which to apply the operator, which can be either a MODEL COLUMN, RELATED MODEL, ASSOCIATION PROXY or HYBRID ATTRIBUTE for a resource.

{"name": <fieldname>, "op": <operatorname>, "field": <fieldname>}

Where the first <fieldname> and <operatorname> are as above and the second <fieldname> is the field of the model that should be used as the second argument to the operator.

The first <fieldname> may specify a field on a related model, if it is a string of the form <relationname>__<fieldname>. Alternatively if the field name is the name of a relation and the operator is "has" or "any", the "val" argument can be a dictionary with the arguments representing another, nested filter to be applied as the argument for "has" or "any".

The <operatorname> strings recognized by the API include:

==, eq, equals, equals_to "equal to" operator, where val can be numeric or string
!=, neq, does_not_equal, not_equal_to "not equal to" operator, where val can be numeric or string
>, gt, <, lt "less/greater than" operator, where val is typically numeric
>=, ge, gte, geq, <=, le, lte, leq "less/greater than or equal to" operator, where val is typically numeric
in, not_in "is in" operator, where val is typically a list of values
is_null, is_not_null "is null" check, where there is no val param
like, ilike: "like" (case sensitive) or "ilike" (case insensitive) comparison, where val is a string. Wildcards can be included as a % symbol (or %25 url-encoded).
has for nesting operators on a relation that is a single object (i.e.: MANYTOONE)
any for nesting operators on a relation that is a list of objects (i.e.: ONETOMANY/MANYTOMANY)

For geometry columns, there are also some spatial operators for <operatorname>, which include:

geo_at Geometry / Geography type <fieldname> is close to a nominated lat/lon. The val takes the form: {"lat":...,"lon":...,"dist":...} where dist is optional and defaults to 0.00005. For Geometry types dist is in srid units (eg: degrees), for Geography types it is meters. Hint: assume Geometry types most of the time.
geo_in_bbox Geometry / Geography type <fieldname> is within a bounding box. The val takes the form: [p1,p2], which is a list containing two elements being two diagonal points defining the bounding box, eg: [bottom-left, top-right]. p1,p2 are position objects of the form, {"lat":...,"lon":...}
geo_in_poly_xy Same as in geo_in_bbox, but p1-pn are of the form [lon, lat].
geo_in_poly_yx Same as in geo_in_bbox, but p1-pn are of the form [lat, lon].
geo_in_polys_xy Geometry / Geography type <fieldname> is within a multipolygon. The val is a polygon list of points of the form: [[p11,p12,p13,...,p1n,p11],[p21,p22,p23,...,p2n,p21]], where p11-p1n are verticeis for the first polygon, p21-p2n are of the second and so on. pxn are of the form [lon, lat].

Filters can also exclude results, for example:

{"not": <filterobject>}

Filter objects can also be arbitrary Boolean formulas, for example:

{"or": [<filterobject>, {"and": [<filterobject>, ...]}, ...]}

Filter objects can also be defined on Hybrid Attributes of a model. hybrid property filter objects are defined in the same way as column fields, but to filter by a hybrid method with one or more input arguments (<arg1>,<arg2>,...<argN>), the object can be defined as:

{"name": {"method":<method_name>,"args":[<arg1>,<arg2>,...<argN>]}, "op": <operatorname>, "val": <argument>}

The returned list of matching instances will include only those instances that satisfy all of the given filters.

If a filter is poorly formatted (for example, op is set to '==' but val is not set), the server responds with 400 Bad Request.

limit
A positive integer which specifies the maximum number of objects to return.
offset
A positive integer which specifies the offset into the result set of the returned list of instances.
order_by

A list of objects of the form:

{"field": <fieldname>, "direction": <directionname>}

where <fieldname> is a string corresponding to the name of a field of the requested model and <directionname> is either "asc" for ascending order or "desc" for descending order.

<fieldname> may alternately specify a field on a related model, if it is a string of the form <relationname>__<fieldname>.

Ordering can also be defined on Hybrid Attributes of a model. hybrid property order_by objects are defined in the same way as column fields, but to filter by a hybrid method with one or more input arguments (<arg1>,<arg2>,...<argN>), the object can be defined as:

{"field": {"method":<method_name>,"args":[<arg1>,<arg2>,...<argN>]}, "direction": <directionname>}
group_by

A list of objects of the form:

{"field": <fieldname>}

where <fieldname> is a string corresponding to the name of a field of the requested model.

<fieldname> may alternately specify a field on a related model, if it is a string of the form <relationname>__<fieldname>.

single
A Boolean representing whether a single result is expected as a result of the search. If this is true and either no results or multiple results meet the criteria of the search, the server responds with an error message.

Data transformation and batch operations

/api/resource?f={...}&save={...}

Some endpoints support data transformation and manipulation of the output using the data transformation API. This allows users to define a sequence of operations that can be used to transform the output of the response in order to (i) export data in a desired format or (ii) perform batch import operations.

DOCUMENTATION FOR THIS IS STILL COMING... WATCH THIS SPACE...

Other resources