API Tutorial¶

This document describes for developers how to use the Maxar Catalog REST API.

Sample requests to the API are demonstrated using curl commands in a bash shell. This is a low-level way of using the API and some curl commands may be difficult to understand at first. But using curl has the benefit of showing the exact URL's and query parameters necessary to use the API.

For application development a higher-level client library will generally be used. Possible options are the maxar-catalog Python package or a client library generated directly from the API's OpenAPI specification.

Introduction¶

The Catalog API is small — just a few methods for requesting collections, items, and performing searches. For most users the search method will be the one most often used.

Important notes¶

This Jupyter notebook requires the bash kernel with the curl and jq commands available. If you do not have a Jupyter bash kernel available you can copy-and-paste commands in this notebook into a bash shell. Or just read this as documentation without running the commands.

The base URL for the Catalog API is https://api.content.maxar.com/catalog.

Authentication¶

All requests to the catalog API require an HTTP Authentication header with an OAuth2 bearer token.

See Content Hub Authorization for instructions on obtaining a token.

Assuming you have the token in a Bash variable token create the Authorization header like this:

In [42]:

            
                Copied!
                
auth_header="Authorization: Bearer $token"
echo $auth_header
auth_header="Authorization: Bearer $token"
echo $auth_header

Authorization: Bearer

All of the examples in this document pass this auth_header in curl commands.

Health check¶

The API has a healthcheck endpoint that can be used to ping the catalog service and make sure it is available. It's also an easy way to make sure your token is valid, and you're sending a valid Authentiation header:

In [11]:

            
                Copied!
                
curl -s -H "$auth_header" https://api.content.maxar.com/catalog/healthcheck | jq
curl -s -H "$auth_header" https://api.content.maxar.com/catalog/healthcheck | jq

{
  "database": "OK",
  "overall": "OK"
}

The response indicates the status of various services that the catalog depends on, plus an overall status. Currently, the only service the catalog depends on is its internal database.

A request to any API endpoint without valid authentication will return a 401 status as shown below. If you see this response to any call to the API check that you generated a token correctly, that your token hasn't expired, and that you are correctly passing an Authentication header:

In [12]:

            
                Copied!
                
curl -s -i -H "Authentication: Bearer foo" https://api.content.maxar.com/catalog/healthcheck
curl -s -i -H "Authentication: Bearer foo" https://api.content.maxar.com/catalog/healthcheck

HTTP/2 401 
date: Mon, 03 Oct 2022 16:33:11 GMT
content-type: application/json
content-length: 26
server: nginx
x-amzn-requestid: 9819d27f-83e0-413e-8e8c-cf40caf441ee
x-amzn-errortype: UnauthorizedException
x-amz-apigw-id: Zb8_MGdcIAMFThw=

{"message":"Unauthorized"}

Collections¶

Catalog items are organized into collections. See the STAC specification for a description of collections and their properties.

Searching collections¶

If you want to search through our available collections, we support pagination through the GET /collections endpoint with the orderby, limit, and page parameters.

The value of orderby is a SQL-style ordering clause. However, only two properties are supported for ordering: datetime and id. Each may have an optional ASC or DESC modifier, where ASC is the default and may be omitted.

The value of the limit parameter supports a maximum value of 100 currently.

In [39]:

            
                Copied!
                
curl -s -H "$auth_header" "https://api.content.maxar.com/catalog/collections?orderby=datetime+DESC&limit=5&page=50"
curl -s -H "$auth_header" "https://api.content.maxar.com/catalog/collections?orderby=datetime+DESC&limit=5&page=50"

{"collections": [{"id": "Vivid_Premium_Kurgan_RU_22Q3", "links": [{"rel": "alternate", "href": "https://api.content.maxar.com/catalog/mosaic-item.json", "type": "application/json", "title": "Vivid_Premium_Kurgan_RU_22Q3"}, {"rel": "items", "href": "https://api.content.maxar.com/catalog/collections/Vivid_Premium_Kurgan_RU_22Q3/items", "type": "application/geo+json"}], "title": "Vivid_Premium_Kurgan_RU_22Q3", "extent": {"spatial": {"bbox": [[65.1708984375, 55.2392578125, 65.522460937, 55.546875]]}, "temporal": {"interval": [["2015-05-23T07:00:19.516000Z", "2022-08-03T07:08:34.275000Z"]]}}, "license": "proprietary", "keywords": ["maxar", "flame"], "providers": [{"url": "https://www.maxar.com", "name": "maxar"}], "properties": {"title": "Vivid_Premium_Kurgan_RU_22Q3", "datetime": "2022-09-14T13:00:19Z", "resolution": 0.15}, "description": "STAC collection for mosaic Vivid_Premium_Kurgan_RU_22Q3", "stac_version": "0.9.0"}, {"id": "Vivid_Standard_RU54_22Q3", "links": [{"rel": "alternate", "href": "https://api.content.maxar.com/catalog/mosaic-item.json", "type": "application/json", "title": "Vivid_Standard_RU54_22Q3"}, {"rel": "items", "href": "https://api.content.maxar.com/catalog/collections/Vivid_Standard_RU54_22Q3/items", "type": "application/geo+json"}], "title": "Vivid_Standard_RU54_22Q3", "extent": {"spatial": {"bbox": [[105.380859375, 49.130859375, 112.587890625, 54.931640625]]}, "temporal": {"interval": [["2009-06-02T03:53:46.000000Z", "2022-08-29T04:10:26.000000Z"]]}}, "license": "proprietary", "keywords": ["maxar", "flame"], "providers": [{"url": "https://www.maxar.com", "name": "maxar"}], "properties": {"title": "Vivid_Standard_RU54_22Q3", "datetime": "2022-09-14T22:49:06Z", "resolution": 0.5}, "description": "STAC collection for mosaic Vivid_Standard_RU54_22Q3", "stac_version": "0.9.0"}, {"id": "Vivid_Standard_SY01_22Q3", "links": [{"rel": "alternate", "href": "https://api.content.maxar.com/catalog/mosaic-item.json", "type": "application/json", "title": "Vivid_Standard_SY01_22Q3"}, {"rel": "items", "href": "https://api.content.maxar.com/catalog/collections/Vivid_Standard_SY01_22Q3/items", "type": "application/geo+json"}], "title": "Vivid_Standard_SY01_22Q3", "extent": {"spatial": {"bbox": [[35.068359375, 32.255859375, 42.451171875, 37.353515625]]}, "temporal": {"interval": [["2007-06-17T08:40:46.000000Z", "2022-08-28T08:03:22.000000Z"]]}}, "license": "proprietary", "keywords": ["maxar", "flame"], "providers": [{"url": "https://www.maxar.com", "name": "maxar"}], "properties": {"title": "Vivid_Standard_SY01_22Q3", "datetime": "2022-09-14T19:45:38Z", "resolution": 0.5}, "description": "STAC collection for mosaic Vivid_Standard_SY01_22Q3", "stac_version": "0.9.0"}, {"id": "Vivid_Standard_RU06_22Q3", "links": [{"rel": "alternate", "href": "https://api.content.maxar.com/catalog/mosaic-item.json", "type": "application/json", "title": "Vivid_Standard_RU06_22Q3"}, {"rel": "items", "href": "https://api.content.maxar.com/catalog/collections/Vivid_Standard_RU06_22Q3/items", "type": "application/geo+json"}], "title": "Vivid_Standard_RU06_22Q3", "extent": {"spatial": {"bbox": [[72.94921875, 64.599609375, 81.650390625, 73.564453125]]}, "temporal": {"interval": [["2003-08-15T06:17:27.000000Z", "2022-09-03T07:32:25.000000Z"]]}}, "license": "proprietary", "keywords": ["maxar", "flame"], "providers": [{"url": "https://www.maxar.com", "name": "maxar"}], "properties": {"title": "Vivid_Standard_RU06_22Q3", "datetime": "2022-09-14T07:01:03Z", "resolution": 0.5}, "description": "STAC collection for mosaic Vivid_Standard_RU06_22Q3", "stac_version": "0.9.0"}, {"id": "Vivid_Premium_Kemerovo_RU_22Q3", "links": [{"rel": "alternate", "href": "https://api.content.maxar.com/catalog/mosaic-item.json", "type": "application/json", "title": "Vivid_Premium_Kemerovo_RU_22Q3"}, {"rel": "items", "href": "https://api.content.maxar.com/catalog/collections/Vivid_Premium_Kemerovo_RU_22Q3/items", "type": "application/geo+json"}], "title": "Vivid_Premium_Kemerovo_RU_22Q3", "extent": {"spatial": {"bbox": [[85.869140625, 55.1953125, 86.396484375, 55.810546875]]}, "temporal": {"interval": [["2019-07-12T05:54:07.113000Z", "2022-07-28T05:35:44.881000Z"]]}}, "license": "proprietary", "keywords": ["maxar", "flame"], "providers": [{"url": "https://www.maxar.com", "name": "maxar"}], "properties": {"title": "Vivid_Premium_Kemerovo_RU_22Q3", "datetime": "2022-09-14T05:54:37Z", "resolution": 0.15}, "description": "STAC collection for mosaic Vivid_Premium_Kemerovo_RU_22Q3", "stac_version": "0.9.0"}], "numberReturned": 5, "timestamp": "2022-10-03T17:12:59.479358Z", "links": [{"rel": "next", "href": "https://api.content.maxar.com/catalog/collections?limit=5&orderby=datetime+DESC&page=51", "type": "application/geo+json"}]}

