Skip to content

Select Resource

Last updated: August 29, 2022


Select

/select
Select imagery to order, get the status of a select request, and download the output files from a select request.

See also: Selecting Imagery User Guide

Select endpoints

http method path name description
POST /select Select ARD imagery Select imagery to order by query criteria or acquisition IDs.
GET /select/request/{select_id} Get Selection details Get the status and details of an imagery selection request.
GET /select/files/{select_id.extension} Download a Select File Get a "select" file to download by extension type.

Headers

key value description
Authorization Bearer {{token}} Authentication method for ARD API requests.
Content-Type application/json Applies to POST, PATCH, PUT requests, which require a JSON body.

Select imagery

POST /select
Select imagery by criteria or by acquisition IDs with an optional AOI. Examples of "search by criteria" and "search by Acquisition ID" requests are provided below.

Select imagery by criteria

Select imagery that matches a set of criteria.

Request body

parameter required description example
ids optional A list of acquisition IDs. A list of acquisition IDs can optionally be constrained by an AOI. "ids": ["10300100B3841C00", "10300100AB101A00"]
bbox optional, but required if intersects value is not supplied The "select image by criteria" request requires an AOI in either the "intersects" or "bbox" field. "bbox": [-106.8, 35.1, -106.4, 35.4]
datetime optional an ISO-8601-formatted string to indicate the imagery date; to indicate a range use a / to separate two date strings, for open-ended ranges use .. as the date e.g. "2019-10-25T09:00:00Z/.. "datetime": "2019-10-25T09:00:00Z/2020-10-26T13:00:00Z"
image_age_category optional a list of age categories used to limit the age of image tiles returned in the selection results; allowed values are "fresh", "standard", and "training". "image_age_category": ["standard", "training"]
intersects optional, but required if bbox value is not supplied. The "select imagery by criteria" request requires an AOI in either the "intersects" or "bbox" field. "intersects": "POLYGON ((-106.8 35.1,-106.4 35.1,-106.4 35.4,-106.8 35.4,-106.8 35.1))"
query required if the ids field isn't populated. Include query fields and values or submit an empty object to query by only the fields with default values set. See the query fields table below. See "Query fields" table below. "query": {"aoi:cloud_free_percentage": {"gte": 95.0} or "query":{}
stack_depth optional The maximum number of tiles per cell to return; defaults to 5. "stack_depth": 10
Query fields
parameter default value description example
aoi:cloud_free_percentage none The percentage of the AOI intersection area not covered by clouds. "aoi:cloud_free_percentage":{"gte": 95.0}
aoi:data_percentage none The percentage of the tile area intersected by the AOI. "aoi:data_percentage":{"gte": 75.0}
collect_day optional The day the imagery was collected. Can be a single value or range with an operator. "collect_day": {"between": ["15", "21"]}
collect_month optional The month the imagery was collected. Can be a single value or a range with an operator. "collect_month": {"in": ["12", "01", "02"]}
collect_month_day optional The month and day the imagery was collected. Can be a single value or a range with operator. "collect_month_day": {"between": ["03-20","06-21"]}
view:azimuth none The angle measured from the sub-satellite point (point on the ground below the platform) between the scene center and true north. Measured clockwise from north in degrees (0-360). "view:azimuth": {"lte": 60}
view:off_nadir none The angle from the sensor between nadir (straight down) and the scene center, measured in degrees (0-90). (Note: for tiles, this is the average off-nadir angle of the full image strip.) "view:off_nadir": {"lte": 20}
view:sun_azimuth none From the scene center point on the ground, this is the angle between true north and the sun. Measured clockwise in degrees (0-360). "view:sun azimuth": {"lte": 30}
view:sun_elevation "gte": 5 The angle from the tangent of the scene center point to the sun. Measured from the horizon in degrees (0-90). See "nighttime imagery" note below. "view:sun_elevation": {"gte": 20}
multi_resolution_avg none The average multispectral resolution for the strip. This is the native resolution as collected by the satellite. "multi_resolution_avg":{"lte": 2.0}
multi_resolution_max none The maximum multispectral resolution for the strip. This is the native resolution as collected by the satellite. "multi_resolution_max":{"eq": 8.0}
multi_resolution_min none The minimum multispectral resolution for the strip. This is the native resolution as collected by the satellite. "multi_resolution_min":"eq": 1.7}
off_nadir_max none The maximum off-nadir angle of the full image strip. "off_nadir_max": {"eq": "20"}
off_nadir_min none The minimum off-nadir angle of the full image strip. "off_nadir_min": {"eq": 0}
pan_resolution_avg none The average panchromatic resolution for the strip. This is the native resolution as collected by the satellite. "pan_resolution_avg": {"lte": .47}
pan_resolution_max none The maximum panchromatic resolution for the strip. This is the native resolution as collected by the satellite. "multi_resolution_max": {"eq": .60}"
pan_resolution_min none The minimum panchromatic resolution for the strip. This is the native resolution as collected by the satellite. "multi_resolution_min": {"eq": .40}
platform geoeye-01, worldview-01, worldview-02, worldview-03, worldview-04 The name of the satellite used to collect the image. Allowed values are geoeye-01, worldview-02, worldview-03, and worldview-04. For worldview-03, only VNIR imagery is available as ARD. "platform": {"eq": "worldview-03"}

