Skip to content

ARD Selects

The ARD Select system helps you find the right ARD tiles from Maxar's vast catalog of imagery. It's like a search engine for tiles, but it does more than just list out results:

  • Selects also score candidate tiles to give you the best matches within each grid cell
  • Selects generate helpful results files, from GeoJSON to a fully functional HTML viewer

To run Selects from Python the SDK has a Select object that represents a Select and its interaction with the API.

Note that Maxar ARD also has a Metadata API that also can search tiles, but doesn't do any scoring or generate output files. It can work better for programmatic access where lighter and faster results are advantageous. Both search methods use similar inputs so we suggest starting with Selects as an introduction to searching for ARD tiles.

from max_ard import Select

Selects require either some kind of geographic Area of Interest, or list of one or more Acquistion IDs to use. For this notebook we'll use a bounding box over Albuquerque, New Mexico. We'll also add a date range.

bbox = [-106.8, 35.1, -106.4, 35.4]
datetime =  "2020-07-01T00:00:00Z/2021-01-25T00:00:00Z"

The Select System also lets you filter on metadata fields. The Select API expects filter queries in this JSON object structure (here as a Python dictionary). For a full list of properties and operators you can use to build queries, see the Select API documentation

query = {
        "platform": {
          "eq": "worldview-02"
        },

        "aoi:cloud_free_percentage": {
          "gte": 95
        },
        "aoi:data_percentage": {
          "gte": 75
        }
    }

This query sets three filters for the select system to use to pick tiles. They are, in order:

  • The platform (a satellite or constellation of satellites) must be Worldview 2
  • The tile must be at least 95% free of clouds within the supplied Area of Interest (the bbox)
  • The AOI must also be at least 75% full of valid data pixels

The call signature for a Select includes the following keyword arguments:

  • acq_ids: An iterable of acquisition IDs to search for.
  • datetime: A datetime string or range:
    • single date: “2020-10-26T13:00:00Z”
    • range: use a slash “2019-10-25T09:00:00Z/2020-10-26T13:00:00Z”
    • open-ended range: use two dots and a slash “../2020-10-26T13:00:00Z”
  • intersects: A WGS-84 geometry to limit the search to. Can be WKT or GeoJSON strings, most Python objects that support geometry, or a file path to an OGR-readable format.
  • bbox: A 4-tuple of the WGS84 bounding box to limit the search to, in the form [XMIN, YMIN, XMAX, YMAX]
  • query: API query JSON as a Python dictionary
  • stack_depth: Limits the number of tiles returned per grid cell. When searching the tiles are ranked and the best scoring tiles will be used to return this number of tiles. Default is 5 tiles.

We'll create a Select using the datetime, bbox, and query we defined. We'll also add a stack depth of 3.

s = Select(datetime=datetime, bbox=bbox, query=query, stack_depth=3)

Let's take a look at Selects:

Properties of the Select object

A Select has the following properties after it is created:

  • request: A container object storing the request options.

After the Select has been submitted with .submit(), the following properties can be used:

  • select_id: The Select ID assigned to the request
  • finished: Boolean if the Select has finished running
  • state: state of the select process: 'RUNNING', 'SUCCEEDED', or 'FAILED'

Once the Select has finished, these properties are available:

  • response: A container object of the API response
  • usage: A convenience property for the data usage section of the Select response
  • results: A SelectResults object that for examining the Select response

Methods of the Select object

  • submit(): submits the select
  • get_link_contents(name) Gets the contents of one of the results files, where name can be stac, html, geojson, or geojsonl
  • copy_file(name, dir='.') Copies a result file locally, where name can be stac, html, geojson, or geojsonl. The file's name will be <select id>.<name>, and can be written to the optional location dir. If dir is not provided it will default to the current working directory.
  • get_signed_link(name) Gets a signed link for a result file, where name can be stac, html, geojson, or geojsonl. Note: do not use an authenticated session from get_session() to download signed links.

Since we have not submitted the request yet, the only property we can access is the request we are going to send. Trying to access other properties or methods will raise a NotSubmitted error.

