Skip to content

Attributes

Attributes are optional key-value pairs that can be used with files that are stored in the API.

Supported file types and endpoints

The types of files that support attributes (and their associated endpoints) are:

Standard attributes

All of the supported file types provide the ability to specify a set of standard attributes. These standard attributes are:

  • "date_time_local" - A string representing a date and time in the local time zone. The string should be formatted using ISO 8601, with no time zone information or fraction of a second included in the representation (i.e. yyyy-mm-ddThh:mm:ss).
  • "date_time_utc" - A string representing a date and time in UTC. The string should be formatted using ISO 8601, with no time zone information or fraction of a second included in the representation (i.e. yyyy-mm-ddThh:mm:ss).
  • "gps_latitude" - The latitude value of a GPS position. It should be in the range of -90 to 90, and "gps_longitude" should also be provided.
  • "gps_longitude" - The longitude value of a GPS position. It should be in the range of -180 to 180, and "gps_latitude" should also be provided.
  • "sensor" - A URI to the sensor that was used to capture or generate this file.

Get a list of standard attributes

Retrieve a list of the standard attributes that are supported for a file type. Each attribute in the list is represented by its URI.

Route: /v3{instance-uri}{files-endpoint}/attributes (see supported file endpoints)
Method: GET

Sample response body:

{
  "success": true,
  "data": {
    "images": {
      "attributes": [
        "/images/attributes/date_time_local",
        "/images/attributes/date_time_utc",
        "/images/attributes/gps_latitude",
        "/images/attributes/gps_longitude",
        "/images/attributes/sensor"
      ]
    }
  }
}

Get the details of a standard attribute

Retrieve the details of a standard attribute.

Route: /v3{instance-uri}{attribute-uri}
Method: GET

Sample response body:

{
  "success": true,
  "data": {
    "images": {
      "attribute": {
        "uri": "/images/attributes/date_time_local",
        "name": "date_time_local",
        "description": "Date and time of the resource in the local time zone"
      }
    }
  }
}

Custom attributes

Files support the use of custom attributes. Initial values for custom attributes can be assigned when the file is uploaded, though they can always be set and updated at a later time.

Setting attribute values

The values for attributes and custom attributes can be set when uploading a new file as well as via a PATCH request for an existing file. The following sections provide more details for accomplishing both of these operations.

Set attributes when uploading

When uploading a file, or starting a new multipart upload, the attributes and custom_attributes form parameters can be used to provide initial values for the attributes for the file. Both form parameters expect a string with a JSON dictionary representation of the key-value pairs that should be set.

Sample attributes form parameter:

{
  "date_time_local": "2022-01-02T13:14:15",
  "gps_latitude": 1.23,
  "gps_longitude": 4.56,
  "sensor": "/sensors/dji-mavic-2-pro"
}

Sample custom_attributes form parameter:

{
  "my_attribute": "a value"
}

Set attributes for existing files

The values for attributes and custom attributes can be set for existing files via a PATCH request.

Route: /v3{instance-uri}{file-uri}
Method: PATCH

The body of the request can contain new values to set for both attributes and custom attributes, as well as null values to indicate that the value for an attribute should be removed (if it previously had been defined). Any existing values for the file that are not modified by the request will be left intact.

Sample request body:

{
  "attributes": {
    "date_time_local": null,
    "date_time_utc": "2022-01-02T13:14:15",
    "gps_latitude": 1.23,
    "gps_longitude": 4.56
  },
  "custom_attributes": {
    "my_attribute": "a new value",
    "old_attribute": null
  }
}

Upon successfully updating the attributes for a file, the response will contain the updated details of the file.