Viewing a collection¶

The canonical path of a collection is /collections/{collectionId}.

Perform a GET on this path to see a collection's defintion. For example here is the definition of the "wv02" collection:

In [34]:

            
                Copied!
                
curl -s -H "$auth_header" https://api.content.maxar.com/catalog/collections/wv02 | jq
curl -s -H "$auth_header" https://api.content.maxar.com/catalog/collections/wv02 | jq

{
  "id": "wv02",
  "type": "Collection",
  "links": [
    {
      "rel": "root",
      "href": "https://api.content.maxar.com/catalog/dg-archive.json",
      "type": "application/json"
    },
    {
      "rel": "items",
      "href": "https://api.content.maxar.com/catalog/wv02/items",
      "type": "application/geo+json"
    },
    {
      "rel": "data-sheet",
      "href": "https://dgv4-cms-production.s3.amazonaws.com/uploads/document/file/130/WorldView2-DS-WV2-rev2.pdf",
      "type": "application/pdf"
    }
  ],
  "title": "WorldView-2",
  "assets": {},
  "extent": {
    "spatial": {
      "bbox": [
        [
          -180,
          -90,
          180,
          90
        ]
      ]
    },
    "temporal": {
      "interval": [
        [
          "2009-10-08T00:00:00Z",
          null
        ]
      ]
    }
  },
  "license": "proprietary",
  "providers": [
    {
      "url": "https://www.maxar.com/",
      "name": "Maxar",
      "roles": [
        "producer",
        "licensor"
      ]
    }
  ],
  "summaries": {
    "gsd": {
      "description": "Average size of pixel when mapped to the ground. Values in meters."
    },
    "title": {
      "description": "Title of item containing the item's vehichle name and item ID."
    },
    "datetime": {
      "description": "ISO-8601 formatted UTC datetime string of when the collection of the image began."
    },
    "eo:bands": {
      "description": "List of band objects that contain the name of each individual satellite sensor band and the center wavelength value of that band."
    },
    "platform": {
      "description": "Unabbreviated name of satellite platform an image was taken with."
    },
    "instruments": {
      "values": [
        "SWIR",
        "VNIR",
        "KMPS5",
        "aerial",
        "KS5",
        "AEISS-A",
        "AEISS",
        "OE-VNIR",
        "other"
      ],
      "description": "Sensor for image."
    },
    "associations": {
      "description": "List of objects that contain the id of the association item the image is a part of (association_identifier) and association type (association_type). Possible association types are VNIR_SWIR, VNIR_CAVIS, and SWIR_CAVIS."
    },
    "view:azimuth": {
      "range": {
        "maximum": 360,
        "minimum": 0
      },
      "description": "Average value of the angle between the vector pointing true North from the spacecraft and the sample point's vector on the horizontal plane. Values in degrees."
    },
    "constellation": {
      "values": [
        "maxar"
      ],
      "description": "Name of constellation that collection belongs to."
    },
    "off_nadir_avg": {
      "range": {
        "maximum": 90,
        "minimum": 0
      },
      "description": "Average angle between the nadir (the point right above the target) and the vector between the sensor and the target. Values in degrees."
    },
    "off_nadir_end": {
      "range": {
        "maximum": 90,
        "minimum": 0
      },
      "description": "End angle between the nadir (the point right above the target) and the vector between the sensor and the target. Values in degrees."
    },
    "off_nadir_max": {
      "range": {
        "maximum": 90,
        "minimum": 0
      },
      "description": "Maximum angle between the nadir (the point right above the target) and the vector between the sensor and the target. Values in degrees."
    },
    "off_nadir_min": {
      "range": {
        "maximum": 90,
        "minimum": 0
      },
      "description": "Minimum angle between the nadir (the point right above the target) and the vector between the sensor and the target.Values in degrees."
    },
    "rda_available": {
      "values": [
        false,
        true
      ],
      "description": "Whether or not an image is available in RDA."
    },
    "eo:cloud_cover": {
      "description": "Percentage of image that is covered by clouds."
    },
    "scan_direction": {
      "values": [
        "Forward",
        "Reverse"
      ],
      "description": "Direction of image scan."
    },
    "view:off_nadir": {
      "range": {
        "maximum": 90,
        "minimum": 0
      },
      "description": "Average angle between the nadir (the point right above the target) and the vector between the sensor and the target. Values in degrees."
    },
    "off_nadir_start": {
      "range": {
        "maximum": 90,
        "minimum": 0
      },
      "description": "Start angle between the nadir (the point right above the target) and the vector between the sensor and the target. Values in degrees."
    },
    "collect_time_end": {
      "description": "ISO-8601 formatted UTC datetime string of when the collection of the image ended."
    },
    "view:sun_azimuth": {
      "range": {
        "maximum": 360,
        "minimum": 0
      },
      "description": "Average of the angle between the vector pointing true North from the sample point and the sun's vector on the horizontal plane. Values in degrees."
    },
    "raw_archive_state": {
      "values": [
        "offline",
        "online"
      ],
      "description": "Current state of the image in raw archive."
    },
    "collect_time_start": {
      "description": "ISO-8601 formatted UTC datetime string of when the collection of the image began."
    },
    "pan_resolution_avg": {
      "description": "Average size of pixel when mapped to the ground for pan bandsets. Values in meters."
    },
    "pan_resolution_end": {
      "description": "End size of pixel when mapped to the ground for pan bandsets. Values in meters."
    },
    "pan_resolution_max": {
      "description": "Maximum size of pixel when mapped to the ground for pan bandsets. Values in meters."
    },
    "pan_resolution_min": {
      "description": "Minimum size of pixel when mapped to the ground for pan bandsets. Values in meters."
    },
    "view:sun_elevation": {
      "range": {
        "maximum": 90,
        "minimum": -90
      },
      "description": "Angle of the sun above the horizon, viewed from the given sample point. Values in degrees."
    },
    "multi_resolution_avg": {
      "description": "Average size of pixel when mapped to the ground for multispectral bandsets. Values in meters."
    },
    "multi_resolution_end": {
      "description": "End size of pixel when mapped to the ground for multispectral bandsets. Values in meters."
    },
    "multi_resolution_max": {
      "description": "Maximum size of pixel when mapped to the ground for multispectral bandsets. Values in meters."
    },
    "multi_resolution_min": {
      "description": "Minimum size of pixel when mapped to the ground for multispectral bandsets. Values in meters."
    },
    "pan_resolution_start": {
      "description": "Start size of pixel when mapped to the ground for pan bandsets. Values in meters."
    },
    "acquisition_rev_number": {
      "description": "Revolution number of the satellite in which the image was acquired/collected"
    },
    "multi_resolution_start": {
      "description": "Start size of pixel when mapped to the ground for multispectral bandsets. Values in meters."
    },
    "stereo_pair_identifiers": {
      "description": "List of stereo pair identifiers that the image is part of."
    },
    "spacecraft_to_target_azimuth_avg": {
      "range": {
        "maximum": 360,
        "minimum": 0
      },
      "description": "Average value of the angle between the vector pointing true North from the spacecraft and the sample point's vector on the horizontal plane. Values in degrees."
    },
    "spacecraft_to_target_azimuth_end": {
      "range": {
        "maximum": 360,
        "minimum": 0
      },
      "description": "End value of the angle between the vector pointing true North from the spacecraft and the sample point's vector on the horizontal plane. Values in degrees."
    },
    "spacecraft_to_target_azimuth_max": {
      "range": {
        "maximum": 360,
        "minimum": 0
      },
      "description": "Maximum value of the angle between the vector pointing true North from the spacecraft and the sample point's vector on the horizontal plane. Values in degrees."
    },
    "spacecraft_to_target_azimuth_min": {
      "range": {
        "maximum": 360,
        "minimum": 0
      },
      "description": "Minimum value of the angle between the vector pointing true North from the spacecraft and the sample point's vector on the horizontal plane. Values in degrees."
    },
    "target_to_spacecraft_azimuth_avg": {
      "range": {
        "maximum": 360,
        "minimum": 0
      },
      "description": "Average value of the angle between vector pointing true North from the sample point and the spacecraft's vector on the horizontal plane. Values in degrees."
    },
    "target_to_spacecraft_azimuth_end": {
      "range": {
        "maximum": 360,
        "minimum": 0
      },
      "description": "End value of the angle between the vector pointing true North from the sample point and the spacecraft's vector on the horizontal plane. Values in degrees."
    },
    "target_to_spacecraft_azimuth_max": {
      "range": {
        "maximum": 360,
        "minimum": 0
      },
      "description": "Maximum value of the angle between the vector pointing true North from the sample point and the spacecraft's vector on the horizontal plane. Values in degrees."
    },
    "target_to_spacecraft_azimuth_min": {
      "range": {
        "maximum": 360,
        "minimum": 0
      },
      "description": "Minimum value of the angle between the vector pointing true North from the sample point and the spacecraft's vector on the horizontal plane. Values in degrees."
    },
    "spacecraft_to_target_azimuth_start": {
      "range": {
        "maximum": 360,
        "minimum": 0
      },
      "description": "Start value of the angle between the vector pointing true North from the spacecraft and the sample point's vector on the horizontal plane. Values in degrees."
    },
    "target_to_spacecraft_azimuth_start": {
      "range": {
        "maximum": 360,
        "minimum": 0
      },
      "description": "Start value of the angle between the vector pointing true North from the sample point and the spacecraft's vector on the horizontal plane. Values in degrees."
    },
    "target_to_spacecraft_elevation_avg": {
      "range": {
        "maximum": 90,
        "minimum": 0
      },
      "description": "Average angle of the spacecraft above the horizon, viewed from sample point. Values in degrees."
    },
    "target_to_spacecraft_elevation_end": {
      "range": {
        "maximum": 90,
        "minimum": 0
      },
      "description": "End angle of the spacecraft above the horizon, viewed from sample point. Values in degrees."
    },
    "target_to_spacecraft_elevation_max": {
      "range": {
        "maximum": 90,
        "minimum": 0
      },
      "description": "Maximum angle of the spacecraft above the horizon, viewed from sample point. Values in degrees."
    },
    "target_to_spacecraft_elevation_min": {
      "range": {
        "maximum": 90,
        "minimum": 0
      },
      "description": "Minimum angle of the spacecraft above the horizon, viewed from sample point. Values in degrees."
    },
    "target_to_spacecraft_elevation_start": {
      "range": {
        "maximum": 90,
        "minimum": 0
      },
      "description": "Start angle of the spacecraft above the horizon, viewed from sample point. Values in degrees."
    }
  },
  "properties": {
    "eo:platform": "worldview-02",
    "eo:instrument": "VNIR",
    "eo:constellation": "maxar"
  },
  "description": "WorldView-2 Imagery",
  "stac_version": "1.0.0"
}