from max_ard.exceptions import NotSubmitted
print(s.request)
try:
    print(s.state)
except NotSubmitted:
    print('The Select has not been submitted yet and does not have a state')
ids=None datetime='2020-07-01T00:00:00Z/2021-01-25T00:00:00Z' stack_depth=3 intersects=None bbox=[-106.8, 35.1, -106.4, 35.4] query={'platform': {'eq': 'worldview-02'}, 'aoi:cloud_free_percentage': {'gte': 95}, 'aoi:data_percentage': {'gte': 75}} image_age_category=None
The Select has not been submitted yet and does not have a state

We can submit the Select query. Once the Select is submitted to the API it will have a state and a select_id. Select requests will try to return a response within 20 seconds. If the results can not be computed in that time only a job number is returned. The Select object handles this internally.

s.submit()
print(s.state)
print(s.select_id)
SUCCEEDED
5710215560120474041

Select.wait_for_success() will poll the API to see if the Select has completed:

s.wait_for_success()
print(f'Select {s.select_id} is complete')
Select 5710215560120474041 is complete

To create a Select object from ID, use the from_id classmethod:

s = Select.from_id('5629729628519955012')
<ARD Select 5629729628519955012>

Select Result Files

A completed Select process generates output files. These are:

  • .html: an interative map of the results
  • .geojson: A GeoJSON FeatureCollection of ARD grid tiles and which acquisitions fulfill the query for that cell
  • .geojsonl: A GeoJSON Line representation of the above
  • .stac: A Spatio-Temporal Asset Catalog (STAC) of all the ARD tiles found in the search

To access the contents of one of the results files, use get_link_contents(name):

