Exploring Tile Metadata¶
Last updated: April 4, 2022
About this Guide¶
The Tile Metadata Guide covers the following topics:
Overview of the Tile Metadata API endpoint
Construct a Tile Metadata query
Find all cells that cover an AOI
View or re-run past tile metadata queries
Order the results of a tile metadata query
Overview¶
The Tile Metadata API endpoint lets you query for a single tile, the tiles in a specific cell, or the tiles in cells that intersect with an AOI or a list of acquistion IDs. Additional query fields can be used to filter results. You can give your query a name, re-run it later to get updated results, and use the query ID to place an order.
A Tile Metadata query request is similar to a "select" request. Both the tile metadata api and the select api search request:
-
accept an AOI as a bounding box or a polygon in WKT or GeoJSON format.
-
accept a list of acquisition IDs.
-
allow a stack depth limit to be set.
-
accept additional query fields to further filter results.
-
generate an ID that can be used to order the discovered imagery. The Tile Metadata API generates a "query ID", and the Select API generates a "select ID".
-
calculate and return AOI-specific metadata such as the percentage of cloud cover within your AOI's portion of the tile.
There are some important differences between the Select and Tile Metadata APIs. The Tile Metadata query allows you to explore the tiles in a specific cell. The results are returned with a smaller set of data for faster, simpler processing. The Select API returns results about the selected dataset to help you make decisions about the data.
The results of a Tile Metadata request do not include the following information:
-
cost and usage estimates
-
a stack depth summary
-
a list of acquisitions
-
a visualization of the results in the html viewer
If you need access to this information, use the Select API instead.
Tile Metadata results set¶
The Tile Metadata results set is a page of tiles that match the search criteria, starting with the most recent matching acquisition. For a tile to appear in the results, it must:
-
intersect with the AOI
-
intersect with the acquisition ID(s)
-
fall within the date range if a date range is specified
-
meet all of the additional query criteria
No additional scoring or ranking logic is applied.
Tile Metadata processing limits¶
Large Metadata API requests may run into execution and results processing limits. Any search that could return a large amount of data should be broken into smaller searches. If you run into execution time limits, you can reduce your AOI size, choose a smaller date range, or use the query fields to further filter your results. We recommend using the Max-ARD SDK, which provides a batch search function that will efficiently divide up large area searches for you and retrieve them in parallel.
Construct a Tile Metadata query¶
There are three ways to query for tile metadata:
-
explore metadata for tiles in a specific cell
-
explore metadata for tiles that cover a specified AOI or a list of acquisition IDs
-
explore metadata for a single tile
Explore metadata for tiles in a specific cell¶
This API request takes a cell ID as a path parameter. A request like this example will return a page listing of tiles in the cell, starting with the most recent.
POST https://ard.maxar.com/api/v1/metadata/cells/Z13-031133231113/acquisitions
Although a request body is not required for this query, we recommend submitting one with your post. This gives you the option to:
-
name the query for easier identification later
-
further constrain the result by submitting an AOI. The geometries for the cell and the AOI must intersect to get results.
-
filter by additional query criteria
Explore metadata for tiles that cover an AOI or a list of acquisition IDs¶
This request requires either a list of acquisition IDs or an AOI in either the bbox or intersects field. Additional fields can be included for further refinement.
POST https://ard.maxar.com/api/v1/metadata/cells/acquisitions
This is an example request body with only an AOI.
{
"bbox": [-106.8, 35.1, -106.4, 35.4]
}
This is an example request body with only a list of acquisition IDs.
{
"ids": ["10300100B3841C00", "10300100AB101A00"]
}
Explore metadata by cell ID and acquisition ID¶
To view the metadata for a single image within a cell, make a tile metadata request with both the cell ID and the acquisition ID in the path. This will give you the metadata for the part of the acquisition that falls within the specified cell. The results are returned as a GeoJSON feature.
This query doesn't require a request body, but you can include one to name your query or further constrain the results by an AOI.
Example request:
GET https://ard.maxar.com/api/v1/metadata/cells/{cell_id}/acquisitions/:{acquisition_id}
Query parameter: format¶
You can specify the format of the results as a query parameter, called "format". The supported formats are STAC, GeoJSON, and Order.
Example:
POST https://ard.maxar.com/metadata/cells/acquisitions?format=stac
Request body¶
The following fields can be used in a Tile Metadata Query request body.
For a query by AOI or acquisition IDs, a request body with either a list of IDs or an AOI in either the bbox or intersects field is required.
Request body fields¶
| field | value |
|---|---|
| query_name | Provide a name for your query to easily identify it later in a list. |
| ids | required if not supplying an AOI in the intersects or bbox field. |
| bbox | The bounding box coordinates to which selection results will be limited in [minx, miny, maxx, maxy] format. |
| datetime | 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 | Image age categories are "fresh", "standard", and "training." |
| intersects | The geometry to which selection results will be limited; accepts GeoJSON geometry or WKTformat. |
| stack_depth | 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 | Additional fields for further refining the query results. Available fields and operators are described in the Metadata API reference documentation |
Image age categories¶
Maxar ARD imagery is categorized into three age ranges. See your Maxar ARD subscription for pricing by category. You can include an image age category in the request to limit results to that category, but the results will not show a breakdown of imagery by image age category. If that information needed, make a request to the Select API instead.
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 |
Query fields¶
See the Metadata API Reference for a list of fields that can be included in the request body query object.
Tile Metadata query results¶
The results of a Tile Metadata query include:
-
query ID.
-
query name: if no name was submitted, the value will be "null".
-
the query criteria submitted in the request body.
-
the acquisition ID, cell ID, and metadata for each tile. If the format is "order", the tile metadata is not displayed in the results.
-
links to results in other formats.
Example response¶
This is a truncated example response in GeoJSON format.
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
-106.70143733134023,
35.140959315429065
],
[
-106.7023764087391,
35.186025357332746
],
[
-106.64748158281041,
35.18678472949584
],
[
-106.64657275298134,
35.141717427553935
],
[
-106.70143733134023,
35.140959315429065
]
]
]
},
"properties": {
"cell_id": "Z13-031133320201",
"acquisition_id": "10300100BD8AE000",
"constellation": "digitalglobe",
"date": "2021-04-24",
"datetime": "2021-04-24T17:50:28Z",
"eo:cloud_cover": 0.0037800589291292004,
"instruments": [
"VNIR"
],
"modified": "2022-03-30T21:09:46Z",
"multi_resolution_avg": 2.05155995,
"multi_resolution_max": 2.1107078,
"multi_resolution_min": 1.9975655,
"off_nadir_max": 21.569456,
"off_nadir_min": 16.593653,
"pan_resolution_avg": 0.5147694233333333,
"pan_resolution_max": 0.5297548,
"pan_resolution_min": 0.5010995,
"platform": "worldview-02",
"tile:cloud_free_percentage": 100,
"tile:cloud_percentage": 0,
"tile:data_percentage": 100,
"tile:no_data_percentage": 0,
"tile:quadkey": "031133320201",
"tile:zone": 13,
"view:azimuth": 325.74694666666664,
"view:off_nadir": 19.092010666666667,
"view:sun_azimuth": 137.86597,
"view:sun_elevation": 62.440462833333335,
"tile:cloud_polys": null,
"aoi:data_area_sqkm": 26,
"aoi:data_percentage": 100,
"aoi:cloud_free_percentage": 100
}
}
],
"query_id": "Q5890030913094814209",
"query_name": Albuquerque,
"query_criteria": {
"collect_month_day": {
"between": [
"03-20",
"06-21"
]
},
"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"
},
"datetime": {
"between": [
"2019-04-02T21:40:00Z",
"2022-01-01T21:40:00Z"
]
},
"aoi:cloud_free_percentage": {
"gte": 95.0
},
"aoi:data_percentage": {
"gte": 75.0
}
},
"links": {
"details": "https://ard.maxar.com/api/v1/metadata/query/Q5890030913094814209",
"geojson": "https://ard.maxar.com/api/v1/metadata/query/Q5890030913094814209/results?format=geojson",
"stac": "https://ard.maxar.com/api/v1/metadata/query/Q5890030913094814209/results?format=stac",
"acquisitions": "https://ard.maxar.com/api/v1/metadata/query/Q5890030913094814209/results?format=order"
}
}
Response fields¶
To see a list of response fields and their definitions, see Response Fields.
Find all the cells that cover an AOI¶
To see a list of cells that intersect a given AOI, make a request to the metadata cells endpoint, with an AOI in the request body. The results can be formatted as a GeoJSON feature collection or as a list of IDs.
This example request shows an AOI as a bounding box and chooses the results format of "ids":
POST https://ard.maxar.com/api/v1/metadata/cells?format=ids
{
"bbox": [-106.8, 35.1, -106.4, 35.4]
}
[
"Z13-031133231111",
"Z13-031133231113",
"Z13-031133231131",
"Z13-031133231133",
"Z13-031133231311",
]
View or re-run past tile metadata queries¶
The "Query" API endpoint lets you list your past queries, get the details of a specific query, or re-run a query to get the most recent results. You can also delete a query.
By default, saved queries expire 90 days from their original date of execution. Queries never expire if one or both of the following are true:
-
the query has a name
-
the query ID has been used to order imagery.
The API requests supported by the "query" endpoint are:
-
Get a list of your past queries
-
Get the details of a specific query by query ID
-
Re-run a query to get the latest results
-
Delete a query
See also: Query API Reference
Order the results of a tile metadata query¶
To order the imagery results from a tile metadata query, you can place an order using the query ID from the response. The Ordering API accepts a query ID in the select_id field of a request body.
The query ID can be found in the response to a tile metadata query.
-
In a GeoJSON feature collection, the
query_idcan be found below thepropertiessection. -
In an Order response, the
query_idis listed at the top. -
In a STAC response, the
query_idis found near the end of the response, below the "assets" section.
Example query ID:
"query_id": "Q5865450089204699225"
This example shows a request to the Ordering API, using the query ID to place the order. The query ID should be submitted in the select_id field.
{
"select_id": "Q5865450089204699225",
"output_config": {
"amazon_s3": {
"bucket": "my-ard-bucket",
"prefix": "albuquerque-project"
}
},
"bundle_adjust": true,
"notifications": [{
"type": "email",
"address": "shea.barnes@myemail.com"
}]
}