Items¶

The canonical path to an item is /collections/{collectionId}/items/{itemId}. So to directly GET an item this way you must know its collection. (However see below for documentation of the /search endpoint where items may be queried by id without regard to collection.)

Here is an example of getting the image 1020010010DD0000 in the wv01 collection:

In [14]:

            
                Copied!
                
curl -s -H "$auth_header" https://api.content.maxar.com/catalog/collections/wv01/items/1020010010DD0000 | jq
curl -s -H "$auth_header" https://api.content.maxar.com/catalog/collections/wv01/items/1020010010DD0000 | jq

{
  "id": "1020010010DD0000",
  "bbox": [
    -71.770808,
    -74.794935,
    -71.010839,
    -74.71916
  ],
  "type": "Feature",
  "links": [
    {
      "rel": "collection",
      "href": "https://api.content.maxar.com/catalog/collections/wv01"
    },
    {
      "rel": "root",
      "href": "https://api.content.maxar.com/catalog/collections/dg-archive"
    },
    {
      "rel": "self",
      "href": "https://api.content.maxar.com/catalog/collections/wv01/items/1020010010DD0000"
    }
  ],
  "assets": {
    "browse": {
      "href": "https://api.content.maxar.com/catalog/collections/wv01/items/1020010010DD0000/assets/collections/dg-archive/assets/browse/1020010010DD0000.browse.tif",
      "type": "image/tiff; application=geotiff",
      "title": "Browse Image"
    },
    "cloud-cover": {
      "href": "https://api.content.maxar.com/catalog/collections/wv01/items/1020010010DD0000/assets/collections/wv01/assets/cloud-cover/1020010010DD0000.cloud.json",
      "type": "application/geo+json",
      "title": "Cloud Cover"
    },
    "sample-point-set": {
      "href": "https://api.content.maxar.com/catalog/collections/wv01/items/1020010010DD0000/assets/collections/wv01/assets/sample-point-sets/1020010010DD0000.sample-points.json",
      "type": "application/geo+json",
      "title": "Sample Point Set"
    }
  },
  "geometry": {
    "type": "Polygon",
    "coordinates": [
      [
        [
          -71.770808,
          -74.727724
        ],
        [
          -71.770734,
          -74.794935
        ],
        [
          -71.010839,
          -74.786512
        ],
        [
          -71.010931,
          -74.71916
        ],
        [
          -71.770808,
          -74.727724
        ]
      ]
    ]
  },
  "collection": "wv01",
  "properties": {
    "gsd": 0.707835555077,
    "title": "DigitalGlobe WV01 Image 1020010010DD0000",
    "datetime": "2011-02-09T13:11:08.974402Z",
    "eo:bands": [
      {
        "name": "pan",
        "center_wavelength": 650
      }
    ],
    "platform": "worldview-01",
    "instruments": [
      "VNIR"
    ],
    "associations": [],
    "view:azimuth": 6.24952793121,
    "constellation": "digitalglobe",
    "off_nadir_avg": 32.9030418396,
    "off_nadir_end": 32.7110824585,
    "off_nadir_max": 33.0951957703,
    "off_nadir_min": 32.7110824585,
    "rda_available": false,
    "eo:cloud_cover": 98.9121283347,
    "scan_direction": "reverse",
    "view:off_nadir": 32.9030418396,
    "off_nadir_start": 33.0951957703,
    "collect_time_end": "2011-02-09T13:11:09.390358Z",
    "view:sun_azimuth": 61.6186828613,
    "collect_time_start": "2011-02-09T13:11:08.974402Z",
    "pan_resolution_avg": 0.707835555077,
    "pan_resolution_end": 0.705121338367,
    "pan_resolution_max": 0.710432112217,
    "pan_resolution_min": 0.705121338367,
    "view:sun_elevation": 22.5309238434,
    "multi_resolution_avg": null,
    "multi_resolution_end": null,
    "multi_resolution_max": null,
    "multi_resolution_min": null,
    "pan_resolution_start": 0.710432112217,
    "acquisition_rev_number": 18885,
    "multi_resolution_start": null,
    "stereo_pair_identifiers": [
      "67aff054-1d95-4c34-8ab2-f07a844d93af-inv"
    ],
    "spacecraft_to_target_azimuth_avg": 6.24952793121,
    "spacecraft_to_target_azimuth_end": 6.47290420532,
    "spacecraft_to_target_azimuth_max": 6.47290420532,
    "spacecraft_to_target_azimuth_min": 6.02687835693,
    "target_to_spacecraft_azimuth_avg": null,
    "target_to_spacecraft_azimuth_end": null,
    "target_to_spacecraft_azimuth_max": null,
    "target_to_spacecraft_azimuth_min": null,
    "spacecraft_to_target_azimuth_start": 6.02687835693,
    "target_to_spacecraft_azimuth_start": null,
    "target_to_spacecraft_elevation_avg": null,
    "target_to_spacecraft_elevation_end": null,
    "target_to_spacecraft_elevation_max": null,
    "target_to_spacecraft_elevation_min": null,
    "target_to_spacecraft_elevation_start": null
  },
  "stac_version": "1.0.0-beta.2",
  "stac_extensions": [
    "eo",
    "view",
    "https://schemas.content.maxar.com/schemas/maxar-stac-item-extension-schema-1-0.json"
  ]
}

