Skip to content

Tile Metadata Resource

Last updated: August 29, 2022


Resource paths

/metadata/cells

/metadata/cells/acquisitions

Tile Metadata API

http method path name description
POST /metadata/cells/{cell_id}/acquisitions Tile metadata by cell ID Explore metadata for tiles in a specific cell.
POST /metadata/cells/acquisitions Tile metadata by AOI or Acquisition IDs Explore metadata for tiles that cover a an AOI or acquisition IDs.
POST /metadata/cells List cells in an AOI Retrieve a list of grid cell IDs that cover the given AOI.
GET /metadata/cells/{cell_id}/acquisitions/{acquisition_id} Get metadata for a specific tile Retrieve the metadata for the given cell as a GeoJSON Feature.

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.

Explore Tile Metadata

Explore tile metadata for a specific cell or for an AOI intersecting a specific cell.

Tile Metadata by cell ID

POST /metadata/cells/{cell_id}/acquisitions
Explore metadata for tiles in a specific cell.

Example:

POST https://ard.maxar.com/api/v1/metadata/cells/Z17-120022203221/acquisitions

Path parameters

parameter description example
cell_id The id for the Maxar grid cell. The naming convention for the cell ID is {UTM zone}-{quadkey address}. Z17-120022203221

Query parameters

Filter results by optional query parameters.

param description example
format Choose the tile format for the query results. Formats are "geojson", "stac", and "order"; defaults to "geojson". format=stac
POST https://ard.maxar.com/api/v1/metadata//cells/Z17-120022203221/acquisitions?format=stac

Example optional request body

This example will return up to 4 tiles in the requested cell ID and set a name for the query.

{
    "query_name": "projectYY",
    "stack_depth": 4
}

See all optional request body parameters.

Tile metadata by AOI or Acquisition IDs

POST /metadata/cells/acquisitions
Explore metadata for tiles that cover an AOI or acquisition IDs. Additional fields can also be applied in the "query" object.

Example:

POST https://ard.maxar.com/api/v1/metadata/cells/acquisitions

Query parameters

Filter results by optional query parameters.

param description example
format Choose the tile format for the query results. Formats are "geojson" or "stac", and "order"; defaults to "geojson". format=stac
Formats

Response file formats, as specified using the "format" query parameter.

format description example
geojson Formats the results as a GeoJSON FeatureCollection. format=geojson
order Formats the results as an ARD order request body. format=order
stac Formats the results in STAC collection format. format=stac

Example with optional "format" parameter:

https://ard.maxar.com/api/v1/metadata//cells/acquisitions?format=geojson

Request body

The tile metadata query requires one of the following body request parameters:

  • a list of acquisition IDs

or

  • an AOI in either the intersects or bbox field
Example request by AOI and query fields
{
    "query_name":"Albuquerque NM USA",
    "bbox": [-106.8, 35.1, -106.4, 35.4],
    "stack_depth": 3,
     "query": {       
        "view:off_nadir": {
            "lt": 30},
            "tile:cloud_free_percentage": {
            "gte": 95.0
        }
     }
}
Example request by Acquisition IDs, AOI, and query fields
{
    "query_name": "Albuquerque NM USA by ID",
    "ids": ["10300100B3841C00", "10300100AB101A00"],
    "intersects": "POLYGON ((-106.8 35.1,-106.4 35.1,-106.4 35.4,-106.8 35.4,-106.8 35.1))",
    "stack_depth": 3,
    "query": {
        "view:off_nadir": {
            "lt": 30
        },
        "tile:cloud_free_percentage": {
            "gte": 95.0
        }
    }
}
Example request by acquisition IDs
{
    "ids": [
        "10300100B3841C00", "10300100AB101A00"
    ]
}

Request body parameters

The following parameters can be applied to both tile metadata query request types.

