How to find image resolution data for Open Aerial Map images through the API?

Question

I'm prepping a data set and would like to download all images from Open Aerial Map that have a ground resolution of say greater than 5cm/pixel.

The web UI displays this data for each image:

But I can't see a way to access it through the API (Note: Link to API docs from main site is currently broken): https://hotosm.github.io/oam-api/

I can access the metadata for any image, but can't find any kind of resolution data:

{"uuid":"http://oin-hotosm.s3.amazonaws.com/573a17d4cd0663bb003c32b6/0/575fcf142b67227a79b4fbfd.tif","title":"Carretera _ Puente Rio Chico","projection":"GEOGCS[\"WGS 84\",DATUM[\"WGS_1984\",SPHEROID[\"WGS 84\",6378137,298.257223563,AUTHORITY[\"EPSG\",\"7030\"]],AUTHORITY[\"EPSG\",\"6326\"]],PRIMEM[\"Greenwich\",0],UNIT[\"degree\",0.0174532925199433],AUTHORITY[\"EPSG\",\"4326\"]]","bbox":[-80.4248105,-0.9801461999990004,-80.418725308,-0.9748216999999999],"footprint":"POLYGON((-80.4248105 -0.9748216999999999,-80.418725308 -0.9748216999999999,-80.418725308 -0.9801461999990004,-80.4248105 -0.9801461999990004,-80.4248105 -0.9748216999999999))","gsd":1.8570457238770968e-7,"file_size":47649982,"acquisition_start":"2016-04-27T05:00:00.000Z","acquisition_end":"2016-04-28T17:00:03.000Z","platform":"uav","provider":"Santiago Pastor","contact":"fruizc,[email protected]","properties":{"sensor":"Unknow","thumbnail":"http://oin-hotosm.s3.amazonaws.com/573a17d4cd0663bb003c32b6/0/575fcf142b67227a79b4fbfd_thumb.png","tms":"http://tiles.openaerialmap.org/573a17d4cd0663bb003c32b6/0/575fcf142b67227a79b4fbfd/{z}/{x}/{y}.png","wmts":"http://tiles.openaerialmap.org/573a17d4cd0663bb003c32b6/0/575fcf142b67227a79b4fbfd/wmts"},"uploaded_at":"2016-05-16T00:00:00.000Z"}

How do I find image resolution data for Open Aerial Map images through the API?

Answer 1

TL;DR Web site resolution Resolution == Metadata GSM*

Full answer*: I did some hunting through the web site and API source and think I have it worked out.

First I got the metadata for a specific image. Easy-ish to do through the UI: 1. Copy the "TMS" URL for an image. 2. Replace the image IDs in a meta URL query and get the JSON.

eg: TMS URL: https://tiles.openaerialmap.org/5e40d48b56992d0006e589df/0/5e40d48b56992d0006e589e0/{z}/{x}/{y}

Metadata URL: http://oin-hotosm.s3.amazonaws.com/5e40d48b56992d0006e589df/0/5e40d48b56992d0006e589e0_meta.json

This is the src for the search result pane:

...        
<span>Resolution</span>
</dt>
<dd>{utils.gsdToUnit(d.gsd)}</dd>
...

And from utils.js:

 /**
   * Coverts the given GSD to meters or centimeters
   * @param  float gsd in meters
   * @return string
   */
  gsdToUnit: function(gsd) {
    var unit = "m";
    // If it's less than 1m, convert to cm so it displays more nicely
    if (gsd < 1) {
      unit = "cm";
      gsd *= 100;
    }

    return Math.round(gsd) + " " + unit;
  },

In above example metadata GSD = 0.0199991051357, and web UI displays 2cms which matches the function.

What tricked me up is a lot of images seem to have very small possibly invalid GSD values which probably need to be corrected by several orders of magnitude.

Bonus info: Can hit the metadata endpoint with GSD queries, eg:

https://api.openaerialmap.org/meta/?gsd_from=0.01&gsd_to=0.05

Answer 2

@Geordie: your self-answer isn't quite correct:

I noticed that the API doesn't distinguish between GSD in geographic or projected coordinates systems. For example, you may see some very small units e.g. 1e-7 - turns out these are in degrees. If you load them into something like rasterio you can check the CRS to confirm. Other times the gsd parameter is correct.

This is a bit frustrating because it means you can't query GSD in quite the way you'd like. You can filter on e.g. GSD > 1e-3 which should get rid of geographic GSDs, if you don't care about throwing away some data.

What I would recommend is converting the metadata to something like EPSG:3395 (which is in metres) and filtering on that. For example, in Python:

import rasterio
from rasterio.warp import calculate_default_transform

# World Mercator
dst_crs = "EPSG:3395"
img = "575fcf142b67227a79b4fbfd.tif"

with rasterio.open(img) as src:
    transform, width, height = calculate_default_transform(
        src.crs, dst_crs, src.width, src.height, *src.bounds)
    kwargs = src.meta.copy()
    kwargs.update({
        'crs': dst_crs,
        'transform': transform,
        'width': width,
        'height': height
    })

print(transform[0])

> 0.0206139627341944

Up to you how to do that at scale, you'd need to download all the metadata and import it somewhere else. Probably this should be raised with the OAM team so they can provide consistent metadata to images, or at least have a gsd_units tag.

This example is taken from the rasterio docs.