See the STAC item specification for descriptions of the properties of a STAC item.

Search overview¶

This section describes the API's search command. It provides query parameters for searching the catalog in a variey of ways including area of interest, time, and by arbitrary STAC item properties.

Important notes¶

Some of the query parameters used by the Maxar Catalog's search method do not match those in the current STAC API specification. When version 1.0 of the STAC API specification is released the Maxar Catalog API might change in minor ways that are not backward compatible.

Here are some current differences:

The Maxar Catalog search method supports a query parameter where for specifying a SQL-style where-clause on STAC item properties. The STAC API specification does not support this search parameter. However, there is a proposal for a query parameter that supports searches on item properties using a JSON-style syntax instead of a SQL-style syntax. See here for information.

But see also the emerging OAFeat specification where a query parameter that supports SQL-style where-clauses is described. So it is still undetermined what an eventual query parameter will look like in the final API.
The Maxar Catalog search method supports an orderby parameter which allows SQL-style sorting on the id and datetime properties. The STAC API specification instead proposes an extension for a sort parameter. See here
The Maxar Catalog search method does not yet support the fields query parameter described as a possible extension in the current STAC API specification.

Search method endpoints¶

There are actually two endpoints that can be used to search the catalog:

/search
/collections/{collectionId}/items

The /search endpoint is the primary method for searching. But every collection also has its own endpoint for searching just its items. Both of these endpoints support the same query parameters except for collections. The collection-specific endpoint does not support the collections query parameter since it is intended for searching only items in its collection, as specified by collectionId in the URL's path. But internally both of these search endpoints operate the same way. If you are searching on a particular collection there is no real difference in calling search and using the collections query parameter, or calling the collection-specific search endpoint.

The rest of this document will describe calling the /search method with the understanding that everything applies to the collection-specific search endpoint as well, except for the handling of the collections query parameter.

Query parameters¶

Query parameters supported by the search methods are described in the STAC specification here. Since the parameters supported by the Maxar Catalog differ somewhat here are the actual parameters supported:

Parameter	Description
collections	List of collections to restrict search to
ids	List of item IDs to query
bbox	Bounding box of coordinates in the order west,south,east,north
intersects	GeoJSON geometry
datetime	Datetime interval, either closed or open ended
where	SQL-style where clause
orderby	SQL-style order clause on the properties `datetime` and/or `id`
limit	Page size
page	Page number to retrieve, starting from page 1

The bbox and intersects parameters are mutually exclusive.

The bbox parameter may include elevation values as the STAC specification allows, but the search methods currently ignore them.

The ids parameter is generally used by itself to retrieve one or more particular features. But additional parameters may be specified along with ids to further restrict the query. Note that this is different behavior from what is described in the STAC API specification.

As mentioned earlier the collections parameter may not be used when searching on a collection-specific endpoint.

Details¶

The search methods always return a GeoJSON FeatureCollection, even if the response contains only a single feature. If no features satisfy the search criteria then the response is a GeoJSON FeatureCollection with an empty features array.

There is a 30-second timeout on all queries. A query that times out will generally return an HTTP status code of 504.

The search methods support three different ways of specifying query parameters. Internally the search is performed the same way — these are just different ways of calling the search method:

GET using URL query parameters
POST using form parameters (Content-Type application/x-www-form-urlencoded)
POST using JSON body containing query parameters (Content-Type application/json)

The examples later in this document demonstrate each of these methods.

The query parameters collections, ids, and bbox each specify a list of values. When using the first two query methods specify a string with comma-separated values. But when posting a JSON body specify a JSON array.

When using the intersects query parameter you should usually use the third method of posting a JSON object, since a GeoJSON geometry can be large. It may be easier to work with as a property inside a JSON object. But it is possible to pass an intersects query parameter using the first two methods, in which case its value is a JSON-encoded string.

Paging and ordering¶

The search methods always page their results and are currently configured with a page size of 100 features. The search method's limit and page query parameters can be used to repeatedly request result pages until the full results of a search are received.

The Maxar Catalog search does not currently handle paging the way it is described in the current STAC API specification. The specification describes returning a link in the response to a URL for fetching the next page of results. If this remains in the API's version 1.0 release then the catalog will implement it then.

