Intro to Discovery

About the API

Use the MGP Discovery API to search the Maxar catalog for content, based on a set of criteria you define. All data served by the Discovery API follow the STAC specification.

Maxar STAC Hierarchy

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. STAC groups collections into logical hierarchies referred to as "sub-catalogs." There are two ways to view the date: the root catalog view and the sub-catalog view.

The Root Catalog View

Search and filter across the full catalog.

Base URL:

https://api.maxar.com/discovery/v1

You can access the entire catalog of data through STAC API at the /discovery endpoint. Our collection provides an in-depth reference for all available requests with parameters, responses, and examples. We also have a very detailed API Tutorial that provides a better client-focused overview of these requests. See the linked user example journeys for your use-case.

Sub-Catalog View

Search and filter within a sub-catalog.

Base URL:

https://api.maxar.com/discovery/v1/catalogs/{subCatalogId}

Sub-catalogs group data for more targeted discovery. At the base url of any sub-catalog, you can browse and explore the data in the same manner as the Root Catalog. All sub-catalogs are navigated at the same endpoint, no matter if it is a child of a sub-catalog, or a top level sub-catalog.

For a specific sub-catalog, you get the power of a fully functional STAC API at the /discovery/catalogs/{subCatalogId} base url. To learn more, see List top level SubCatalogs.

Sub-Catalog ID	Description	Sub-Catalog URL
analytics	Analytics products	GET https://api.maxar.com/discovery/v1/catalogs/analytics
basemaps	Basemaps	GET https://api.maxar.com/discovery/v1/catalogs/basemaps
imagery	Maxar Satellite Imagery	GET https://api.maxar.com/discovery/v1/catalogs/imagery
3d	Precision3D Elevation products	GET https://api.maxar.com/discovery/v1/catalogs/3d
Analysis-ready	Analysis-ready Data	GET https://api.maxar.com/discovery/v1/services/imagegrid/search

Area-based Calculations

Many of the item metadata values represent the whole strip. Because image strips are so large, a property like eo:cloud_cover represents a large area. While an eo:cloud_cover of 50% means 50% of the image is covered by clouds, it's possible that your area of interest happens to have no clouds over it. Most users search for images with low cloud cover values but for small AOIs there can be a larger selection of cloud free AOIs to work with hidden in images that have higher cloud cover values.

While it's possible to search for intersecting images, download their cloud cover polygons, and compute a final cloud cover percentage specific to the AOI, the Discovery AOI now supports "Area Based Calculations". When this mode is toggled on, two additional fields are added to the metadata properties:

• area:cloud_cover_percentage: the percentage of cloud cover within the supplied AOI
• area:avg_off_nadir_angle: average off-nadir angle within the supplied AOI

AOIs can be either the STAC bbox or intersects geometry.

To turn this calculation mode on or off, add an area-based-calc parameter set to true or false. Default is false meaning no area-based calculations are performed. For example, a basic GET request with area-based calculations turned on looks like:

https://api.maxar.com/discovery/v1/search?collections=wv01,wv02&bbox=-105,40,-104,41&datetime=2020-01-01/2020-01-07&sortby=datetime&area-based-calc=true

Area-based calculations are not applicable to the gridded search endpoint, as they already provide a similar calculation for each grid tile.

Example Scenario: Exploring Maxar imagery

This scenario is ideal if you are new to Maxar imagery.

Phase 1: Discovery

Goal	Request	Response
See what is available in the catalog	GET https://api.maxar.com/discovery/v1	{ "id": "Maxar", "type": "Catalog", ..., "links": [ { "title": "Imagery", "type": "Catalog", "rel": "Child", "href": "https://api.maxar.com/discovery/v1/catalogs/imagery"} ], ... }
Given an "Imagery" sub-catalog in the response links, navigate there to see if this contains the right satellite data desired	GET https://api.maxar.com/discovery/v1/catalogs/imagery	{"description": "This catalog holds all of the Maxar satellite imagery and stereo data", ...] }
The description matches what you want, you can directly search your desired area	GET https://api.maxar.com/discovery/v1/catalogs/imagery/search?bbox=-109,37,-102,41	{"features": [{"id": "1040010083331700", "collection": "wv03-swir", ...}, {"id": "10300100E269D200", "wv02", ...}], ...}

Phase 2: Everyday Access

Once you are familiar with the metadata of images, you can refine search parameters.

Goal	Request	Response
Each day, you can search for satellite imagery data from these collections in the areas you care about	https://api.maxar.com/discovery/v1/catalogs/imagery/search -G --data-urlencode "filter=eo:cloud_cover < 10" --data-urlencode "bbox=-109,37,-102,41" --data-urlencode "collections=wv02,wv03-swir"	{"features": [{"title": "Maxar WV02 Image 123456789", ...}, ...]}