Selecting ARD Imagery to Order¶

Last updated: May 6, 2022

Overview¶

The Maxar ARD imagery selection process lets you select imagery by a set of criteria or by a list of acquisition IDs. You can see the results of your selection in the API response, and you use the html viewer to visualize the results. Estimated usage data is also included. No subscription charges are incurred during the "select" process. Once you are satisfied with the resulting imagery selection, you can use the generated "select ID" to place an order.

Constructing a "select" request¶

Several combinations of selection criteria can be used in a "select" request.

field	required?	description
ids	optional	A list of acquisition IDs. A list of acquisition IDs can optionally be constrained by an AOI.
datetime	optional	Use an ISO-8601-formatted string to indicate the imagery date. To indicate a range use a `/` to separate two date strings, e.g. “2019-10-25T09:00:00Z/2020-10-26T13:00:00Z”; for open-ended ranges use `..` as the end date e.g. "2019-10-25T09:00:00Z/.."
image_age_category	optional	Image age categories are "fresh", "standard", and "training."
intersects	optional	The geometry to which selection results will be limited; accepts geojson geometry or WKT format.
bbox	optional	The bounding box coordinates to which selection results will be limited in `[minx, miny, maxx, maxy]` format.
stack_depth	optional	Use stack depth to set the maximum number of tiles per cell to return. This will find the best matches up to the selected maximum. If a stack depth limit is not set, a default of 5 tiles maximum will be returned.
query	Required if the request does not include a an acquisition ID list.	The fields and query parameters to match against. Available fields and operators are described in the API reference documentation

Note: A request cannot include an AOI in both the intersects and the bbox field.

Image age categories¶

Maxar ARD imagery is categorized into three age ranges. See your Maxar ARD subscription for pricing by category. When selecting imagery, the response will show an estimate of the amount of imagery per age category. Imagery age is calculated when the order is delivered.

These are the image age categories for archive imagery:

image age category	time since acquisition
Fresh imagery	less than or equal to 90 days
Standard imagery	91 days to 3 years
Training imagery	more than 3 years

The image age category can be included as a field in the selection request if you want to limit your select to one or more age categories. This is explained later in this document.

Search operators¶

It's common to see example requests with the following operators, used to show equal to, less than, or greater than.

lte: less than or equal to

gte: greater than or equal to

For a full list of search operators, see the Select API Reference.

Select by criteria¶

To construct a request without acquisition IDs, use a set of criteria to determine tile selection.

At a minimum, a "select by criteria" request must include:

An AOI in the "intersects" field OR a bounding box in the "bbox" field. The "intersects" field accepts a polygon or multipolygon in WKT or GeoJSON format. GeoJSON must be a geometry. Feature collections are not a valid input.

AND

A "query" object. The query object can include one or more fields with values to use in the imagery selection process. You can also submit an empty query object. When an empty query object is submitted, only the query fields with default values are used to select imagery. See the API reference documentation for more information.

Available fields and search operators are described in the API reference documentation

Example request body:

POST/select

{
    "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-03"
        },
        "aoi:cloud_free_percentage": {
            "gte": 95.0
        },
        "aoi:data_percentage": {
            "gte": 75.0
        },
        "view:off_nadir": {
            "lt": 30
        },
        "view:sun_elevation": {
            "gte": 5
        }
    }
}

Select by acquisition ID¶

A "select" request can be made using a list of acquisition IDs and an optional AOI. You can select imagery by acquisitions from Maxar's GeoEye-1, WorldView-1, Worldview-2, WorldView-3, and WorldView-4 sensor platforms. Including an AOI in either the bbox or intersects field will limit your results to only the area you request.

This request type can be constrained by any of the criteria listed in the next section. The results will include any tiles from a specified acquisition ID that meet the additional criteria.

Example:

POST /select

{
   "ids": ["10300100B3841C00", "10300100AB101A00", "10300100A67D3100", "10300100AC700900"],
   "bbox": [-106.8, 35.1, -106.4, 35.4],
   "stack_depth": 3
}

Since stack depth is set to "3", it will select a maximum of three tiles per cell that most closely match the criteria.

Date Range and Image Age Category¶

There are two date-based fields that can be used in a "select" request: datetime and image_age_category.

The datetime field accepts a date range or a specific date. Date ranges can be open-ended. For datetime formatting options, see Select API Reference.

The image_age_category field accepts the values of "fresh", "standard", or "training. These are described earlier in this document. The request can include more than one category, but the categories included must be adjacent to each other.

Examples:

These are valid requests:

"image_age_category": ["standard"]

"image_age_category": ["standard", "training"]

This request is invalid because the categories are not adjacent:

    "image_age_category": ["fresh", "training"]

The datetime and image_age_category fields can be used together, as long as they don't conflict.

This example shows a fixed date range and the image age category of "training".

"datetime": "2017-01-31/2018-01-01",
"image_age_category": ["training"]