parameter required description example
ids required if not supplying an AOI in the intersects or bbox field. A list of acquisition IDs. "ids": ["10300100CD960400","10300100CD7C2C00"]
bbox required if not using intersects field or ids field. 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]
intersects required if not using bbox field or ids field. A WKT or GeoJSON geometry formatted polygon or multipolygon. see example request
datetime optional 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 date e.g. "2019-10-25T09:00:00Z/.." "datetime": "2020-07-01T00:00:00Z/2021-01-25T00: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 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 optional See the query fields table "query": {"aoi:cloud_free_percentage": {"gte": 95.0} or "query":{}
query_name optional A human-readable name to identify the query. "query_name": "Albuquerque NM USA"
stack_depth optional "stack_depth": 7

Query fields

All query fields are optional. If the "default value" column has the value of "none", there is no default for the field.

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 "lte": 30 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). "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": 2.956368
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, and worldview-04 The name of the satellite used to collect the image. Allowed values are geoeye-01, worldview-1, worldview-02, worldview-03, and worldview-04. For worldview-03, only VNIR imagery is available as ARD. "platform": {"eq": "worldview-03"}

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.

Tile metadata query response

A tile metadata query response in GeoJSON, ARD order, or STAC format.

See Tile metadata properties for a list of properties found in the response to a tile metadata query.

Example responses

200 OK: Success

400 Bad Request: invalid cell ID

GeoJSON feature collection

{
    "type": "FeatureCollection",
    "features": [
        {
            "type": "Feature",
            "geometry": {
                "type": "Polygon",
                "coordinates": [
                    [
                        [
                            -80.44891658974173,
                            35.46724243467717
                        ],
                        [
                            -80.50402298431787,
                            35.46748145779075
                        ],
                        [
                            -80.50374587896196,
                            35.51256331332783
                        ],
                        [
                            -80.44860869972095,
                            35.51232389441319
                        ],
                        [
                            -80.44891658974173,
                            35.46724243467717
                        ]
                    ]
                ]
            },
            "properties": {
                "cell_id": "Z17-120022203221",
                "acquisition_id": "104001007297D800",
                "constellation": "digitalglobe",
                "date": "2022-01-23",
                "datetime": "2022-01-23T16:15:46Z",
                "eo:cloud_cover": 0.0700605940545337,
                "instruments": [
                    "VNIR"
                ],
                "modified": "2022-01-23T20:31:54Z",
                "multi_resolution_avg": 1.3282768416666666,
                "multi_resolution_max": 1.329538,
                "multi_resolution_min": 1.3278235,
                "off_nadir_max": 16.815842,
                "off_nadir_min": 16.646889,
                "pan_resolution_avg": 0.331958515,
                "pan_resolution_max": 0.33227426,
                "pan_resolution_min": 0.3318473,
                "platform": "worldview-03",
                "tile:cloud_free_percentage": 100,
                "tile:cloud_percentage": 0,
                "tile:data_percentage": 100,
                "tile:no_data_percentage": 0,
                "tile:quadkey": "120022203221",
                "tile:zone": 17,
                "view:azimuth": 177.6466925,
                "view:off_nadir": 16.695059,
                "view:sun_azimuth": 158.08304916666665,
                "view:sun_elevation": 32.65171191666666,
                "tile:cloud_polys": {
                    "type": "Polygon",
                    "coordinates": [
                        [
                            [
                                -80.459379,
                                35.508625
                            ],
                            [
                                -80.458387,
                                35.508485
                            ],
                            [
                                -80.458728,
                                35.506999
                            ],
                            [
                                -80.460047,
                                35.507681
                            ],
                            [
                                -80.459379,
                                35.508625
                            ]
                        ]
                    ]
                },
                "aoi:data_area_sqkm": 26,
                "aoi:data_percentage": 100,
                "aoi:cloud_free_percentage": 100
            }
        }
    ],
    "query_id": "Q585732947467002961",
        "query_name":"Albuquerque NM USA",
    "links": {
        "details": "https://ard.maxar.com/api/v1/metadata/query/Q58573294746700296111",
        "geojson": "https://ard.maxar.com/api/v1/metadata/query/Q58573294746700296111/results?format=geojson",
        "stac": "https://ard.maxar.com/api/v1/metadata/query/Q58573294746700296111/results?format=stac",
        "acquisitions": "https://ard.maxar.com/api/v1/metadata/query/Q58573294746700296111/results?format=order"
    }
}

