Exploring Cell Metadata¶
Last updated: March 2, 2022¶
See also: Metadata API Reference
Overview¶
The ARD Metadata API lets you explore areas of the world covered by Maxar ARD in order to discover ARD tiles you might be interested in ordering. The API was designed to let users quickly and easily winnow out imagery that doesn't fit their needs in order to focus on data that will be useful. It is similar to the Select API, but is more useful for cases where AOIs are smaller and fast results are more important than the downloadable artifacts that the Select API generates.
There are three key components to the Cell Metadata API:
-
Cell Summary: See a metadata summary for a cell or for cells that intersect a given AOI.
-
Tile Metadata: Explore tile metadata for a single cell ID or for cells that intersect a given AOI.
-
Query Management: View the details of a past query, or re-run a query to get up to date results.
Cell Summary¶
The cell summary query returns a pre-computed summary of metadata for all of the tiles in a cell that intersect a particular AOI. The summary records contain overview information for the cell and tile counts for specified categories.
To explore the summary metadata for cells that intersect your AOI, you first need to register your AOI. This step ensures that the data you want to explore is available and that our system has compiled the necessary summaries for the area you're interested in. You only need to register an AOI one time, after which the intersecting cells will be continually updated as now imagery data comes in.
Once your AOI has been registered, you can retrieve a metadata summary. Two request types are supported:
-
Get a metadata summary for a specific cell ID. This request requires a cell ID in the path. It can be further constrained by an AOI.
-
Get a metadata summary for each cell that intersects a given AOI. This request requires an AOI.
Learn more:
Tile Metadata¶
A Tile Metadata query returns data about ARD tiles that match a particular set of criteria you define. There are three types of Tile Metadata queries:
-
Query for tiles in a single cell: This query requires a cell ID in the path. It also allows a request body with optional fields for a query name, an AOI, a date range, a stack depth limit, and a set of additional query criteria.
-
Query for tiles in cells that intersect a given AOI: This query requires an AOI in the request body. It also allows optional fields for a query name, a date range, a stack depth limit, and a set of additional query criteria.
-
Retrieve metadata for a single ARD tile. This request rquires a cell ID and an acquisition ID in the path.
Learn more:
Query Management¶
When a tile metadata query is executed, it is saved and assigned a Query ID which is returned as part of the query response. Queries can be given a name by including the query_name field in the request body. We recommend giving your query a name so that it is easy to identify later.
The Query Management API 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 that is no longer useful.
By default, query records expire 90 days from their original date of execution. Query records 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.
Learn more:
More information about viewing or re-running queries can be found in the Tile Metadata User Guide.