Nighttime imagery

ARD is not available for nighttime imagery because pre-processing includes atmospheric compensation (AComp) for surface reflectance. Because there is no energy to reflect in nighttime imagery, results may not be as expected. Any imagery with a sun elevation of 5 degrees or less is considered nighttime imagery.

The default sun elevation value can be overridden by submitting the field with a value as part of the query object. However, if a view:sun_elevation value of less than 5 is submitted in a "select" request, the imagery will be included in the selection, but it will fail during the ordering process. If this occurs, the order response will show this error message:

{
    "message": "Bad Request: Acquisition [id number]cannot be ordered because it has a sun elevation value less than 5",
    "code": "invalid_parameters",
    "type": "invalid_request_error"
}
Example request: Select imagery by criteria
{
    "bbox": [-106.8, 35.1, -106.4, 35.4],
    "image_age_category": ["standard"],
    "stack_depth": 3,
    "query": {
        "collect_month_day": {
            "between": ["03-20", "06-21"]
        },
        "aoi:cloud_free_percentage": {
            "gte": 95.0
        },
        "aoi:data_percentage": {
            "gte": 75.0
        },
        "view:off_nadir": {
            "lt": 30
        },
        "view:sun_elevation": {
            "gte": 5
        }
    }
}
Example request: select imagery by criteria without specifying query fields or values.

The query object is required if the request does not include the ids field. You can submit an empty query object. In this scenario, only the query fields that have a default value set will be used in the selection process.

{
    "image_age_category": ["standard", "training"],
    "bbox": [-106.8, 35.1, -106.4, 35.4],
    "stack_depth": 7,
    "query": {},
}

This query would select based on the main body of the request and the query fields with default values.

Submitting an empty query object is equivalent to querying by the following fields and values:

"query": {
         "view:sun_elevation": {
             "gte": 5
         },
         "platform": {
             "in": [

                 "geoeye-01",
                 "worldview-01",
                 "worldview-02",
                 "worldview-03",
                 "worldview-04"
             ]
         },
         "instruments": {
             "not-contains": "SWIR"
         }
     }

Note: The instruments field should not be set in a request body. Only the default value of "not-contains":swirwill return results.

Note: A "select by criteria" request requires an AOI in either the intersects or the bbox field. However, including both fields will result in an error.

To learn more about AOIs, see AOI Examples and Guidelines.

Select imagery by acquisition ID and AOI

Request body

parameter required description example
bbox optional The "select imagery by acquisition ID" request can be constrained by an AOI in either the "intersects" or "bbox" field. "bbox": [-106.8, 35.1, -106.4, 35.4]
ids required for this request type A list of acquisition IDs for selection. "ids": ["10300100B3841C00", "10300100AC700900"]
intersects optional The "select imagery by acquisition ID" request can be constrained by an AOI in either the "intersects" or "bbox" field. "intersects": "POLYGON ((-106.8 35.1,-106.4 35.1,-106.4 35.4,-106.8 35.4,-106.8 35.1))"
Example: Select imagery by acquisition ID and AOI
{
    "ids": ["10300100B3841C00", "10300100AC700900"],
    "bbox": [-106.8, 35.1, -106.4, 35.4]
}

Select response

A Select request returns the following responde code, along with a link to the "Get Select Details" request URL.

Status: 202: Accepted

Get Select Details

GET /select/request/{select_id}

Get the status and details of a "select" request.

Path parameters

parameter description example
select_id The ID from the "Select" response. "id": "5593392884763461609"

Select Details response

The select request details response includes the following information:

  • Request details

  • Request status

  • Stack depth fulfillment details

  • Number of unique acquisitions in the selection

  • Links

  • Usage data

Request details

The request body for the selection.

Example:

    "id": "5705192618481751693",
    "response_timestamp": "2021-07-20T20:59:24Z",
    "duration": "0:00:05.017000",
    "request_details": {
        "datetime": "2020-07-01T00:00:00Z/2021-01-25T00:00:00Z",
        "bbox": [
            -106.8,
            35.1,
            -106.4,
            35.4
        ],
        "stack_depth": 3,
        "query": {
            "platform": {
                "eq": "worldview-01"
            },
            "aoi:cloud_free_percentage": {
                "gte": 95.0
            },
            "aoi:data_percentage": {
                "gte": 75.0
            },
            "view:sun_elevation": {
                "gte": 10
            }
        }
    }