"Order" format

{
    "query_id": "Q5857404111168258284",
        "query_name":"Albuquerque NM USA",
    "acquisitions": [
        {
            "id": "1050010029A54C00",
            "cells": [
                "Z36-300202300130"
            ]
        },
        {
            "id": "1040010073834100",
            "cells": [
                "Z36-300202300130"
            ]
        }
    ],
    "links": {
        "details": "https://ard.maxar.com/api/v1/metadata/query/Q585740411116825844",
        "geojson": "https://ard.maxar.com/api/v1/metadata/query/Q58574041111682582844/results?format=geojson",
        "stac": "https://ard.maxar.com/api/v1/metadata/query/Q58574041111682582844/results?format=stac",
        "acquisitions": "https://ard.maxar.com/api/v1/metadata/query/Q58574041111682582844/results?format=order"
    }
}

STAC format

{
    "type": "FeatureCollection",
    "collections": [
        {
            "type": "Collection",
            "stac_version": "1.0.0",
            "stac_extensions": [],
            "id": "Z36-300202300130",
            "title": "ARD tiles in grid cell Z36-300202300130",
            "description": "ARD tiles in grid cell Z36-300202300130",
            "license": "proprietary",
            "providers": [
                {
                    "name": "Maxar"
                }
            ],
            "extent": {
                "spatial": {
                    "bbox": [
                        34.775618309298956,
                        -16.047465748031563,
                        34.822738616301926,
                        -16.001894439485305
                    ]
                },
                "temporal": {
                    "interval": [
                        [
                            "2022-02-03T08:18:02Z",
                            "2022-02-03T08:18:02Z"
                        ]
                    ]
                }
            },
            "links": [
                {
                    "rel": "self",
                    "href": "https://ard.maxar.com/api/v1/metadata/cells/Z36-300202300130/acquisitions?format=stac"
                },
                {
                    "rel": "query_details",
                    "href": "https://ard.maxar.com/api/v1/metadata/query/Q5857410049440093178"
                },
                {
                    "rel": "item",
                    "href": "https://ard.maxar.com/api/v1/metadata/cells/Z36-300202300130/acquisitions/1050010029A54C00?format=stac"
                }
            ],
            "assets": {}
        }
    ],
    "features": [
        {
            "type": "Feature",
            "geometry": {
                "type": "Polygon",
                "coordinates": [
                    [
                        [
                            34.82273861630193,
                            -16.04707339977968
                        ],
                        [
                            34.77601814069492,
                            -16.04746574803156
                        ],
                        [
                            34.77561830929896,
                            -16.00228562562127
                        ],
                        [
                            34.82232828082863,
                            -16.00189443948531
                        ],
                        [
                            34.82273861630193,
                            -16.04707339977968
                        ]
                    ]
                ]
            },
            "properties": {
                "cell_id": "Z36-300202300130",
                "acquisition_id": "1050010029A54C00",
                "constellation": "digitalglobe",
                "date": "2022-02-03",
                "datetime": "2022-02-03T08:18:02Z",
                "eo:cloud_cover": 6.814534544606911,
                "instruments": [
                    "VNIR"
                ],
                "modified": "2022-02-03T10:34:26Z",
                "multi_resolution_avg": 2.9380573285714284,
                "multi_resolution_max": 2.956368,
                "multi_resolution_min": 2.9170208,
                "off_nadir_max": 41.89689,
                "off_nadir_min": 41.503822,
                "pan_resolution_avg": 0.7340485642857143,
                "pan_resolution_max": 0.7386181,
                "pan_resolution_min": 0.7287985,
                "platform": "geoeye-01",
                "tile:cloud_free_percentage": 100,
                "tile:cloud_percentage": 0,
                "tile:data_percentage": 100,
                "tile:no_data_percentage": 0,
                "tile:quadkey": "300202300130",
                "tile:zone": 36,
                "view:azimuth": 50.070378285714284,
                "view:off_nadir": 41.714803857142854,
                "view:sun_azimuth": 94.91849228571428,
                "view:sun_elevation": 66.89916,
                "tile:cloud_polys": null,
                "aoi:data_area_sqkm": 1,
                "aoi:data_percentage": 100,
                "aoi:cloud_free_percentage": 100
            },
            "stac_version": "1.0.0",
            "stac_extensions": [
                "https://stac-extensions.github.io/eo/v1.0.0/schema.json",
                "https://stac-extensions.github.io/view/v1.0.0/schema.json"
            ],
            "bbox": [
                34.77561830929896,
                -16.04746574803156,
                34.82273861630193,
                -16.00189443948531
            ],
            "links": [
                {
                    "rel": "self",
                    "href": "https://ard.maxar.com/api/v1/metadata/cells/Z36-300202300130/acquisitions/1050010029A54C00?format=stac"
                },
                {
                    "rel": "collection",
                    "href": "https://ard.maxar.com/api/v1/metadata/cells/Z36-300202300130/acquisitions?format=stac"
                }
            ],
            "assets": {
                "preview": {
                    "title": "Preview of 1050010029A54C00 in grid cell Z36-300202300130",
                    "type": "image/jpeg",
                    "roles": [
                        "thumbnail"
                    ],
                    "href": "https://ard.maxar.com/api/v1/browse/preview/1050010029A54C00/Z36-300202300130"
                }
            },
            "id": "Z36-300202300130/1050010029A54C00"
        }
    ],
    "query_id": "Q5857410049440093178",
        "query_name":"Albuquerque NM USA",
    "links": {
        "details": "https://ard.maxar.com/api/v1/metadata/query/Q58574100494400931788",
        "geojson": "https://ard.maxar.com/api/v1/metadata/query/Q58574100494400931788/results?format=geojson",
        "stac": "https://ard.maxar.com/api/v1/metadata/query/Q58574100494400931788/results?format=stac",
        "acquisitions": "https://ard.maxar.com/api/v1/metadata/query/Q58574100494400931788/results?format=order"
    }
}

