Querying¶

Once files have been stored in the API (either via upload or as the output of a job), they can be searched for in a variety of ways. To search for jobs, refer to the details on querying for job.

Supported file types and endpoints¶

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

Images via the /images endpoint.
Videos via the /videos endpoint.
AR sessions via the /ar-sessions endpoint.
AR lidar sessions via the /ar-lidar-sessions endpoint.
Point clouds via the /point-clouds endpoint.
Meshes via the /meshes endpoint.
Orthomosaics via the /orthomosaics endpoint.

Get a list of files¶

Returns a list of all available files of a particular type. Each file in the list is represented by its URI. Multipart uploads that are not yet complete will not be included in this list.

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

Sample response body:

{
  "success": true,
  "data": {
    "images": [
      "/images/1111-1111",
      "/images/2222-2222",
      "/images/3333-3333",
      ...
    ]
  }
}

Return details of the files¶

Instead of returning a list where each file is represented by its URI, return a list where each entry contains the details of the file. This is accomplished by appending the details option to the request's URL.

Route: /v3{instance-uri}{files-endpoint}?details
Method: GET

Sample response body:

{
  "success": true,
  "data": {
    "images": [
      {
        "uri": "/images/1111-1111",
        "name": "my photo",
        "type": "jpg",
        ...
      },
      {
        "uri": "/images/2222-2222",
        "name": "another photo",
        "type": "jpg",
        ...
      },
      ...
    ]
  }
}

Return details of the most recent file¶

Instead of returning a list of all available files, return only the most recent file that has been added to the API (here, the most recent file is determined based on the order that the API calls were made to add the files, and not any date-time attribute of the files). To retrieve only the most recent file, append the latest option to the request's URL, and the response will contain the details of the file (instead of just its URI), matching the response that is returned when getting the details of a single file.

Route: /v3{instance-uri}{files-endpoint}?latest
Method: GET

Sample response body:

{
  "success": true,
  "data": {
    "image": {
      "uri": "/images/1111-1111",
      "name": "my photo",
      "type": "jpg",
      ...
    }
  }
}

Query for files¶

Files can be searched for based on their properties, standard attributes, or custom attributes. For instance, files can be found based on their name, type, date-time, GPS position, or other custom values. To search for jobs, refer to the details on querying for job.

All queries are accomplished via a query string that is appended to a supported file endpoint:

Route: /v3{instance-uri}{files-endpoint}?query={query-string} (see supported file endpoints)
Method: GET

Files that match the query are returned in the response, with the same format as retrieving a list of all available files.

The details or latest options can also be used with a query, and their use in the route URL would appear as follows:

/v3{instance-uri}{files-endpoint}?query={query-string}&details
/v3{instance-uri}{files-endpoint}?query={query-string}&latest

Query string format¶

The query is formatted using a JSON-encoded string, where the query contains names, values, and operators. A single term in a query is made up of a name, value, and comparison operator (like equal-to or greater-than), and has the following format:

{"name": {"comparison-operator": value}}

Two or more terms can be combined together via a logical operator (like AND or OR). In this case, the query will have the following format:

{"logical-operator": [
  {"name": {"comparison-operator": value}},
  {"name": {"comparison-operator": value}}
]}

All operators begin with a $, and the supported comparison operators are:

Equal to - $eq
Not equal to - $neq
Greater than - $gt
Great than or equal to - $gte
Less than - $lt
Less than or equal to - $lte

At most one logical operator is supported in a query, and the supported logical operators are:

And - $and
Or - $or

The name that is used in a query term can refer to one of several things:

A file property, like "name", "type", or "size"
A standard attribute, where the standard attribute name has been prefixed with attributes. (e.g. "attributes.date_time_local")
A custom attribute, where the custom attribute name has been prefixed with custom_attributes. (e.g. "custom_attributes.my_attribute")
A shared custom attribute, where the custom attribute name has been prefixed with {shared-folder-name}.custom_attributes. (e.g. "my-shared-folder.custom_attributes.my_attribute"). This is useful for querying for files that are accessible via a shared folder, where the user who's shared the folder has set one or more of their custom attributes to be shared.
An annotation, where properties of the annotation can be used in the query such as "annotations.label" or "annotations.custom_attributes.{custom-attribute-name}".

As a note, when using comparison operators on a string value, the comparison is performed in a case-insensitive manner. This means that the strings "TEST", "Test", and "test" will all be treated as equal.

With the tools of logical operators, comparison operators, and attribute or property names, we can now construct a variety of queries. For example, to search for JPG images:

/images?query={"type":{"$eq":"jpg"}}

To search for images that were captured in the year 2022 or newer:

/images?query={"attributes.date_time_local":{"$gte":"2022-01-01T00:00:00"}}

To search for videos within a defined GPS region:

/videos?query={"$and":[
  {"attributes.gps_latitude":{"$gt":1.2}},
  {"attributes.gps_latitude":{"$lt":3.4}},
  {"attributes.gps_longitude":{"$gt":-2.3}},
  {"attributes.gps_longitude":{"$lt":-1.2}}
]}

To search for images that were captured with a DJI Mavic 2 Pro:

/images?query={"attributes.sensor":{"$eq":"/sensors/dji-mavic-2-pro"}}

To search for orthomosaics that have stockpile annotations:

/orthomosaics?query={"annotations.label":{"$eq":"/labels/stockpile"}}

To search for images that have "red mulch" as the product in an annotation's custom attributes:

/images?query={"annotations.custom_attributes.product":{"$eq":"red mulch"}}

To search for meshes that have been defined with a value of "car" or "truck" for a custom vehicle attribute:

/meshes?query={"$or":[
  {"custom_attributes.vehicle":{"$eq":"car"}},
  {"custom_attributes.vehicle":{"$eq":"truck"}}
]}

When performing a query using a non-null value, only those files that have non-null values for that attribute will be returned. For example, searching for vehicles that are not cars will only return files that have a vehicle defined:

{"custom_attributes.vehicle": {"$neq": "car"}

If a file has not had a vehicle value defined for it, that file will not be returned in the list of results. In order to search for vehicles that are not cars as well as those that have an undefined vehicle, use a logical operator to combine the two terms:

{"$or": [
  {"custom_attributes.vehicle": {"$neq": "car"}},
  {"custom_attributes.vehicle": {"$eq": null}}
]}