Skip to content

max-ard CLI

Select Tools

The ARD Select service allows you to search and filter acquisitions. It provides results in several different file formats.

max-ard select

The base command for Select tools. Run this by itself to see all of the Select subcommands.

max-ard select submit

Usage: max-ard select submit [OPTIONS]

Submit a select request to search for ARD imagery and estimate usage.

Options:

  • --acq-id Limit the Select to these acquisition IDs. Can be provided multiple times.

  • --datetime Limit the Select to a given date or date range.

  • --intersects Search for tiles that intersect this geometry. Can be WKT, GeoJSON or a path to a file, see below.

  • --bbox like intersects, but limits search to a WGS84 bounding box in format --bbox XMIN YMIN XMAX YMAX

  • --stack-depth Limits the number of tiles returned. When searching the tiles are ranked and the best scoring tiles will be used to return this number of tiles. Default is 5 tiles.

  • --filter Add a filter statement in the form of --filter <property> <operator> <value>. See the Select API documentation for a list of properties and operators.

  • --image-age Limit imagery to an image age category ('fresh', 'standard', or 'training'). Can be used more than once if age ranges are contiguous.

  • --min-cloud-free Shortcut to filter the minimum percentage of cloud-free cover. Equivalent to filtering aoi:cloud_free_percentage greater than or equal to the supplied value.

  • --min-data Shortcut to filter the minimum percentage of valid data pixels. Equivalent to filtering on aoi:data_percentage greater than or equal to the supplied value.

  • --bba Only select images that can be used with Block Bundle Adjustment.

  • --verbose, -v Output more information about the select, such as the raw payload. Useful for troubleshooting.

At a minimum, you must supply at least one of the following:

  • a spatial filter using intersects or bbox
  • specific acquisition ID or IDs using --acq-id at least once
% max-ard select submit \
  --bbox -104.9 39.7 -104.5 39.9 \
  --filter platform eq worldview-02 \
  --filter aoi:cloud_free_percentage gt 95

The Select service will try to compute results within 20 seconds. If it takes longer than 20 seconds the command will return a job ID that you can check for completion with max-ard select status SELECT_ID.

Intersects Inputs

The --intersects parameter can be a WKT or GeoJSON string, or a path to a WKT or GeoJSON file. If Fiona is installed, most common geospatial file formats can also be read.

Note: only POLYGON and MULTIPOLYGON geometry types are accepted. Geometries with a large number of vertices may exceed the maximum HTTP POST size. For complex AOIs, We recommend simplifying the geometry first or using the bounding box of the input and the --bbox parameter instead.

Geometries must be submitted in WGS84 units.

max-ard select status

Usage: max-ard select status SELECT_ID

Check status of a running selection query given a select ID.

States are:

  • RUNNING
  • SUCCEEDED
  • FAILED
% max-ard select status 5568159187953882262

max-ard select describe

Usage: max-ard select submit SELECT_ID [OPTIONS]

Returns information about the Select given the SELECT_ID.

Options:

--dest Saves the output to a file path in the format specified by the file extension. Formats stac, geojson, and geojsonl, kml, kmz, and shp write files describing the tiles. Format html is an interactive map browser of the results - to view the map without downloading it first, use maxard select browse SELECT_ID.

--format If --dest is not provided, outputs to stdout in these formats : html, geojsonl, kml, or stac. Ignored if --dest is used.

--verbose , -v Outputs more information about the Select such as the request payload sent to the API. Useful for troubleshooting. Ignored if --format or --dest is supplied.

% max-ard select describe 5568184876815431013
getting Select ID 5568184876815431013
*******************
Request details:
{"datetime": "2020-07-01T09:00:00Z/2021-01-25T09:00:00Z", "stack_depth": 3, "query": {"platform": {"eq": "worldview-02"}, "aoi:cloud_free_percentage": {"gte": 95.0}, "aoi:data_percentage": {"gte": 75.0}}, "bbox": [-105.1, 39.7, -104.7, 39.9]}
*******************
97 tiles identified in the following 18 acquisitions:
10300100AE766C00 (2020-11-01) - 16 tiles
10300100B09E5F00 (2020-12-15) - 2 tiles
10300100B18AB600 (2021-01-05) - 2 tiles
10300100B4496100 (2020-12-31) - 2 tiles
10300100B3522C00 (2020-12-17) - 2 tiles
10300100AD73AD00 (2020-09-24) - 1 tiles
10300100B00C7500 (2020-12-31) - 16 tiles
10300100B104E700 (2020-12-09) - 14 tiles
10300100AD977C00 (2020-11-01) - 4 tiles
10300100B3366B00 (2021-01-19) - 12 tiles
10300100AFA65D00 (2020-11-12) - 5 tiles
10300100B1D7A700 (2020-12-20) - 2 tiles
10300100ADA54B00 (2020-10-16) - 4 tiles
10300100AD983700 (2020-08-01) - 4 tiles
10300100AEBA9700 (2020-10-11) - 4 tiles
10300100A99E1000 (2020-07-27) - 2 tiles

Saving the Select as a GeoJSON file named my_select.geojson:

% max-ard select describe 5568159187953882262 --dest my_select.geojson

Piping a Select to PostGIS using ogr2ogr:

% max-ard select describe 5568159187953882262 --format geojson | ogr2ogr -f "PostgreSQL" PG:"<connection info>" /vsistdin/

max-ard select url

Usage: max-ard select url SELECT_ID [--FORMAT]

Gets links for the Select result files for a Select of SELECT_ID. If no FORMAT is supplied, returns the base URL of the Select. If a FORMAT is supplied, returns a pre-signed URL to download the result of type FORMAT (stac, geojson, geojsonl, and html)

% max-ard select url 5568159187953882262
https://ard.maxar.com/api/select/5568159187953882262

% max-ard select url 5568159187953882262 --format html
<long pre-signed url>

max-ard select browse

Usage: max-ard select browse SELECT_ID

Downloads the HTML interactive viewer of the Select result SELECT ID to a temporary file and opens the map with the system web browser.

When exited the temporary file is deleted. Use max-ard select describe SELECT_ID --format html > my_map.html to save a local copy.

An example of the HTML viewer can be found in the output examples here.

% max-ard select browse 5568159187953882262
Fetching map...
Press any key when finished
Back to top