List cells in an AOI

POST /metadata/cells

Query for a list of cells that cover an AOI.

Query parameters

param description example
format Choose the format for the query response. Allowed values are "ids" and "geojson" format=geojson

Example request:

POST https://ard.maxar.com/api/v1/metadata/cells?format=ids

Request body

This query requires a request body with an AOI in "bbox" or "intersects" format.

Example request with a bounding box AOI.

{
   "bbox": [-106.8, 35.1, -106.4, 35.4]
}

Example request with a WKT polygon AOI:

{
    "intersects": "POLYGON ((-106.8 35.1,-106.4 35.1,-106.4 35.4,-106.8 35.4,-106.8 35.1))"
}

Response

Example response in an "ids" list format:

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

Example response in GeoJSON format:

{
    "type": "FeatureCollection",
    "features": [
        {
            "type": "Feature",
            "properties": {
                "id": "Z13-031133231111"
            },
            "geometry": {
                "type": "Polygon",
                "coordinates": [
                    [
                        [
                            -106.76116801661404,
                            35.36549648670249
                        ],
                        [
                            -106.76214815453802,
                            35.41055942822295
                        ],
                        [
                            -106.81719094073765,
                            35.409743594237504
                        ],
                        [
                            -106.81618022745944,
                            35.36468200254137
                        ],
                        [
                            -106.76116801661404,
                            35.36549648670249
                        ]
                                            ]
                                        ]
                                    }
}
                                ]
}

Get metadata for a specific tile

GET /metadata/cells/{cell_id}/acquisitions/{acquisition_id}

Path parameters

parameter description example
cell_id The id for the Maxar grid cell. The naming convention for the cell ID is {UTM zone}-{quadkey address} Z17-120022203221
acquisition_id The acquisition ID for the image. 104001007297D800

Response

Returns a GeoJSON feature for the tile and its metadata.

See Tile metadata response examples.

More resources

Metadata Overview

Tile Metadata Properties

Query resource

Cell Summary Resource

Back to top