There is always an ordering applied to the results of any query since it's necessary for paging to work. This default is descending order by the standard STAC item property "datetime". In the unlikely event that two STAC items have the same datetime value the item id is used as a secondary sort property.

The search endpoints support a orderby query parameter for providing a different ordering. The value of orderby is a SQL-style ordering clause. However, only two properties are supported for ordering: datetime and id. Each may have an optional ASC or DESC modifier, where ASC is the default and may be omitted.

Here are few examples of allowed orderby values:

datetime DESC, id (default ordering if none specified)
datetime ASC
id ASC
id DESC

The orderby parameter does not support ordering by arbitrary STAC item properties, such as eo:cloud_cover. Clients that need such ordering have to perform it on the client side.

Efficient searches using spatial and temporal filters¶

A STAC catalog is intended to be searched spatially and/or temporally. This is how the Maxar Catalog is intended to be searched. It is not strictly required that a search include a spatial and/or temporal component, but searches that don't run the risk of timing out before they are able to complete. This is especially the case when using the where query parameter. It is important to provide either a spatial or temporal filter to cut down the search's set of candidate features before the where clause is applied.

A spatial search is performed by specifying either the bbox or intersects query parameters. The bbox parameter is for simple spatial searches on a bounding box of west, east, south, and north coordinates. The intersects parameter is for searching on an arbitrary GeoJSON geometry. In either case a catalog feature satisfies the spatial query if it intersects the bounding box or geometry.

Temporal searches are performed on the datetime property that every STAC item is required to have.

Datetime values in STAC items and queries are always required to have the format "yyyy-mm-ddThh:mm:ssZ" (see RFC 3339 Section 5.6). The seconds may have a fractional component as well.

The value of the datetime query parameter can specify either a closed time range or an open-ended time range, with a slash indicating how its value is interpreted:

`datetime` query value	Description
start-time/end-time	Feature datetime between start-time (inclusive) and end-time (exclusive)
start-time/	Feature datetime greater than or equal to start-time
/end-time	Feature datetime less than end-time

There are some searches that can be performed efficiently without a spatial or temporal component. Searching by item ID using the ids query parameter is always fast. Searching on a single collection with no other query parameter will be fast, with features returned by the default ordering of decreasing datetime.

Performing a query using only the where query parameter will not be efficient and will likely time out.

Specifying collections when searching¶

A query against the /search endpoint operates on all collections in the Maxar catalog. Many users will want to search only for satellite imagery, but might get unexpected results since the catalog contains geospatial products besides just imagery from Maxar satellites. For example the catalog contains collections for mosaics, imagery stereo pairs, digital elevation models, and other products.

If you are only searching for Maxar imagery you should do this in one of two ways. You can use the endpoint /collections/{collectionId}/items to search for images from one particular satellite. Or you can use the /search endpoint and specify the collections query parameter, which is a list of collections to search. When searching for imagery one of these two methods should be used to avoid receiving unexpected STAC items in the response from unrelated collections.

In the common situation where you want to search the catalog for any Maxar satellite imagery you should specify the collections to search as "ge01", "wv01", "wv02", "wv03-vnir", and "wv04".

Search examples¶

Below are examples of performing catalog searches using the various query parameters.

The GeoJSON feature collections returned by searches are generally large, so they are not included in full in the output. Instead the jq command is used to filter out certain properties to demonstrate that the searches produced some kind of expected value. Remove the jq commands from the examples and run them yourself to see what the full output looks like.

Search by ID¶

One of the simplest searches is by ID.

The query parameter ids is used to search by item ID. This is the easiest way to look up a particular image in the catalog since it is not necessary to know the collection it belongs to.

Here is a search on a particular ID:

In [15]:

            
                Copied!
                
curl -s -H "$auth_header" 'https://api.content.maxar.com/catalog/search?ids=1020010079424900' | \
    jq -r '.features[] | [.id, .properties.datetime, .properties.platform] | @csv'
curl -s -H "$auth_header" 'https://api.content.maxar.com/catalog/search?ids=1020010079424900' | \
    jq -r '.features[] | [.id, .properties.datetime, .properties.platform] | @csv'

"1020010079424900","2018-09-07T20:57:58.335106Z","worldview-01"

Any number of item ID's can be specified in the ids parameter. Here is an example of searching on multiple ID's by doing a POST with a form parameter:

In [16]:

            
                Copied!
                
curl -s -H "$auth_header" -d 'ids=102001009C00D000,10300100AEB46000,104001006215C400' 'https://api.content.maxar.com/catalog/search' | \
    jq -r '.features[] | [.id, .properties.datetime, .properties.platform] | @csv'
curl -s -H "$auth_header" -d 'ids=102001009C00D000,10300100AEB46000,104001006215C400' 'https://api.content.maxar.com/catalog/search' | \
    jq -r '.features[] | [.id, .properties.datetime, .properties.platform] | @csv'

"10300100AEB46000","2020-10-17T20:32:44.965746Z","worldview-02"
"102001009C00D000","2020-10-17T20:01:45.956688Z","worldview-01"
"104001006215C400","2020-10-17T19:38:34.841756Z","worldview-03"

It is not an error to search on an id that does not exist in the catalog. It is also not an error to search on an id of a feature that the caller does not have permission to access. The returned GeoJSON feature collection will contain whatever features match the requested set of IDs, with no mention of id values that don't exist or that the user does not have permission to access.

Search by location and datetime¶

This example demonstrates the commonly performed search involving a collection, bounding box, and acquisition date. The search performs a GET using the following query parameters:

collections: Search only for WorldView-1 and WorldView-2 images.
bbox: Search in the bounding box west=-105, east=-104, south=40, north=41 degrees.
datetime: Search for datetime in the range Jan 1, 2020 to Jan 7, 2020.

First perform the search and save the result in a variable:

In [17]:

            
                Copied!
                
features=$(curl -s -H "$auth_header" 'https://api.content.maxar.com/catalog/search?collections=wv01,wv02&bbox=-105,40,-104,41&datetime=2020-01-01/2020-01-07')
features=$(curl -s -H "$auth_header" 'https://api.content.maxar.com/catalog/search?collections=wv01,wv02&bbox=-105,40,-104,41&datetime=2020-01-01/2020-01-07')

The bounding box and date range are large enough that it's likely the query hit the maximum page size of 100 features:

In [18]:

            
                Copied!
                
echo "$features" | jq '.features | length'
echo "$features" | jq '.features | length'

Verify that only WorldView-1 and WorldView-2 images were returned:

In [19]:

            
                Copied!
                
echo "$features" | jq -r '.features[] | .properties.platform' | sort | uniq
echo "$features" | jq -r '.features[] | .properties.platform' | sort | uniq

worldview-01
worldview-02

Verify that datetime values in the returned features are in the expected range. Remember that if the orderby query parameter is not specified then returned features are in descending order by their datetime property:

In [20]:

            
                Copied!
                
echo "$features" | jq -r '.features[] | .properties.datetime' | sort | head -1
echo "$features" | jq -r '.features[] | .properties.datetime' | sort | tail -1
echo "$features" | jq -r '.features[] | .properties.datetime' | sort | head -1
echo "$features" | jq -r '.features[] | .properties.datetime' | sort | tail -1

2020-01-06T21:12:13.296499Z
2020-01-06T23:05:18.450366Z