Request status

States: RUNNING, SUCCEEDED, FAILED

Example:

 "status": "SUCCEEDED"

Stack depth fulfilled

The stack depth summary for each cell in the selection.The stack depth is set in the "select" request. If no depth is set, the default is 5.

field description
filled The number of cells in the selection where the requested stack depth has been met.
partial The number of cells in the selection that contain at least one tile in the stack, but do not meet the request stack depth.
empty The number of empty cells in the selection.
total The total number of cells in the selection.

Example:

"stack_depth_summary": {
    "filled": 1,
    "partial": 39,
    "empty": 16,
    "total": 56
  }

Unique acquisitions

The number of unique acquisitions in the selection.

"unique_acquisitions": 5,

Links to files pertaining to the selection. Links require ARD authentication to open.

Example:

"links": {
    "self": "https://ard.maxar.com/api/v1/select/request/5705192618481751693",
    "status": "https://ard.maxar.com/api/v1/select/request/5705192618481751693",
    "html": "https://ard.maxar.com/api/v1/select/files/5705192618481751693.html",
    "geojson": "https://ard.maxar.com/api/v1/select/files/5705192618481751693.geojson",
    "geojsonl": "https://ard.maxar.com/api/v1/select/files/5705192618481751693.geojsonl",
    "stac": "https://ard.maxar.com/api/v1/select/files/5705192618481751693.stac"

Usage

Estimated usage and cost data pertaining to the imagery selection. To learn how to interpret usage data, see Account Usage.

Example:

"usage": {
    "limits": {
        "limit_sqkm": -1,
        "annual_subscription_fee_limit": 100500,
        "fresh_imagery_fee_limit": -1,
        "standard_imagery_fee_limit": -1,
        "training_imagery_fee_limit": -1
    },
    "area": {
        "training_imagery_sqkm": 0,
        "total_imagery_sqkm": 1313,
        "fresh_imagery_sqkm": 0,
        "standard_imagery_sqkm": 1313,
        "estimate": true
    },
    "cost": {
        "fresh_imagery_cost": 0,
        "standard_imagery_cost": 14,
        "training_imagery_cost": 0,
        "total_imagery_cost": 140,
        "estimate": true
    },
    "available": {
        "available_sqkm": -1,
        "total_imagery_balance": 100360,
        "fresh_imagery_balance": -1,
        "standard_imagery_balance": -1,
        "training_imagery_balance": -1
    },
    "usage_as_of": "2021-07-20T20:59:18Z"
}
}

Example Get Status response

Status: 200 OK

{
    "id": "5890025443722088241",
    "response_timestamp": "2022-04-01T21:29:13Z",
    "duration": "0:00:05.152000",
    "request_details": {
        "bbox": [
            -106.8,
            35.1,
            -106.4,
            35.4
        ],
        "image_age_category": [
            "standard"
        ],
        "stack_depth": 3,
        "query": {
            "collect_month_day": {
                "between": [
                    "03-20",
                    "06-21"
                ]
            },
            "aoi:cloud_free_percentage": {
                "gte": 95.0
            },
            "aoi:data_percentage": {
                "gte": 75.0
            },
            "view:off_nadir": {
                "lt": 30
            },
            "view:sun_elevation": {
                "gte": 5
            },
            "platform": {
                "in": [
                    "geoeye-01",
                    "worldview-01"
                    "worldview-02",
                    "worldview-03",
                    "worldview-04"
                ]
            },
            "instruments": {
                "not-contains": "SWIR"
            }
        }
    },
    "status": "SUCCEEDED",
    "stack_depth_summary": {
        "filled": 29,
        "partial": 25,
        "empty": 2,
        "total": 56
    },
    "unique_acquisitions": 15,
    "links": {
        "self": "https://ard.maxar.com/api/v1/select/request/5890025443722088241",
        "status": "https://ard.maxar.com/api/v1/select/request/5890025443722088241",
        "html": "https://ard.maxar.com/api/v1/select/files/5890025443722088241.html",
        "geojson": "https://ard.maxar.com/api/v1/select/files/5890025443722088241.geojson",
        "geojsonl": "https://ard.maxar.com/api/v1/select/files/5890025443722088241.geojsonl",
        "stac": "https://ard.maxar.com/api/v1/select/files/5890025443722088241.stac"
    },
    "usage": {
        "limits": {
            "limit_sqkm": -1,
            "annual_subscription_fee_limit": -1,
            "fresh_imagery_fee_limit": -1,
            "standard_imagery_fee_limit": -1,
            "training_imagery_fee_limit": -1
        },
        "area": {
            "training_imagery_sqkm": 0,
            "total_imagery_sqkm": 3014,
            "fresh_imagery_sqkm": 0,
            "standard_imagery_sqkm": 3014,
            "estimate": true
        },
        "cost": {
            "fresh_imagery_cost": 0,
            "standard_imagery_cost": 31,
            "training_imagery_cost": 0,
            "total_imagery_cost": 31,
            "estimate": true
        },
        "available": {
            "available_sqkm": -1,
            "total_imagery_balance": -1,
            "fresh_imagery_balance": -1,
            "standard_imagery_balance": -1,
            "training_imagery_balance": -1
        },
        "usage_as_of": "2022-04-01T21:29:08Z"
    }
}

