Maxar Catalog API

Introduction

The Maxar Catalog API provides the ability to search Maxar's database of satellite imagery and other geospatial products. This document describes the service's REST API for querying the catalog and provides examples of calling it.

The catalog contains metadata for images and other raster products -- but for most products not the full-resolution data. Metadata may contain "asset" URL's pointing to a product's full-resolution dataset, which for some products may be directly retrieved or for others may require additional permission to obtain. For most imagery products there will at least be a publicly available low-resolution browse dataset.

The Maxar Catalog implements a new standard for geospatial databases: STAC, the SpatioTemporal Asset Catalog. A STAC catalog stores geospatial features that are queryable by location and time, as well as by custom properties stored in each feature. A single geospatial feature is represented in the Maxar catalog by a GeoJSON feature

The STAC specification is currently in beta release and there may be minor changes when version 1.0 is released. The STAC API is also intended to implement the emerging OGC Features API (OAFeat) which is also still under development. Therefore, the Maxar Catalog's API may change slightly if necessary to reflect the eventual 1.0 versions of these specifications.

Users of the Maxar Catalog should have a basic understanding of STAC. See the following links for more information. This Maxar Catalog documentation does not duplicate introductory information found at these sites:

Releases

August 2, 2022

Update	Description	Resources
Paging through collections	New Feature: Support for pagination through orderby, limit, and page query parameters	GET /collections
Next link in POST /search	Enhancement: When searching for items using the POST method, we now include a link for accessing the next page of results if more exist	POST /search

Terminology

Note that the term "catalog" has two meanings. In this document it refers to the "Maxar Catalog", which is the database of Maxar imagery and other geospatial products. However, the STAC specification has its own "catalog" concept (see here), intended for storing a collection of STAC items in a filesystem or object store like S3. This document doesn't use "catalog" in the STAC sense, instead using the STAC term "collection" for a set of geospatial items.

The terms "item" and "feature" appear in the STAC and OAFeat specifications, and are used interchangeably to refer to a single image's metadata represented as a GeoJSON feature.

Authorization

All calls to the API require authorization using an OAuth2 bearer token. See Content Hub Authorization for instructions on obtaining a token.

STAC item example

Understanding STAC items is central to using the Maxar Catalog. This section presents an example of a STAC item for a Maxar satellite image.

The file 10400100603CF500.json is a STAC item for image 10400100603CF500 acquired by Maxar's WorldView-3 satellite on Oct 9, 2020.

Here are a few things to note about a STAC feature's properties. See the STAC item specification for more information:

A STAC item is a GeoJSON feature. It always has an id property, a type property with value Feature, and a geometry property. The geometry property's value is a GeoJSON geometry object.
The bbox property is the feature's bounding box with coordinates in the order west, south, east, north.
The links property contains URL's to related entities, like the collection the item belongs to.
The assets property contains URL's to data associated with the item. STAC items for Maxar satellite images will always have assets for a low-resolution browse image, cloud polygon in GeoJSON format, and sample points in GeoJSON format.
The collection property is the name of the collection in the Maxar Catalog an item belongs to. Every STAC item in the Maxar Catalog belongs to exactly one collection.
The properties object contains arbitrary properties of a STAC item. The STAC specification requires at least a datetime property which for satellite imagery is the acquisition datetime. STAC items for Maxar imagery contain many other properties, some of which are standardized by STAC extensions and others are custom properties defined by Maxar.
The stac_version is the version of the STAC specification the JSON adheres to. When STAC version 1.0 is released then all STAC items in the Maxar Catalog will be updated if necessary to match it.
The stac_extensions property is a list of the STAC extensions used by the item. STAC extensions generally specify new properties and are generally identifiable by a prefix on the property name. In this example this would be properties like eo:cloud_cover and view:sun_azimuth.

In the Maxar Catalog STAC item geometry objects always have coordinates in WGS84 decimal degrees.

Collections

Items in the Maxar Catalog are organized into collections. Every item belongs to exactly one collection.

The following table shows the collections used for Maxar satellite imagery. Multiple collections are used for WorldView-3 images because that satellite has multiple sensors.

Collection name	Description
ge01	GeoEye-1 images
wv01	WorldView-1 images
wv02	WorldView-2 images
wv03-vnir	WorldView-3 VNIR images
wv03-swir	WorldView-3 SWIR images
wv04	WorldView-4 images

The catalog has some other collections for resources besides individual satellite images. For example these collections contain pairs of in-track stereo imagery:

Collection name
ge01-intrack-stereo
wv01-intrack-stereo
wv02-intrack-stereo
wv03-swir-intrack-stereo
wv03-vnir-intrack-stereo

And there are a variety of other collections:

Collection name	Description
dg-dem	Digital elevation models
mosaics	VIVID mosaics
multi-sensor-image-pair	Stereo pairs between images from different sensors

In the above tables the collection name is the value to use in URL's in the REST API. Collection names are case-sensitive.

Collections can optionally be part of a hierarchy. For example the various collections for WorldView and GeoEye images all belong to the "parent" collection dg-archive. Parent collections like dg-archive do not themselves contain any STAC items, instead they act as containers for other collections.

STAC item identifiers

Every STAC item always has an id property. This is some kind of identifier that uniquely identifies every item in the database.

The STAC specification intends that all data providers generate id values that are globally unique. See here. In the case of Maxar satellite images this is the case. All image IDs for items in the standard imagery collections (ge01, wv01, wv02, wv03-vnir, wv03-swir, wv04) will be unique across all Maxar satellites.

However, the Maxar Catalog does have items with duplicate id values in its mosaic collections, since items in mosaic collection use quadkeys as identifiers. So when querying items in mosaic collections you have to be prepared to deal with duplicate id values, depending on the collections you are querying. All items inside a single collection will have unique id values.