The GeoJSON geometries in the returned featuers could be plotted on a map. Look at the other Python notebooks in this documentation for examples of doing that using geopandas.

Search using ordering¶

The above example used the default ordering enforced by the service: descending by datetime, ascending by id.

Here is the same query but ordering by datetime ascending. Note that now the datetime values in the first page of returned results are from the beginning of the date range rather than the end:

In [21]:

            
                Copied!
                
features=$(curl -s -H "$auth_header" 'https://api.content.maxar.com/catalog/search?collections=wv01,wv02&bbox=-105,40,-104,41&datetime=2020-01-01/2020-01-07&orderby=datetime')
echo "$features" | jq -r '.features[] | .properties.datetime' | sort | head -1
echo "$features" | jq -r '.features[] | .properties.datetime' | sort | tail -1
features=$(curl -s -H "$auth_header" 'https://api.content.maxar.com/catalog/search?collections=wv01,wv02&bbox=-105,40,-104,41&datetime=2020-01-01/2020-01-07&orderby=datetime')
echo "$features" | jq -r '.features[] | .properties.datetime' | sort | head -1
echo "$features" | jq -r '.features[] | .properties.datetime' | sort | tail -1

2020-01-01T00:25:24.887021Z
2020-01-01T01:58:19.588153Z

Since the default ordering returns the newest images first you can easily find images recently added to the catalog. For example this query returns the most recently added WorldView-2 image in the catalog (at the time of this writing):

In [22]:

            
                Copied!
                
curl -s -H "$auth_header" 'https://api.content.maxar.com/catalog/search?collections=wv02&limit=1' | \
    jq -r '.features[] | [.id, .properties.datetime] | @csv'
curl -s -H "$auth_header" 'https://api.content.maxar.com/catalog/search?collections=wv02&limit=1' | \
    jq -r '.features[] | [.id, .properties.datetime] | @csv'

"10300100DBC37500","2022-10-03T14:51:49.916824Z"

Search by geometry¶

The query parameter "intersects" allows an arbitrary GeoJSON geometry to be specified. Any item whose geometry intersects this shape satisfies the query. Any type of geometry may be used — it does not have to be a polygon.

Here is an example that follows from the previous query. Arbitrarily select the first item returned above and use its geometry as an intersection polygon to query on. Search against all the standard Maxar imagery collections. The result is all Maxar images that intersect the given geometry.

This example also demonstrates calling the search endpoint by performing a POST of a JSON object, where the query parameters are object properties. This is useful when using the intersects query parameter since a GeoJSON geometry can be large and is awkward to pass as a GET query parameter.

In [23]:

            
                Copied!
                
# Get the GeoJSON geometry of the first feature returned from the previous example
footprint=$(echo "$features" | jq -r '.features[0].geometry')

# Create JSON with the query parameters
body=$(jq <<EOF
  {
    "intersects": $footprint,
    "collections": ["ge01", "wv01", "wv02", "wv03-vnir", "wv04"]
  }
EOF
)

# Pretty-print the query parameters
echo "$body"

# POST to /search passing in body on stdin
surrounding_features=$(echo "$body" | curl -s --data @- -H "Content-Type: application/json" -H "$auth_header" 'https://api.content.maxar.com/catalog/search')
# Get the GeoJSON geometry of the first feature returned from the previous example
footprint=$(echo "$features" | jq -r '.features[0].geometry')