This example shows an open-ended date range and the image age category of "training".

"datetime": "../2018-02-28",
"image_age_category": ["training]

This request would be invalid because the fresh and standard categories fall outside of the specified date range.

"datetime": "2019-01-01/2020-01-01",
"image_age_category": ["standard", "fresh"]

"Best Match" logic¶

Learn how the best matched imagery is selected at Frequently Asked Questions-Selecting Imagery

Results of a "Select" request¶

The response to a POST Select request are a 202 Accepted message, a status, and a link to get the details of the selection.

To view the status and details of a Select request, make a GET request with the select ID (below).

Get the details of a Select request¶

A successful request results in a body containing a unique request ID, details of the request, estimated usage data, and links to retrieve the output files associated with this selection request.

GET /select/request/{selectID}

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

Path parameters¶

parameter	description
selectID	The ID from the "select" response. Example: "id": "5593392884763461609"

Response¶

{
    "id": "5701532359835563578",
    "response_timestamp": "2021-07-15T19:47:07Z",
    "duration": "0:00:05.135000",
    "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-03"
            },
            "aoi:cloud_free_percentage": {
                "gte": 95.0
            },
            "aoi:data_percentage": {
                "gte": 75.0
            },
            "view:sun_elevation": {
                "gte": 5
            },
            "instruments": {
                "not-contains": "SWIR"
            }
        }
    },
    "status": "SUCCEEDED",
    "stack_depth_summary": {
        "filled": 1,
        "partial": 39,
        "empty": 16,
        "total": 56
    },
    "links": {
        "self": "https://ard.maxar.com/api/v1/select/request/5701532359835563578",
        "status": "https://ard.maxar.com/api/v1/select/request/5701532359835563578",
        "html": "https://ard.maxar.com/api/v1/select/files/5701532359835563578.html",
        "geojson": "https://ard.maxar.com/api/v1/select/files/5701532359835563578.geojson",
        "geojsonl": "https://ard.maxar.com/api/v1/select/files/5701532359835563578.geojsonl",
        "stac": "https://ard.maxar.com/api/v1/select/files/5701532359835563578.stac"
    },
    "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"
    }
}

Usage data¶

The "select" response shows estimated usage data that would be used if the selected imagery is ordered. Estimated usage data is typically slightly higher than the actual usage. To learn more about usage data, see Account Usage Data.

Downloading and opening files from the response¶

The URLs in the response must be signed before the files can be downloaded or opened. See the FAQ to learn how to get signed URLs.

Select ID¶

The "ID" in the select response can be used to order the imagery results from the request. To order imagery by the selection ID, copy the ID number and use it in a "Place an order by Select ID" request. See Ordering ARD Imagery for more information, or use the "Order ARD Imagery" request example in the Postman collection.

The select ID can be used to place an order for approximately 90 days. However, the estimated usage data provided in the selection response is only valid at the time the selection is made.

State¶

A state of "FINISHED" for a select request means the selection files have been produced and can be viewed or downloaded.

Select Outputs¶

After the select query has completed successfully, the following files will have been written to the select results location:

filename	description
`request_id.geojson`	Detailed information about each cell_id, in geojson format.
`request_id.geojsonl`	Detailed information about each cell_id, in jsonl format.
`request_id.stac`	Detailed information about each cell_id, in STAC format.
`request_id-visualization.html`	HTML page providing a way to view vector representation of the tiles on a map along with some basic information when cells are clicked on.

The results will not be available at this link unless the status is FINISHED.

Visualizing the results of a "select" request¶

The html output file provides a vector representation of the tiles in your selection on a map. Click on individual cells on the map for additional information.

To interact with a sample visualization file, go to HTML visualization.

The visualization looks like this:

visualization html example

Top right: shows a summary of the selection criteria in the request.
bottom right: a legend defining the cell colors.
center: color-coded cells for the imagery in the selection. Click on a cell to display thumbnail images for each tile in the stack. You may need to scroll to see all of the images.
left: image thumbnails for the selected cell.

Download a file from the "select" Results¶

The files from a "select" request can be downloaded by making a request to download files. The request must include the ID from the original selection and the extension of the file you want to download.

Supported extensions are:

stac geojson geojsonl html

This request results in a link from which you'll download the file.

If no extension is included in the request, the result will display the original "select" request results.

Example request:

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

Example response:

Status: 200 OK

{
    "file_size": 3682,
    "download_link": "[URL with access to download requested file]",
    "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

Get the status of a "select" request¶

Get the status and results of the select request. Use the "ID" from the original request to check the status.

Example request:

GET /select/request/{request_id}

The results are the same as a successful response to a select query.

"Select" errors¶

See Error Codes and Conditions for standard selection errors.

Order the selected imagery¶

The simplest way to order the contents of a selection is by selection ID. Retain the "ID" from your results, and use as the input to an "order" request. See Ordering ARD.