Response fields

field description example
bbox The bounding box coordinates to which selection results will be limited in [minx, miny, maxx, maxy] format. "bbox": [-106.8, 35.1, -106.4, 35.4]
datetime the yyyy-mm-ddThh:mm:ssZ formatted string representation of the date/time of collection. "2019-10-25T09:00:00Z/2020-10-26T13:00:00Z"
ids The ID of an acquisition to be selected. "ids": ["10300100B3841C00", "10300100AC700900"]
image_age_category A date-based field for choosing an image age category of "fresh", "standard", or "training". "image_age_category": ["standard", "training"]
intersects The geometry to which selection results will be limited; accepts a polygon or multipolygon GeoJSON geometry or WKT format. GeoJSON feature collections are not a valid input. "intersects": "POLYGON ((-106.8 35.1,-106.4 35.1,-106.4 35.4,-106.8 35.4,-106.8 35.1))"
aoi:cloud_free_percentage The percentage of the AOI intersection area not covered by clouds. "aoi:cloud_free_percentage":
collect_day The day the imagery was collected. Can be a single value or range with an operator. "collect_day":
collect_month The month the imagery was collected. Can be a single value or a range with an operator. "collect_month":
collect_month_day The month and day the imagery was collected. Can be a single value or a range with operator. "collect_month_day":
aoi:data_percentage The percentage of the tile area intersected by the AOI. "aoi:data_percentage":
view:azimuth The angle measured from the sub-satellite point (point on the ground below the platform) between the scene center and true north. Measured clockwise from north in degrees (0-360). "view:azimuth":
view:off_nadir The angle from the sensor between nadir (straight down) and the scene center, measured in degrees (0-90). (Note: for tiles, this is the average off-nadir angle of the full image strip.) "view_off_nadir":
view:sun_azimuth From the scene center point on the ground, this is the angle between true north and the sun. Measured clockwise in degrees (0-360). "view:sun azimuth":
view:sun_elevation The angle from the tangent of the scene center point to the sun. Measured from the horizon in degrees (0-90). Default is "greater than or equal to 5, "gte": 5.0. See note below. "view:sun_elevation":
off_nadir_min The minimum off-nadir angle of the full image strip. "off_nadir_min":
off_nadir_max The maximum off-nadir angle of the full image strip. "off_nadir_max":
platform The name of the satellite used to collect the image. Allowed values are geoeye-01, worldview-01, worldview-02, worldview-03, and worldview-04. For worldview-03, only VNIR imagery is available as ARD. "platform":
stack_depth The maximum number of tiles per cell to return; defaults to 5. "stack_depth": 5

Note: By default, results include imagery from geoeye-01, worldview-02, worldview-03, and worldview-04. See WorldView-1 Ordering for examples of ordering WorldView-1 imagery.

Download a file from the selection results

GET /select/files/{request_id}.{extension}

Access and download individual files from the select results.

Path parameters

parameter description example
request_id The id of the select request. 5704485897238655107
extension (optional) Extension of the file requested. Supported extensions are 'stac', 'html', 'geojson', and 'geojsonl'. If no extension is provided, then the output of the original /select request is returned. 704485897238655107.geojsonl

Example request

https://ard.maxar.com/api/v1/select/files/5704485897238655107.geojsonl

Response

A successful response will return a download link for the requested file.

Example success response

{
    "file_size": 3682,
    "download_link": "https://ard-metadata-master-dev-materialselectionresults-zbr6g8vbrnzf.s3.amazonaws.com/...",
    "download_link_expiration": 3600
}

A successful response will contain a download link for requested file as well as metadata fields.

  • file_size: size of requested file in bytes

  • download_link: presigned download link for requested file

  • download_link_expiration: the amount of time (in seconds) the download link will be valid for

More documentation

Selecting Imagery Guide

Usage Guide

AOI Guidelines and examples

Temporal Queries

Back to top