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.

Select requests¶

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¶

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, a GeoJSON feature collection, or a multipolygon GeoJSON geometry or WKT format.	"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
}

Download links¶

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

Select Resource¶

Select¶

Select requests¶

Headers¶

Select imagery¶

Select imagery by criteria¶

Request body¶

Query fields¶

Nighttime imagery¶

Example request: Select imagery by criteria¶

Example request: select imagery by criteria without specifying query fields or values.¶

Select imagery by acquisition ID and AOI¶

Request body¶

Example: Select imagery by acquisition ID and AOI¶

Select response¶

Get Select Details¶

Path parameters¶

Select Details response¶

Request details¶

Request status¶

Stack depth fulfilled¶

Unique acquisitions¶

Links¶

Usage¶

Example Get Status response¶

Response fields¶

Download a file from the selection results¶

Path parameters¶

Example request¶

Response¶

Example success response¶

Download links¶

More documentation¶