Tile Metadata Resource¶
Last updated: August 29, 2022
Resource paths¶
/metadata/cells
/metadata/cells/acquisitions
Metadata requests¶
| 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
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
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
intersectsorbboxfield
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",
"cell_ids": [
"Z36-300202300130"
]
},
{
"id": "1040010073834100",
"cell_ids": [
"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.