Skip to content

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.

Back to top

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.

Back to top

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

Back to top

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"]
}

Back to top

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

Back to top

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.

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.

Back to top

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.

Back to top

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"
    }
}

Back to top

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]
}
Example results in ID format:

[
    "Z13-031133231111",
    "Z13-031133231113",
    "Z13-031133231131",
    "Z13-031133231133",
    "Z13-031133231311",

]

Back to top

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

Back to top

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_id can be found below the properties section.

  • In an Order response, the query_id is listed at the top.

  • In a STAC response, the query_id is found near the end of the response, below the "assets" section.

Example query ID:

 "query_id": "Q5865450089204699225"
A query ID always begins with the letter "Q".

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"
    }]
}

Back to top

More Resources

Cell Metadata Overview

Cell Summary Guide

Cell Metadata API Reference

Back to top