# Create JSON with the query parameters
body=$(jq <

{
  "intersects": {
    "type": "Polygon",
    "coordinates": [
      [
        [
          149.61481,
          8.648672
        ],
        [
          149.614791,
          8.594569
        ],
        [
          149.614741,
          8.54033
        ],
        [
          149.614719,
          8.497805
        ],
        [
          149.817765,
          8.537812
        ],
        [
          149.817748,
          8.580365
        ],
        [
          149.817752,
          8.634308
        ],
        [
          149.817728,
          8.688122
        ],
        [
          149.817668,
          8.741758
        ],
        [
          149.614782,
          8.70259
        ],
        [
          149.61481,
          8.648672
        ]
      ]
    ]
  },
  "collections": [
    "ge01",
    "wv01",
    "wv02",
    "wv03-vnir",
    "wv04"
  ]
}

Count the number of features returned:

In [24]:

            
                Copied!
                
echo "$surrounding_features" | jq '.features | length'
echo "$surrounding_features" | jq '.features | length'

Search by properties¶

The where query parameter allows a SQL-style where clause to be applied to STAC item properties. Free-form SQL-style queries such as these can be applied:

eo:cloud_cover < 20
(gsd < 0.5) and (view:azimuth < 50)
title like '%DigitalGlobe%'

Filters in a where parameter are logically applied after any other query parameters. The query parameters ids, collections, bbox, intersects, and datetime can all be considered to be applied first. Whatever features are selected by these primary filters then have the where clause applied to them.

Only values in a STAC item's properties object may be filtered using the where parameter. JSON properties at the "top level" of a STAC item, like stac_version and assets, cannot be queried this way.

Searching by where clause also does not work on properties whose values are arrays or objects. For example STAC items for Maxar images generally have a property eo:bands whose value is an array of objects, one for each band in the image (see here). The where clause does not support any syntax for querying such nested properties.

Syntax¶

This section describes the syntax used by the where query parameter.

Here are a few general rules:

Strings must be delimited by single quotes. There is no support for escape sequences inside strings.
String comparisons are always case-sensitive.
Keywords and literals such as null, true, false, like, etc. are not case sensitive.
Some common STAC item properties contain a prefix and colon, e.g. eo:cloud_cover. There is no special handling required for these property names because of the colon.

The following clauses are allowed. Note that property names are always on the left side:

property is null
property is not null
property is bool (where bool is true or false)
property operator value (where value is a number or string)
property like string
property not like string
property in list (where list is a parenthesis-delimited list of numbers or strings)

These are the operators allowed between property and value:

=
!=
<> (Same as !=)
<
>
<=
>=

Examples¶

This example repeats one from earlier that searched on collections, bounding box, and datetime range. This time a where-clause is added for filtering on the properties eo:cloud_cover and view:off_nadir:

In [25]:

            
                Copied!
                
                    
                    
                
                

        
features=$(
    curl -s -H "$auth_header" \
    -d 'collections=wv01,wv02' \
    -d 'bbox=-105,40,-104,41' \
    -d 'datetime=2020-01-01/2020-01-07' \
    -d 'where=view:off_nadir < 5 and eo:cloud_cover < 10' \
    'https://api.content.maxar.com/catalog/search')
features=$(
    curl -s -H "$auth_header" \
    -d 'collections=wv01,wv02' \
    -d 'bbox=-105,40,-104,41' \
    -d 'datetime=2020-01-01/2020-01-07' \
    -d 'where=view:off_nadir < 5 and eo:cloud_cover < 10' \
    'https://api.content.maxar.com/catalog/search')

The original query hit the page limit of 100 features since the query on collections, bounding box, and datetime range was so broad. Adding the where clause cuts down on the number of returned features:

In [26]:

            
                Copied!
                
echo "$features" | jq '.features | length'
echo "$features" | jq '.features | length'

Querying antimeridian images¶

Some images acquired by Maxar satellites cross the antimeridian. Their STAC item footprint geometries will likewise cross the antimeridian. In the West part of the footprint verticies will be in the Eastern hemisphere with longitudes near 180° East. The East part of the geometry will have vertices in the Western hemisphere with longitudes near 180° West. There are only a handful of places on Earth where land areas cross the antimeridian such as Fiji, Eastern Russia, and Antarctica.

The GeoJSON specification (RFC 7946) suggests cutting such geometries at the antimeridian because many applications have difficulty processing longitudes that discontinuously change from +180° to -180°. However, the Maxar Catalog takes a different approach. If a geometry crosses the antimeridian then its vertices with longitudes in the Western hemisphere will have values greater than 180°. This avoids cutting the geometry and maintains continuity in the longitude values, which can be helpful for some applications that have trouble dealing with the antimeridian. Applications may choose to modify such longitudes in returned features by subtracting 360 from them. Or applications may first split the returned geometries on the antimeridian, then subtract 360 from longitudes in the part in the Western hemisphere. It is up to applications using the Catalog API to decide how to deal with longitudes in features that cross the antimeridian.

The bbox property of an image that crosses the antimeridian is handled similarly. It will have an east longitude > 180°.

As an example here is the geometry and bbox of the WorldView-3 image 104001006A8D9C00. It is located in Fiji and spans the antimeridian. Notice that vertices in the Western hemisphere have longitudes > 180°:

In [27]:

            
                Copied!
                
curl -s -H "$auth_header" "https://api.content.maxar.com/catalog/collections/wv03-vnir/items/104001006A8D9C00" | jq '{bbox,geometry}'
curl -s -H "$auth_header" "https://api.content.maxar.com/catalog/collections/wv03-vnir/items/104001006A8D9C00" | jq '{bbox,geometry}'

{
  "bbox": [
    179.848856,
    -17.036345,
    180.008652,
    -16.738788
  ],
  "geometry": {
    "type": "Polygon",
    "coordinates": [
      [
        [
          179.849571,
          -16.759354
        ],
        [
          179.849597,
          -16.760238
        ],
        [
          179.849583,
          -16.76627
        ],
        [
          179.849575,
          -16.770324
        ],
        [
          179.849522,
          -16.791741
        ],
        [
          179.849496,
          -16.801833
        ],
        [
          179.84944,
          -16.823254
        ],
        [
          179.849414,
          -16.833349
        ],
        [
          179.849352,
          -16.854776
        ],
        [
          179.849322,
          -16.864878
        ],
        [
          179.849259,
          -16.886305
        ],
        [
          179.849228,
          -16.896412
        ],
        [
          179.849159,
          -16.917846
        ],
        [
          179.849104,
          -16.934967
        ],
        [
          179.849048,
          -16.953265
        ],
        [
          179.848978,
          -16.980989
        ],
        [
          179.848955,
          -16.991109
        ],
        [
          179.848907,
          -17.012597
        ],
        [
          179.848884,
          -17.022723
        ],
        [
          179.848856,
          -17.034228
        ],
        [
          180.008652,
          -17.036345
        ],
        [
          180.008578,
          -17.014817
        ],
        [
          180.008464,
          -16.983194
        ],
        [
          180.007929,
          -16.958274
        ],
        [
          180.007696,
          -16.953244
        ],
        [
          180.005889,
          -16.930844
        ],
        [
          180.00488,
          -16.919828
        ],
        [
          180.00314,
          -16.88818
        ],
        [
          180.003234,
          -16.885594
        ],
        [
          180.002914,
          -16.879193
        ],
        [
          180.003613,
          -16.86815
        ],
        [
          180.003608,
          -16.866845
        ],
        [
          180.00518,
          -16.835406
        ],
        [
          180.005263,
          -16.8341
        ],
        [
          180.005646,
          -16.825257
        ],
        [
          180.007322,
          -16.79838
        ],
        [
          180.007661,
          -16.784771
        ],
        [
          180.007799,
          -16.76235
        ],
        [
          180.007723,
          -16.741027
        ],
        [
          179.848988,
          -16.738788
        ],
        [
          179.849557,
          -16.751386
        ],
        [
          179.849571,
          -16.759354
        ]
      ]
    ]
  }
}

Note that these extended longitude values are not used when performing a geospatial search using the Catalog API. When you search using either the bbox or intersects query parameters all longitudes must be in the range [-180, 180].

If you use the bbox query parameter and want to search across the antimeridian then the East side of the box will be in the Western hemisphere. For instance if you wanted to search over Fiji you might specify bbox=179,-17,-179,-16. The GeoJSON specification discusses this as well here.

The same applies when using the intersects query parameter with a GeoJSON geometry that crosses the antimeridian. For example here is a GeoJSON geometry for a parallelogram over Fiji that could be used as the value of intersects:

{
  "type": "Polygon",
  "coordinates": [
    [
      [179, -17],
      [180, -17],
      [-179, -16],
      [180, -16],
      [179, -17]
    ]
  ]
}

Returned features that cross the antimeridian will always have longitudes > 180° for those vertices in the Western hemisphere, even though the search geometries specified by bbox and intersects don't use that convention.

Querying stereo pairs¶

Each satellite has a collection for its intrack stereo pairs (for WorldView-3 there are separate collections for VNIR and SWIR images):

ge01-intrack-stereo
lg01-intrack-stereo
lg02-intrack-stereo
wv01-intrack-stereo
wv02-intrack-stereo
wv03-swir-intrack-stereo
wv03-vnir-intrack-stereo

The STAC items in these collections describe the two images that make up a stero pair.

Here is an example. This query returns the most recent GeoEye-1 stereo pair in the collection ge01-intrack-stereo. The feature's geometry is the area of intersection of the two images in the stereo pair. A few properties describe the stereo pair. The image_identifiers array contains the images belonging to the pair:

In [28]:

            
                Copied!
                
curl -s -H "$auth_header" "https://api.content.maxar.com/catalog/collections/ge01-intrack-stereo/items?limit=1" | jq
curl -s -H "$auth_header" "https://api.content.maxar.com/catalog/collections/ge01-intrack-stereo/items?limit=1" | jq

{
  "type": "FeatureCollection",
  "features": [
    {
      "id": "e2bc6c55-158c-4c6e-8d5f-c853bae5d750-inv",
      "bbox": [
        -46.0261275643433,
        -13.7973296846791,
        -45.8390802456912,
        -13.6848373230799
      ],
      "type": "Feature",
      "links": [
        {
          "rel": "collection",
          "href": "https://api.content.maxar.com/catalog/collections/ge01-intrack-stereo",
          "type": "application/json"
        },
        {
          "rel": "root",
          "href": "https://api.content.maxar.com/catalog/collections/maxar-stereo",
          "type": "application/json"
        },
        {
          "rel": "self",
          "href": "https://api.content.maxar.com/catalog/collections/ge01-intrack-stereo/items/e2bc6c55-158c-4c6e-8d5f-c853bae5d750-inv",
          "type": "application/geo+json"
        }
      ],
      "assets": {},
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [
              -46.02608389,
              -13.7018126
            ],
            [
              -46.0261275643433,
              -13.6911991273234
            ],
            [
              -45.861675619949,
              -13.6848373230799
            ],
            [
              -45.83908818,
              -13.68951074
            ],
            [
              -45.8390802456912,
              -13.725296737545
            ],
            [
              -45.83908451,
              -13.7264738
            ],
            [
              -45.83927123,
              -13.76893621
            ],
            [
              -45.83951978,
              -13.79164716
            ],
            [
              -46.0104413059261,
              -13.7973296846791
            ],
            [
              -46.02574302,
              -13.79420493
            ],
            [
              -46.02583847,
              -13.75292259
            ],
            [
              -46.02608389,
              -13.7018126
            ]
          ]
        ]
      },
      "collection": "ge01-intrack-stereo",
      "properties": {
        "title": "Maxar InTrack Stereo e2bc6c55-158c-4c6e-8d5f-c853bae5d750-inv",
        "datetime": "2022-10-03T13:14:02.685706Z",
        "stereo_type": "InTrack",
        "max_bisector": 60.977203369140625,
        "min_bisector": 60.83549499511719,
        "max_asymmetry": 6.603069305419922,
        "min_asymmetry": 6.200501918792725,
        "max_convergence": 33.477142333984375,
        "min_convergence": 33.238887786865234,
        "image_identifiers": [
          "105001002F288000",
          "105001002F287E00"
        ]
      },
      "stac_version": "1.0.0"
    }
  ],
  "numberReturned": 1,
  "timestamp": "2022-10-03T16:33:30.925411Z",
  "links": [
    {
      "rel": "next",
      "href": "https://api.content.maxar.com/catalog/collections/ge01-intrack-stereo/items?limit=1&page=2"
    }
  ]
}