geojson = s.get_link_contents('geojson')
print(geojson[:100] + '...')
{
"type": "FeatureCollection",
"features": [{
  "type": "Feature",
  "geometry": {
    "type": "Poly...

To copy the file locally, use copy_file(name):

from os import listdir
s.copy_file('geojson')
listdir('.')
['examples.md',
 'ARDCollections.ipynb',
 'Ordering_ARD.ipynb',
 'select-browse.html',
 'Selecting_ARD.ipynb',
 'select_template.py',
 'outputs.md',
 '5579684549227101409.geojson',
 'SDK_Quickstart.ipynb',
 '.ipynb_checkpoints',
 '5579682711031350580.geojson',
 'my_select.geojson',
 '5573250050575359338.geojson',
 'Authentication.ipynb']

You can also get a temporary signed link for any result file. Note that these signed links should not be downloaded from an authenticated Requests session.

link = s.get_signed_link('html')
print(link)

Data Usage

You can find the data usage a Select would incur if ordered in .usage

Usage is stored in a usage object with nested attributes about data usage and account limits. The attributes include total usage as well as per image age category.

Two attributes describe usage. When running a select, the usage amount is estimated and the boolean estimate attribute will be True. Usage objects attached to finished orders show the actual amount of usage and estimate will be False.

area:

  • fresh_imagery_sqkm
  • standard_imagery_sqkm
  • training_imagery_sqkm
  • total_imagery_sqkm
  • estimate

cost:

  • fresh_imagery_cost
  • standard_imagery_cost
  • training_imagery_cost
  • total_imagery_cost
  • estimate

Another two attributes show account usage and limits. For Selects, usage available reflects what is available when the Select is run, not what would remain if the Select was ordered.

limits:

  • limit_sqkm
  • annual_subscription_fee_limit
  • fresh_imagery_fee_limit
  • standard_imagery_fee_limit
  • training_imagery_fee_limit

available:

  • available_sqkm
  • total_imagery_balance
  • fresh_imagery_balance
  • standard_imagery_balance
  • training_imagery_balance

For example, to get the total estimated cost of the imagery returned by a Select:

s.usage.cost.total_imagery_cost
24.0

Usage objects also have a formatted __str__ representation:

print(s.usage)
 Data Usage
 ----------

  Account limit: unlimited sq.km ($unlimited)

  Imagery ordered: 2317.0 sq.km ($24.0)
  ├ Fresh (< 90 days): 0.0 sq.km ($0.0)
  ├ Standard (90 days - 3 years): 2317.0 sq.km ($24.0)
  └ Training (> 3 years): 0.0 sq.km ($0.0)

  Remaining balance: unlimited sq.km ($unlimited)

Select Results

The Results object provides convenient access to Select results.

results = s.results
print(results)
<SelectResult (95 tiles in 12 acquisitions) >

Results support the Python Geospatial interface and can be loaded by Shapely and other libraries

from shapely.geometry import shape
shape(results)

Results have a list of dates, as well as start and end dates:

results.dates
['2020-07-10',
 '2020-07-24',
 '2020-07-29',
 '2020-09-08',
 '2020-10-21',
 '2021-01-16']
results.start_date, results.end_date
('2020-07-10', '2021-01-16')

To access all the tiles in the results:

results.tiles
[<SelectTile of 10300100B3841C00 at Z13-031133231113>,
 <SelectTile of 10300100B3841C00 at Z13-031133231131>,
 <SelectTile of 10300100B3841C00 at Z13-031133231133>,
 <SelectTile of 10300100B3841C00 at Z13-031133231311>,
 <SelectTile of 10300100B3841C00 at Z13-031133231313>,
 <SelectTile of 10300100B3841C00 at Z13-031133231331>,
 <SelectTile of 10300100AC94D700 at Z13-031133320001>,
 <SelectTile of 10300100AA1C6800 at Z13-031133320001>,
 <SelectTile of 10300100B2B49700 at Z13-031133320002>,
 <SelectTile of 10300100B2B49700 at Z13-031133320003>,
 <SelectTile of 10300100AC94D700 at Z13-031133320003>,
 <SelectTile of 10300100AA1C6800 at Z13-031133320003>,
 <SelectTile of 10300100AC94D700 at Z13-031133320010>,
 <SelectTile of 10300100AA1C6800 at Z13-031133320010>,
 <SelectTile of 10300100AC94D700 at Z13-031133320011>,
 <SelectTile of 10300100AA1C6800 at Z13-031133320011>,
 <SelectTile of 10300100B2B49700 at Z13-031133320012>,
 <SelectTile of 10300100AC94D700 at Z13-031133320012>,
 <SelectTile of 10300100AA1C6800 at Z13-031133320012>,
 <SelectTile of 10300100B39ACD00 at Z13-031133320013>,
 <SelectTile of 10300100AC94D700 at Z13-031133320013>,
 <SelectTile of 10300100AA1C6800 at Z13-031133320013>,
 <SelectTile of 10300100B2B49700 at Z13-031133320020>,
 <SelectTile of 10300100B2B49700 at Z13-031133320021>,
 <SelectTile of 10300100AC94D700 at Z13-031133320021>,
 <SelectTile of 10300100AA1C6800 at Z13-031133320021>,
 <SelectTile of 10300100B2B49700 at Z13-031133320022>,
 <SelectTile of 10300100B2B49700 at Z13-031133320023>,
 <SelectTile of 10300100AC94D700 at Z13-031133320023>,
 <SelectTile of 10300100AA1C6800 at Z13-031133320023>,
 <SelectTile of 10300100AC94D700 at Z13-031133320030>,
 <SelectTile of 10300100AA1C6800 at Z13-031133320030>,
 <SelectTile of 10300100AB101A00 at Z13-031133320030>,
 <SelectTile of 10300100B39ACD00 at Z13-031133320031>,
 <SelectTile of 10300100AC94D700 at Z13-031133320031>,
 <SelectTile of 10300100AA1C6800 at Z13-031133320031>,
 <SelectTile of 10300100AC94D700 at Z13-031133320032>,
 <SelectTile of 10300100AA1C6800 at Z13-031133320032>,
 <SelectTile of 10300100AB101A00 at Z13-031133320032>,
 <SelectTile of 10300100AC94D700 at Z13-031133320033>,
 <SelectTile of 10300100AA1C6800 at Z13-031133320033>,
 <SelectTile of 10300100AB101A00 at Z13-031133320033>,
 <SelectTile of 10300100B39ACD00 at Z13-031133320102>,
 <SelectTile of 10300100B39ACD00 at Z13-031133320103>,
 <SelectTile of 10300100B39ACD00 at Z13-031133320120>,
 <SelectTile of 10300100B39ACD00 at Z13-031133320121>,
 <SelectTile of 10300100B39ACD00 at Z13-031133320122>,
 <SelectTile of 10300100B39ACD00 at Z13-031133320123>,
 <SelectTile of 10300100B2B49700 at Z13-031133320200>,
 <SelectTile of 10300100B2B49700 at Z13-031133320201>,
 <SelectTile of 10300100AC94D700 at Z13-031133320201>,
 <SelectTile of 10300100AA1C6800 at Z13-031133320201>,
 <SelectTile of 10300100B2B49700 at Z13-031133320202>,
 <SelectTile of 10300100B2B49700 at Z13-031133320203>,
 <SelectTile of 10300100AC94D700 at Z13-031133320203>,
 <SelectTile of 10300100AA1C6800 at Z13-031133320203>,
 <SelectTile of 10300100AC94D700 at Z13-031133320210>,
 <SelectTile of 10300100AA1C6800 at Z13-031133320210>,
 <SelectTile of 10300100AB101A00 at Z13-031133320210>,
 <SelectTile of 10300100AC94D700 at Z13-031133320211>,
 <SelectTile of 10300100AA1C6800 at Z13-031133320211>,
 <SelectTile of 10300100AB101A00 at Z13-031133320211>,
 <SelectTile of 10300100AC94D700 at Z13-031133320212>,
 <SelectTile of 10300100AA1C6800 at Z13-031133320212>,
 <SelectTile of 10300100AB101A00 at Z13-031133320212>,
 <SelectTile of 10300100B39ACD00 at Z13-031133320213>,
 <SelectTile of 10300100AD437400 at Z13-031133320213>,
 <SelectTile of 10300100AC700900 at Z13-031133320213>,
 <SelectTile of 10300100B2B49700 at Z13-031133320220>,
 <SelectTile of 10300100ACCDAB00 at Z13-031133320220>,
 <SelectTile of 10300100A9547600 at Z13-031133320220>,
 <SelectTile of 10300100B2B49700 at Z13-031133320221>,
 <SelectTile of 10300100ACCDAB00 at Z13-031133320221>,
 <SelectTile of 10300100A9547600 at Z13-031133320221>,
 <SelectTile of 10300100ACCDAB00 at Z13-031133320230>,
 <SelectTile of 10300100A9547600 at Z13-031133320230>,
 <SelectTile of 10300100AC94D700 at Z13-031133320230>,
 <SelectTile of 10300100AD437400 at Z13-031133320231>,
 <SelectTile of 10300100AC700900 at Z13-031133320231>,
 <SelectTile of 10300100AC94D700 at Z13-031133320231>,
 <SelectTile of 10300100A9CC9200 at Z13-031133320300>,
 <SelectTile of 10300100B39ACD00 at Z13-031133320300>,
 <SelectTile of 10300100A9CC9200 at Z13-031133320301>,
 <SelectTile of 10300100B39ACD00 at Z13-031133320302>,
 <SelectTile of 10300100AD437400 at Z13-031133320302>,
 <SelectTile of 10300100AC700900 at Z13-031133320302>,
 <SelectTile of 10300100AD437400 at Z13-031133320303>,
 <SelectTile of 10300100AC700900 at Z13-031133320303>,
 <SelectTile of 10300100A9CC9200 at Z13-031133320303>,
 <SelectTile of 10300100AD437400 at Z13-031133320320>,
 <SelectTile of 10300100AC700900 at Z13-031133320320>,
 <SelectTile of 10300100A9CC9200 at Z13-031133320320>,
 <SelectTile of 10300100AD437400 at Z13-031133320321>,
 <SelectTile of 10300100AC700900 at Z13-031133320321>,
 <SelectTile of 10300100A67D3100 at Z13-031133320321>]

A stack is a collection of all of the ARD tiles covering a given cell. We can look at all of the stacks via .stacks:

results.stacks
[<Stack at Z13-031133231113 [<SelectTile of 10300100B3841C00>]>,
 <Stack at Z13-031133231131 [<SelectTile of 10300100B3841C00>]>,
 <Stack at Z13-031133231133 [<SelectTile of 10300100B3841C00>]>,
 <Stack at Z13-031133231311 [<SelectTile of 10300100B3841C00>]>,
 <Stack at Z13-031133231313 [<SelectTile of 10300100B3841C00>]>,
 <Stack at Z13-031133231331 [<SelectTile of 10300100B3841C00>]>,
 <Stack at Z13-031133320001 [<SelectTile of 10300100AC94D700>, <SelectTile of 10300100AA1C6800>]>,
 <Stack at Z13-031133320002 [<SelectTile of 10300100B2B49700>]>,
 <Stack at Z13-031133320003 [<SelectTile of 10300100B2B49700>, <SelectTile of 10300100AC94D700>, <SelectTile of 10300100AA1C6800>]>,
 <Stack at Z13-031133320010 [<SelectTile of 10300100AC94D700>, <SelectTile of 10300100AA1C6800>]>,
 <Stack at Z13-031133320011 [<SelectTile of 10300100AC94D700>, <SelectTile of 10300100AA1C6800>]>,
 <Stack at Z13-031133320012 [<SelectTile of 10300100B2B49700>, <SelectTile of 10300100AC94D700>, <SelectTile of 10300100AA1C6800>]>,
 <Stack at Z13-031133320013 [<SelectTile of 10300100B39ACD00>, <SelectTile of 10300100AC94D700>, <SelectTile of 10300100AA1C6800>]>,
 <Stack at Z13-031133320020 [<SelectTile of 10300100B2B49700>]>,
 <Stack at Z13-031133320021 [<SelectTile of 10300100B2B49700>, <SelectTile of 10300100AC94D700>, <SelectTile of 10300100AA1C6800>]>,
 <Stack at Z13-031133320022 [<SelectTile of 10300100B2B49700>]>,
 <Stack at Z13-031133320023 [<SelectTile of 10300100B2B49700>, <SelectTile of 10300100AC94D700>, <SelectTile of 10300100AA1C6800>]>,
 <Stack at Z13-031133320030 [<SelectTile of 10300100AC94D700>, <SelectTile of 10300100AA1C6800>, <SelectTile of 10300100AB101A00>]>,
 <Stack at Z13-031133320031 [<SelectTile of 10300100B39ACD00>, <SelectTile of 10300100AC94D700>, <SelectTile of 10300100AA1C6800>]>,
 <Stack at Z13-031133320032 [<SelectTile of 10300100AC94D700>, <SelectTile of 10300100AA1C6800>, <SelectTile of 10300100AB101A00>]>,
 <Stack at Z13-031133320033 [<SelectTile of 10300100AC94D700>, <SelectTile of 10300100AA1C6800>, <SelectTile of 10300100AB101A00>]>,
 <Stack at Z13-031133320102 [<SelectTile of 10300100B39ACD00>]>,
 <Stack at Z13-031133320103 [<SelectTile of 10300100B39ACD00>]>,
 <Stack at Z13-031133320120 [<SelectTile of 10300100B39ACD00>]>,
 <Stack at Z13-031133320121 [<SelectTile of 10300100B39ACD00>]>,
 <Stack at Z13-031133320122 [<SelectTile of 10300100B39ACD00>]>,
 <Stack at Z13-031133320123 [<SelectTile of 10300100B39ACD00>]>,
 <Stack at Z13-031133320200 [<SelectTile of 10300100B2B49700>]>,
 <Stack at Z13-031133320201 [<SelectTile of 10300100B2B49700>, <SelectTile of 10300100AC94D700>, <SelectTile of 10300100AA1C6800>]>,
 <Stack at Z13-031133320202 [<SelectTile of 10300100B2B49700>]>,
 <Stack at Z13-031133320203 [<SelectTile of 10300100B2B49700>, <SelectTile of 10300100AC94D700>, <SelectTile of 10300100AA1C6800>]>,
 <Stack at Z13-031133320210 [<SelectTile of 10300100AC94D700>, <SelectTile of 10300100AA1C6800>, <SelectTile of 10300100AB101A00>]>,
 <Stack at Z13-031133320211 [<SelectTile of 10300100AC94D700>, <SelectTile of 10300100AA1C6800>, <SelectTile of 10300100AB101A00>]>,
 <Stack at Z13-031133320212 [<SelectTile of 10300100AC94D700>, <SelectTile of 10300100AA1C6800>, <SelectTile of 10300100AB101A00>]>,
 <Stack at Z13-031133320213 [<SelectTile of 10300100B39ACD00>, <SelectTile of 10300100AD437400>, <SelectTile of 10300100AC700900>]>,
 <Stack at Z13-031133320220 [<SelectTile of 10300100B2B49700>, <SelectTile of 10300100ACCDAB00>, <SelectTile of 10300100A9547600>]>,
 <Stack at Z13-031133320221 [<SelectTile of 10300100B2B49700>, <SelectTile of 10300100ACCDAB00>, <SelectTile of 10300100A9547600>]>,
 <Stack at Z13-031133320230 [<SelectTile of 10300100ACCDAB00>, <SelectTile of 10300100A9547600>, <SelectTile of 10300100AC94D700>]>,
 <Stack at Z13-031133320231 [<SelectTile of 10300100AD437400>, <SelectTile of 10300100AC700900>, <SelectTile of 10300100AC94D700>]>,
 <Stack at Z13-031133320300 [<SelectTile of 10300100A9CC9200>, <SelectTile of 10300100B39ACD00>]>,
 <Stack at Z13-031133320301 [<SelectTile of 10300100A9CC9200>]>,
 <Stack at Z13-031133320302 [<SelectTile of 10300100B39ACD00>, <SelectTile of 10300100AD437400>, <SelectTile of 10300100AC700900>]>,
 <Stack at Z13-031133320303 [<SelectTile of 10300100AD437400>, <SelectTile of 10300100AC700900>, <SelectTile of 10300100A9CC9200>]>,
 <Stack at Z13-031133320320 [<SelectTile of 10300100AD437400>, <SelectTile of 10300100AC700900>, <SelectTile of 10300100A9CC9200>]>,
 <Stack at Z13-031133320321 [<SelectTile of 10300100AD437400>, <SelectTile of 10300100AC700900>, <SelectTile of 10300100A67D3100>]>]

An Acquisition is a collection of all of the ARD tiles from a common acquisition. All of the acquisitions in a stack can be accessed via .acquisitions:

results.acquisitions
[<Acquisition of 10300100B3841C00 [<SelectTile at Z13-031133231113>, <SelectTile at Z13-031133231131>, <SelectTile at Z13-031133231133>, <SelectTile at Z13-031133231311>, <SelectTile at Z13-031133231313>, <SelectTile at Z13-031133231331>]>,
 <Acquisition of 10300100AC94D700 [<SelectTile at Z13-031133320001>, <SelectTile at Z13-031133320003>, <SelectTile at Z13-031133320010>, <SelectTile at Z13-031133320011>, <SelectTile at Z13-031133320012>, <SelectTile at Z13-031133320013>, <SelectTile at Z13-031133320021>, <SelectTile at Z13-031133320023>, <SelectTile at Z13-031133320030>, <SelectTile at Z13-031133320031>, <SelectTile at Z13-031133320032>, <SelectTile at Z13-031133320033>, <SelectTile at Z13-031133320201>, <SelectTile at Z13-031133320203>, <SelectTile at Z13-031133320210>, <SelectTile at Z13-031133320211>, <SelectTile at Z13-031133320212>, <SelectTile at Z13-031133320230>, <SelectTile at Z13-031133320231>]>,
 <Acquisition of 10300100AA1C6800 [<SelectTile at Z13-031133320001>, <SelectTile at Z13-031133320003>, <SelectTile at Z13-031133320010>, <SelectTile at Z13-031133320011>, <SelectTile at Z13-031133320012>, <SelectTile at Z13-031133320013>, <SelectTile at Z13-031133320021>, <SelectTile at Z13-031133320023>, <SelectTile at Z13-031133320030>, <SelectTile at Z13-031133320031>, <SelectTile at Z13-031133320032>, <SelectTile at Z13-031133320033>, <SelectTile at Z13-031133320201>, <SelectTile at Z13-031133320203>, <SelectTile at Z13-031133320210>, <SelectTile at Z13-031133320211>, <SelectTile at Z13-031133320212>]>,
 <Acquisition of 10300100B2B49700 [<SelectTile at Z13-031133320002>, <SelectTile at Z13-031133320003>, <SelectTile at Z13-031133320012>, <SelectTile at Z13-031133320020>, <SelectTile at Z13-031133320021>, <SelectTile at Z13-031133320022>, <SelectTile at Z13-031133320023>, <SelectTile at Z13-031133320200>, <SelectTile at Z13-031133320201>, <SelectTile at Z13-031133320202>, <SelectTile at Z13-031133320203>, <SelectTile at Z13-031133320220>, <SelectTile at Z13-031133320221>]>,
 <Acquisition of 10300100B39ACD00 [<SelectTile at Z13-031133320013>, <SelectTile at Z13-031133320031>, <SelectTile at Z13-031133320102>, <SelectTile at Z13-031133320103>, <SelectTile at Z13-031133320120>, <SelectTile at Z13-031133320121>, <SelectTile at Z13-031133320122>, <SelectTile at Z13-031133320123>, <SelectTile at Z13-031133320213>, <SelectTile at Z13-031133320300>, <SelectTile at Z13-031133320302>]>,
 <Acquisition of 10300100AB101A00 [<SelectTile at Z13-031133320030>, <SelectTile at Z13-031133320032>, <SelectTile at Z13-031133320033>, <SelectTile at Z13-031133320210>, <SelectTile at Z13-031133320211>, <SelectTile at Z13-031133320212>]>,
 <Acquisition of 10300100AD437400 [<SelectTile at Z13-031133320213>, <SelectTile at Z13-031133320231>, <SelectTile at Z13-031133320302>, <SelectTile at Z13-031133320303>, <SelectTile at Z13-031133320320>, <SelectTile at Z13-031133320321>]>,
 <Acquisition of 10300100AC700900 [<SelectTile at Z13-031133320213>, <SelectTile at Z13-031133320231>, <SelectTile at Z13-031133320302>, <SelectTile at Z13-031133320303>, <SelectTile at Z13-031133320320>, <SelectTile at Z13-031133320321>]>,
 <Acquisition of 10300100ACCDAB00 [<SelectTile at Z13-031133320220>, <SelectTile at Z13-031133320221>, <SelectTile at Z13-031133320230>]>,
 <Acquisition of 10300100A9547600 [<SelectTile at Z13-031133320220>, <SelectTile at Z13-031133320221>, <SelectTile at Z13-031133320230>]>,
 <Acquisition of 10300100A9CC9200 [<SelectTile at Z13-031133320300>, <SelectTile at Z13-031133320301>, <SelectTile at Z13-031133320303>, <SelectTile at Z13-031133320320>]>,
 <Acquisition of 10300100A67D3100 [<SelectTile at Z13-031133320321>]>]

Acquisitions

Acquisitions is a list and can be iterated or indexed. You can also get a specific acquisition from the results using get_acquisition() and an acquisition ID.

acquisition = results.acquisitions[0]
acquisition
<Acquisition of 10300100B3841C00 [<SelectTile at Z13-031133231113>, <SelectTile at Z13-031133231131>, <SelectTile at Z13-031133231133>, <SelectTile at Z13-031133231311>, <SelectTile at Z13-031133231313>, <SelectTile at Z13-031133231331>]>
results.get_acquisition('10300100B3841C00')
<Acquisition of 10300100B3841C00 [<SelectTile at Z13-031133231113>, <SelectTile at Z13-031133231131>, <SelectTile at Z13-031133231133>, <SelectTile at Z13-031133231311>, <SelectTile at Z13-031133231313>, <SelectTile at Z13-031133231331>]>

Acquisition objects also have a shorter str representation:

print(acquisition)
<Acquisition at 10300100B3841C00 (6 tiles)>

They also support the Python Geospatial Interface:

shape(acquisition)

As well as have some summary properties:

acquisition.properties
{'acquisition_id': '10300100B3841C00',
 'platform': 'worldview-02',
 'datetime': '2021-01-16T18:02:57.170983Z'}

Stacks

Stacks have similar qualities with the exception of properties:

stack = results.stacks[0]
stack
<Stack at Z13-031133231113 [<SelectTile of 10300100B3841C00>]>
results.get_stack('Z13-031133231113')
<Stack at Z13-031133231113 [<SelectTile of 10300100B3841C00>]>
print(stack)
<Stack at Z13-031133231113 (1 tiles)>
shape(stack)

Tiles

A SelectTile object represents an ARD Tile picked by the Select service.

Stack and Acquisition objects are also lists, and you can also get a specific tile from a SelectResult by acquisition ID and cell:

tile = stack[0]
tile
<SelectTile of 10300100B3841C00 at Z13-031133231113>
results.get_tile('10300100B3841C00', 'Z13-031133231113')
<SelectTile of 10300100B3841C00 at Z13-031133231113>

You can also get tiles from Stacks and Acquisitions:

print(stack.get_tile_from_acquisition('10300100B3841C00'))
print(acquisition.get_tile_from_cell('Z13-031133231113'))    
<SelectTile of 10300100B3841C00 at Z13-031133231113>
<SelectTile of 10300100B3841C00 at Z13-031133231113>

A SelectTile has attributes for the acquisition ID, the maxar_canvas_grid Cell object it covers, and a properties with image metadata. Like the other objects it supports the Python Geospatial Protocol:

tile.acq_id, tile.cell
('10300100B3841C00', <Cell Z13-031133231113>)
tile.properties
{'off_nadir_min': 7.4760494,
 'view:sun_azimuth': 159.54324333333332,
 'acquisition_id': '10300100B3841C00',
 'pan_resolution_max': 0.47500458,
 'date': '2021-01-16',
 'datetime': '2021-01-16T18:02:57.170983Z',
 'constellation': 'digitalglobe',
 'tile:cloud_free_percentage': 100.0,
 'id': '10300100B3841C00',
 'pan_resolution_avg': 0.47164591166666664,
 'pan_resolution_min': 0.47035816,
 'modified': '2021-01-16T19:41:09Z',
 'view:sun_elevation': 31.5245595,
 'tile:cloud_percentage': 0.0,
 'multi_resolution_avg': 1.8871270166666667,
 'multi_resolution_min': 1.8817121,
 'view:off_nadir': 8.159726833333334,
 'tile:data_percentage': 100.0,
 'off_nadir_max': 9.683383,
 'tile:cloud_polys': None,
 'platform': 'worldview-02',
 'multi_resolution_max': 1.9010458,
 'eo:cloud_cover': 1.3208534224506887,
 'tile:quadkey': '031133231113',
 'view:azimuth': 111.309445,
 'instruments': ['VNIR'],
 'tile:zone': 13.0,
 'wkt': 'POLYGON ((-106.760190051784 35.32043318486422, -106.8151717549975 35.31962004905451, -106.8161802274594 35.36468200254137, -106.761168016614 35.36549648670249, -106.760190051784 35.32043318486422))',
 'tile:no_data_percentage': 0.0,
 'aoi:data_area_sqkm': 17.877,
 'aoi:data_percentage': 100,
 'aoi:cloud_free_percentage': 100}
shape(tile)

Back to top