Querying WorldView-3 image associations¶

The catalog contains a collection multi-sensor-image-pair that describes associated images. Currently, this is only used with WorldView-3 images since that satellite is the only one with multiple sensors. Each item in the multi-sensor-image-pair collection describes the association between a WorldView-3 VNIR and SWIR image.

Each WorldView-3 STAC item has an associations property with the STAC item ID of its association. So given a WorldView-3 STAC item you can find its associated image (if any) by querying its association in the multi-sensor-image-pair collection, and then querying the STAC item of its associated image.

Here is an example starting with the WorldView-3 SWIR image 104A010079117E00. Here is its STAC item associations property:

In [29]:

            
                Copied!
                
curl -s -H "$auth_header" "https://api.content.maxar.com/catalog/collections/wv03-swir/items/104A010079117E00" | jq '.properties.associations'
curl -s -H "$auth_header" "https://api.content.maxar.com/catalog/collections/wv03-swir/items/104A010079117E00" | jq '.properties.associations'

[
  {
    "association_type": "VNIR_SWIR",
    "association_identifier": "a2288b60-bed2-467b-8e40-d2bbd31b0a57-inv"
  }
]

Note that the associations property is array-valued. In general an image might be associaed with multiple other images in multiple ways. But currently only a "VNIR_SWIR" association is supported for use only by WorldView-3 images.

To find the assoicated image query the catalog for the association's STAC item:

In [30]:

            
                Copied!
                
curl -s -H "$auth_header" "https://api.content.maxar.com/catalog/collections/multi-sensor-image-pair/items/a2288b60-bed2-467b-8e40-d2bbd31b0a57-inv" | jq
curl -s -H "$auth_header" "https://api.content.maxar.com/catalog/collections/multi-sensor-image-pair/items/a2288b60-bed2-467b-8e40-d2bbd31b0a57-inv" | jq

{
  "id": "a2288b60-bed2-467b-8e40-d2bbd31b0a57-inv",
  "bbox": [
    -35.030944,
    -8.043394,
    -34.869169,
    -7.90298
  ],
  "type": "Feature",
  "links": [
    {
      "rel": "collection",
      "href": "https://api.content.maxar.com/catalog/collections/multi-sensor-image-pair"
    },
    {
      "rel": "self",
      "href": "https://api.content.maxar.com/catalog/collections/multi-sensor-image-pair/items/a2288b60-bed2-467b-8e40-d2bbd31b0a57-inv"
    }
  ],
  "assets": {},
  "geometry": {
    "type": "Polygon",
    "coordinates": [
      [
        [
          -35.03046,
          -7.937215
        ],
        [
          -34.869169,
          -7.90298
        ],
        [
          -34.86923,
          -7.9142
        ],
        [
          -34.869337,
          -7.960672
        ],
        [
          -34.869518,
          -8.007177
        ],
        [
          -34.869539,
          -8.012063
        ],
        [
          -35.030537,
          -8.043394
        ],
        [
          -35.030522,
          -8.039473
        ],
        [
          -35.030944,
          -7.993091
        ],
        [
          -35.030424,
          -7.946208
        ],
        [
          -35.03046,
          -7.937215
        ]
      ]
    ]
  },
  "collection": "multi-sensor-image-pair",
  "properties": {
    "title": "Maxar VNIR_SWIR Association a2288b60-bed2-467b-8e40-d2bbd31b0a57-inv",
    "datetime": "2022-06-15T12:31:19.006852Z",
    "association_type": "VNIR_SWIR",
    "image_identifiers": [
      "104A010079117E00",
      "1040010079117E00"
    ]
  },
  "stac_version": "1.0.0-beta.2"
}

The association's image_identifiers property contains the STAC item IDs of the two images in the association. One of these is the ID of the image we started with, 104A010079117E00. The other is its assoicated image.

Requesting assets¶

STAC items can have an assets property containing URL's to an item's constituent files. The particular assets associated with an item depend on what kind of geospatial product the item is.

STAC items for Maxar satellite images generally have these assets:

browse: A low-resolution browse image in GeoTIFF format
cloud-cover: A GeoJSON file containing cloud polygons
sample-point-set: A GeoJSON file of sample points

For example an earlier section above requested the WorldView-1 image 1020010010DD0000 and the returned STAC item's assets property contained this browse object:

"browse": {
      "href": "https://api.content.maxar.com/catalog/collections/wv01/items/1020010010DD0000/assets/collections/dg-archive/assets/browse/1020010010DD0000.browse.tif",
      "type": "image/tiff; application=geotiff",
      "title": "Browse Image"
}

To retrieve the browse image just perform a GET on the given URL. You must provide the usual Authentiation header with bearer token.

Note that a GET on an asset URL generally causes an HTTP redirect and a returned HTTP status of 302. You should then request the redirected URL. If you are using curl to GET an asset URL specify the --location command line option.

Maxar satellite image properties¶

This section lists the properties that are generally provided for Maxar images. Collections in the Maxar catalog other products besides Maxar imagery will have different properties.

Required properties of STAC items

datetime

Properties from STAC common metadata

constellation
gsd
instruments
platform
title

Properties of eo extension:

eo:bands
eo:cloud_cover

Properties of view extension:

view:azimuth
view:off_nadir
view:sun_azimuth
view:sun_elevation

Properties specific to Maxar satellite imagery

associations
collect_time_end
collect_time_start
multi_resolution_avg
multi_resolution_end
multi_resolution_max
multi_resolution_min
multi_resolution_start
off_nadir_avg
off_nadir_end
off_nadir_max
off_nadir_min
off_nadir_start
pan_resolution_avg
pan_resolution_end
pan_resolution_max
pan_resolution_min
pan_resolution_start
rda_available
scan_direction
spacecraft_to_target_azimuth_avg
spacecraft_to_target_azimuth_end
spacecraft_to_target_azimuth_max
spacecraft_to_target_azimuth_min
spacecraft_to_target_azimuth_start
stereo_pair_identifiers
target_to_spacecraft_azimuth_avg
target_to_spacecraft_azimuth_end
target_to_spacecraft_azimuth_max
target_to_spacecraft_azimuth_min
target_to_spacecraft_azimuth_start
target_to_spacecraft_elevation_avg
target_to_spacecraft_elevation_end
target_to_spacecraft_elevation_max
target_to_spacecraft_elevation_min
target_to_spacecraft_elevation_start