Vivid Terrain

Overview

Vivid Terrain offers 3D mapping and imagery with specific post-processing steps. All Vivid Terrain orders can be requested through the Ordering API. This document describes the URL path parameters and settings to include in your order request. All other components of an order request are explained in the Ordering Guide.

All currently available Vivid Terrain content types are listed below. For ordering, these requests have a name and a namespace. These are passed to the Ordering API as URL path parameters.

Product	Namespace	Name
Vivid Terrain Elevation Products (DTM, DSM, and DTM + DSM bundle)	3d	elevation
Vivid Terrain Surface Model	3d	mesh
Vivid Terrain True Ortho	3d	texture
Vivid Terrain 3D Bundle (3DSM, DSM and True Ortho delivered together)	3d	bundle
Vivid Terrain Classification	3d	classification
Vivid Terrain DHM	3d	dhm
Vivid Terrain Point Cloud	3d	point-cloud
Vivid Terrain Buildings	3d	buildings
Vivid Terrain Vegetation	3d	vegetation

Note: Names and namespaces are case sensitive.

Vivid Terrain requests

The table below lists all requests available for Vivid Terrain. AOIs must be a minimum of 10 sq km and a maximum of 1000 sq km.

Base URL: https://api.maxar.com

Request Type	Method	Path	Description
Validate order	POST	/ordering/v1/pipelines/:namespace/:name/validate	Performs basic validation such as ensuring the required fields are provided with allowed values. For 3D, this request also provides a usage estimate for the order in sq km.
Place an order	POST	/ordering/v1/pipelines/:namespace/:name/order	Place an order for Vivid Terrain imagery and models. Once the order is placed, any requested notifications will be sent, and the output files will be delivered to the specified location.
Cancel an order	POST	/ordering/v1/orders/:id/cancel	An order can be canceled until the delivery process begins.

Note: The ordering API uses the name and namespace provided in the request URL to determine which "pipeline" will process the order. Because of this, we use the term "pipelines" in the request URL.

Discovering 3D content in the Discovery catalog

The Discovery API enables searching, filtering, and sorting through a unified catalog of available content. To search for 3d content, you can filter stac items results with the following collection ID:

Collection ID	Description
3d	Returns results from the 3d collection. The results set will return 3d-dsm, 3d-dtm, 3d-3dsm, and 3d-trueortho content. The search can be constrained by an AOI in the bbox or intersects fields.

Discovery search tutorial

Search STAC items with filtering.

Example 3d search response

{
    "type": "FeatureCollection",
    "features": [
        {
            "id": "dtm_w104n40",
            "bbox": [
                -104.000119,
                -102.999883,
                39.999911,
                41.000091
            ],
            "type": "Feature",
            "links": [
                {
                    "rel": "collection",
                    "href": "https://api.maxar.com/discovery/v1/collections/p3d-dtm"
                },
                {
                    "rel": "self",
                    "href": "https://api.maxar.com/discovery/v1/collections/p3d-dtm/items/dtm_w104n40"
                }
            ],
            "assets": {},
            "license": "proprietary",
            "geometry": {
                "type": "Polygon",
                "coordinates": [
                    [
                        [
                            -103.998491,
                            40.001153
                        ],
                        [
                            -103.998491,
                            41.000091
                        ],
                        [
                            -104.000119,
                            41.000091
                        ],
                        [
                            -104.000117,
                            39.999911
                        ],
                        [
                            -102.999883,
                            39.999911
                        ],
                        [
                            -102.999883,
                            40.001153
                        ],
                        [
                            -103.998491,
                            40.001153
                        ]
                    ]
                ]
            },
            "collection": "p3d-dtm",
            "properties": {
                "source": "Precision 3D",
                "block_type": "dtm",
            },
            "stac_version": "1.0.0"
        },
        {
            "id": "dtm_w104n39",
            "bbox": [
                -104.000117,
                -102.999883,
                38.999911,
                40.000091
            ],
            "type": "Feature",
            "links": [
                {
                    "rel": "collection",
                    "href": "https://api.maxar.com/discovery/v1/collections/p3d-dtm"
                },
                {
                    "rel": "self",
                    "href": "https://api.maxar.com/discovery/v1/collections/p3d-dtm/items/dtm_w104n39"
                }
            ],
            "assets": {},
            "license": "proprietary",
            "geometry": {
                "type": "Polygon",
                "coordinates": [
                    [
                        [
                            -104.000116,
                            39.010001
                        ],
                        [
                            -104.000116,
                            38.999911
                        ],
                        [
                            -102.999885,
                            38.999911
                        ],
                        [
                            -102.999883,
                            40.000091
                        ],
                        [
                            -104.000117,
                            40.000091
                        ],
                        [
                            -104.000116,
                            39.010001
                        ]
                    ]
                ]
            },
            "collection": "p3d-dtm",
            "properties": {
                "source": "Precision 3D",
                "created": "2023-10-11T19:15:02Z",
                "datetime": "2023-10-11T19:15:02Z",
                "block_type": "dtm",
                "exported_at": "2023-10-11T19:15:02Z"
            },
            "stac_version": "1.0.0"
       }
        
    ],
    "numberReturned": 15,
    "timestamp": "2023-10-11T20:56:29.403956Z"
}

Worldview 3d Elevation Products

Elevation model (gridded)

POST https://api.maxar.com/ordering/v1/pipelines/3d/elevation/

The following Vivid Terrain elevation content types are available to order:

• Vivid Terrain Digital Terrain Model (DTM)
• Vivid Terrain Digital Surface Model (DSM)
• Vivid Terrain Elevation bundle (DTM and DSM delivered together)

The output file for Elevation Products is a GeoTIFF. The content is delivered to the cloud storage location specified in your order request.

3D Elevation settings

The request body for an order includes a settings object. The fields in this object are specific to ordering elevation models.

Parameter	Required	Description	Allowed Values	Example
aoi	required	The AOI coordinates for the DTM or DSM area.	GeoJSON Feature with geometry type Polygon or MultiPolygon with no holes. Must be between 10 and 1000 sq km.	See example
product_name	required	The name of the product or bundle to be ordered.	dtm, dsm, elevation_bundle	"product_name": "dsm"
post_spacing	required	The distance between points on the elevation grid.	0.5, 1.0, 2.0, 4.0	"post_spacing": 0.5
vertical_system	optional	the vertical coordinate system to define the origin of the height.	default is EGM2008, options are ELLIPSOID, EGM96	"vertical_system": "EGM96"

If the vertical_system field is not included, the default value of EGM2008 will be used.

Example request and responses

Example request

{
	"settings": {
		"aoi": {
			"type": "Feature",
			"geometry": {
				"type": "Polygon",
				"coordinates": [
					[
						[-105.16013169628113, 39.87781964010384],
						[-105.0964978907582, 39.87781964010384],
						[-105.0964978907582, 39.901723980953705],
						[-105.16013169628113, 39.901723980953705],
						[-105.16013169628113, 39.87781964010384]
					]
				]
			}
		},
		"product_name": "dsm",
		"post_spacing": 0.5
	},
	"output_config": {
		"amazon_s3": {
			"bucket": "example-bucket",
			"prefix": "example-prefix"
		}
	},
	"notifications": [{
		"type": "email",
		"target": "user@example.com",
		"level": "FINAL_ONLY"
	}],
	"metadata": {
		"project_id": "any value"
	}
}

Example /validate response

{
    "data": {
        "usage": {
            "product_id": 372,
            "units": "sqkm",
            "quantity": 14.4457289301155,
            "description": "total_coverage_percent [100%]"
        }
    },
    "links": {
        "request": "https://api.maxar.com/ordering/v1/pipelines/3d/elevation/validate"
    },
    "request_timestamp": "2023-10-06T17:56:01Z",
    "response_timestamp": "2023-10-06T17:56:05Z",
    "request_duration": 4.0
}

Example /order response

{
    "data": {
        "id": "0007485351743488843",
        "date_created": "2023-08-21T21:26:23Z",
        "date_modified": "2023-08-21T21:26:25Z",
        "pipeline_id": "3d/elevation",
        	"settings": {
		"aoi": {
			"type": "Feature",
			"geometry": {
				"type": "Polygon",
				"coordinates": [
					[
						[-105.16013169628113, 39.87781964010384],
						[-105.0964978907582, 39.87781964010384],
						[-105.0964978907582, 39.901723980953705],
						[-105.16013169628113, 39.901723980953705],
						[-105.16013169628113, 39.87781964010384]
					]
				]
			}
		},
            "product_name": "dsm",
            "post_spacing": 0.5
        },
        "output_config": {
            "amazon_s3": {
                "bucket": "example-bucket",
                "prefix": "example-prefix"
            }
        },
        "notifications": [
            {
                "type": "email",
                "target": "user@example.com",
                "level": "FINAL_ONLY"
            }
        ],
        "metadata": {
            "project_id": "any value"
        },
        "status": "RECEIVED",
        "status_details": {},
        "cancellation_requested": false,
        "process_details": {},
        "delivery_details": {},
        "order_links": {
            "self": "https://api.maxar.com/ordering/v1/orders/0007485351743488843",
            "events": "https://api.maxar.com/ordering/v1/orders/0007485351743488843/events"
        }
    },
    "links": {
        "request": "https://api.maxar.com/ordering/v1/pipelines/3d/elevation/order"
    },
    "request_timestamp": "2023-08-21T21:26:18Z",
    "response_timestamp": "2023-08-21T21:26:26Z",
    "request_duration": 8.0
  }

Surface Model (mesh)

POST https://api.maxar.com/ordering/v1/pipelines/3d/mesh/

For Vivid Terrain Surface Model content types, you must specify your file delivery formatting. This will change the coordinate system and vertical system of the delivered data.

All 3D Surface Models are delivered with the following values:

Parameter	Value
Equivalent post spacing	0.5m
Reference system	WGS84 G1674
Water indication mask	No

3D Surface Model settings

The request body for an order includes a settings object. The fields in this object are specific to ordering 3D Surface Models.

Parameter	Required	Description	Allowed Values	Example
aoi	required	The AOI coordinates for the 3DSM area.	GeoJSON polygon with no holes. Must be between 10 and 1000 sq km.	See example
product_name	required	The name of the product or bundle to be ordered.	3dsm	"product_name": "3dsm"
file_format	required	The file format for the delivered file. This will affect the data's coordinate system and vertical system. See the table below for their relationship.	See table below.	"file_format": "r3db"

File formats

Below is a table of all allowed file formats for Vivid Terrain Surface Model ordering.

File Format	Coordinate System	Vertical System	Value
3D Tiles 1.1 (Cesium)	Geocentric (ECEF)	N/A	3D-TILES-11 (Default)
3D Tiles 1.0 (Cesium)	Geocentric (ECEF)	N/A	3D-TILES
Vivid Terrain r3db	UTM	Ellipsoid	r3db
Vivid Terrain Collada	UTM	Ellipsoid	collada
I3S 1.8 (ESRI)	Geodetic	EGM96	i3s18
I3S 1.6 (ESRI)	Geodetic	EGM96	i3s

Example request

{
    "settings": {
        "aoi": {
            "type": "Feature",
            "geometry": {
                "type": "Polygon",
                "coordinates": [
                    [
                        [
                            28.92687413900731,
                            41.02551365381996
                        ],
                        [
                            28.92687413900731,
                            40.99020144460522
                        ],
                        [
                            28.99680796540261,
                            40.99020144460522
                        ],
                        [
                            28.99680796540261,
                            41.02551365381996
                        ],
                        [
                            28.92687413900731,
                            41.02551365381996
                        ]
                    ]
                ]
            }
        },
        "product_name": "3dsm",
       "file_format": "r3db"
    },
    "notifications": [
        {
            "type": "email",
            "target": "youremail@email.com",
            "level": "FINAL_ONLY"
        }
    ],
    "output_config": {
        "amazon_s3": {
            "bucket": "your-bucket",
            "prefix": "your/prefix"
        }
    }
}

True Ortho

POST https://api.maxar.com/ordering/v1/pipelines/3d/texture/

Vivid Terrain True Ortho content types have more rigid settings than other requests. All True Ortho orders come with the following default parameters and values:

Parameter	Value
Post spacing	0.5m
File format	GeoTIFF
Reference system	WGS84 G1674
Coordinate system	UTM
File compression	Yes
Tiling	8192x8192 pixels
Tiling overlap	1 pixel

True Ortho settings

The request body for an order includes a settings object. The fields in this object are specific to ordering True Ortho models.

Parameter	Required	Description	Allowed Values	Example
aoi	required	The AOI coordinates for the True Ortho area.	GeoJSON polygon with no holes. Must be between 10 and 1000 sq km.	See example
product_name	required	The name of the product or bundle to be ordered.	true_ortho	"product_name": "true_ortho"

Example request

{
    "settings": {
        "product_name": "true_ortho",
        "aoi": {
            "type": "Feature",
            "geometry": {
                "type": "Polygon",
                "coordinates": [
                    [
                        [
                            28.92687413900731,
                            41.02551365381996
                        ],
                        [
                            28.92687413900731,
                            40.99020144460522
                        ],
                        [
                            28.99680796540261,
                            40.99020144460522
                        ],
                        [
                            28.99680796540261,
                            41.02551365381996
                        ],
                        [
                            28.92687413900731,
                            41.02551365381996
                        ]
                    ]
                ]
            }
        }
    },
        "notifications": [
            {
                "type": "email",
                "target": "youremail@email.com",
                "level": "FINAL_ONLY"
            }
        ],
        "output_config": {
            "amazon_s3": {
                "bucket": "your-bucket",
                "prefix": "your/prefix"
            }
        }
    }

P3D Product Bundle

POST https://api.maxar.com/ordering/v1/pipelines/3d/bundle/

The Vivid Terrain Bundle content type allows you to order Digital Surface Models, True Ortho, and 3D Surface Models in a single order. Your selection of the file format of the 3D Surface Models will determine the corresponding Coordinate System and Vertical System of the 3D Surface Models, and the Digital Surface Models that come with the Bundle. See the table below.

File Format	Coordinate System	Vertical System	Value
3D Tiles 1.1 (Cesium)	Geocentric (ECEF)	N/A	3D-TILES-11 (Default)
3D Tiles 1.0 (Cesium)	Geocentric (ECEF)	N/A	3D-TILES
Vivid Terrain r3db	UTM	Ellipsoid	r3db
Vivid Terrain Collada	UTM	Ellipsoid	collada
I3S 1.8 (ESRI)	Geodetic	EGM96	i3s18
I3S 1.6 (ESRI)	Geodetic	EGM96	i3s

Digital Surface Models

Parameter	Value
Post spacing	0.5m
File format	GeoTIFF
Reference system	WGS84 G1674
Coordinate system	UTM

3D Surface Models

Parameter	Value
Post spacing	0.5m

True Ortho Models

Parameter	Value
Post spacing	0.5m
File format	GeoTIFF
Reference system	WGS84 G1674
Coordinate system	UTM

Example request

{
    "settings": {
        "product_name": "surface_model",
        "file_format": "3D-TILES-11",
        "aoi": {
            "type": "Feature",
            "geometry": {
                "type": "Polygon",
                "coordinates": [
                    [
                        [
                            -81.5642166138,
                            28.3486296393
                        ],
                        [
                            -81.5642166138,
                            28.3842773117
                        ],
                        [
                            -81.5259361267,
                            28.3842773117
                        ],
                        [
                            -81.5259361267,
                            28.3486296393
                        ],
                        [
                            -81.5642166138,
                            28.3486296393
                        ]
                    ]
                ]
            }
        }
    },
    "output_config": {
        "amazon_s3": {
            "bucket": "your-bucket",
            "prefix": "your/prefix"
        }
    }
}

Terrain Classification (vector refined)

Vivid Terrain Classification describes the type of terrain class in a raster format. This type of product is sometimes referred to as land use/land cover or clutter classification data. The classification data is automatically extracted from the Vivid Terrain 3D Surface Model. "Vector-refined" indicates that the classification will be matched to the extents of the vector Percision3D Building polygons and Percision3D Vegetation polygons.

POST  https://api.maxar.com/ordering/v1/pipelines/3d/classification/

All Vivid Terrain Classification (vector-refined) orders are delivered with the following values.

Parameter	Value
Post spacing	0.5m
File format	GeoTIFF
Reference system	WGS84 G1674
Coordinate system	UTM
Compression	Lossless Deflate Compressed
Classification scheme	Standard
Vector refined	True

Optional ordering parameters for Vivid Terrain Classification (vector refined)

Parameter	Default Value	Optional Values	Examples
post_spacing	0.5 (meters)	1.0, 2.0, 4.0	"post_spacing": 2.0

Notes:

Requires DTM.

Example Classifications order with optional parameters

{
   "settings": {
         "product_name": "classification", 
         "post_spacing": 2.0,
         "aoi": {
              "type": "Feature",
              "geometry": {
                   "type": "Polygon",
                   "coordinates": [
                    [
                         [
                              -77.07986908814675,
                              38.92366474267453
                         ],
                         [
                              -77.07986908814675,
                              38.86693932273354
                         ],
                         [
                              -76.98544542389106,
                              38.86693932273354
                         ],
                         [
                              -76.98544542389106,
                              38.92366474267453
                         ],
                         [
                              -77.07986908814675,
                              38.92366474267453
                         ]
                    ]
               ]
          }
     }
},

  "output_configs":[
        {
            "type": "amazon_s3",
            "bucket": "bucket-name",
            "prefix": "set a unique prefix name"
        }
   ],
"notifications": [
      {
           "type": "email",
           "target": "youremail@email.com",
           "level": "FINAL_ONLY"
      }
  ]
}

Digital Height Model (vector-refined)

The Vivid Terrain Digital Height Model (DHM) describes the above-ground difference between the Vivid Terrain DSM and Vivid Terrain DTM in a raster format, including buildings and vegetation which were removed in the process of creating the Vivid Terrain DTM. "Vector-refined" indicates that the DHM will be matched to the extents of the vector Percision3D Building polygons and Vivid Terrain Vegetation polygons.

POST  https://api.maxar.com/ordering/v1/pipelines/3d/dhm/

All Vivid Terrain DHM (vector-refined) orders are delivered with the following values.

Parameter	Value
File format	GeoTIFF
Reference system	WGS84 G1674
Coordinate system	UTM
Compression	Lossless Deflate Compressed
Vector refined	True

Note: DTM coverage is required.

Optional ordering parameters for Vivid Terrain DHM (vector refined)

Parameter	Default Value	Optional Value	Example
post_spacing	0.5 (meters)	1.0, 2.0, 4.0	"post_spacing": 2.0
vertical_system	EGM2008	ELLIPSOID, EGM96	"vertical_system": "ELLIPSOID"

Example Vivid Terrain DHM request with optional parameters

{
   "settings": {
         "product_name": "dhm",
         "post_spacing": 2.0,  
         "vertical_system": "ELLIPSOID",
         "aoi": {
              "type": "Feature",
              "geometry": {
                   "type": "Polygon",
                   "coordinates": [
                    [
                         [
                              -77.07986908814675,
                              38.92366474267453
                         ],
                         [
                              -77.07986908814675,
                              38.86693932273354
                         ],
                         [
                              -76.98544542389106,
                              38.86693932273354
                         ],
                         [
                              -76.98544542389106,
                              38.92366474267453
                         ],
                         [
                              -77.07986908814675,
                              38.92366474267453
                         ]
                    ]
               ]
          }
     }
},
 "output_configs":[
        {
            "type": "amazon_s3",
            "bucket": "bucket-name",
        }
   ],
"notifications": [
      {
           "type": "email",
           "target": "youremail@email.com",
           "level": "INTERMEDIATE"
      }
  ]
}

3d Point Cloud

The Vivid Terrain Point Cloud describes the earth's surface form and texture (natural color) in industry standard point cloud formats.

POST  https://api.maxar.com/ordering/v1/pipelines/3d/point-cloud/

All Vivid Terrain Point Cloud orders are delivered with the following values.

Parameter	Value
Sampling density	4 Points/m2
Reference system	WGS84 G1674
Coordinate system	UTM

Optional ordering parameters for Vivid Terrain Point Cloud:

Parameter	Default Value	Optional Value	Example
file_format	LAZ	LAS	"file_format": "LAS"
vertical_system	EGM2008	ELLIPSOID,EGM96	"vertical_system": "ELLIPSOID"

Example Vivid Terrain Point Cloud request with default values

{
   "settings": {
         "product_name": "point_cloud",
         "aoi": {
              "type": "Feature",
              "geometry": {
                   "type": "Polygon",
                   "coordinates": [
                    [
                         [
                              -77.07986908814675,
                              38.92366474267453
                         ],
                         [
                              -77.07986908814675,
                              38.86693932273354
                         ],
                         [
                              -76.98544542389106,
                              38.86693932273354
                         ],
                         [
                              -76.98544542389106,
                              38.92366474267453
                         ],
                         [
                              -77.07986908814675,
                              38.92366474267453
                         ]
                    ]
               ]
          }
     }
},

 "output_configs":[
        {
            "type": "amazon_s3",
            "bucket": "bucket-name",
            "prefix": "set a unique prefix name"
        }
   ],
"notifications": [
      {
           "type": "email",
           "target": "youremail@email.com",
           "level": "INTERMEDIATE"
      }
  ]
}

Building Vectors

Vivid Terrain Buildings describes the footprint and superstructures of buildings in a vector format with height attribution for a 3D representation. The vectors are automatically extracted from the Vivid Terrain 3D Surface Model. DTM coverage is required.

POST https://api.maxar.com/ordering/v1/pipelines/3d/buildings/

All Vivid Terrain Building orders are delivered with the following values.

Parameter	Value
File format	ESRI Shapefile
Reference system	WGS84 G1674
Coordinate system	UTM

Optional ordering parameters for Vivid Terrain Buildings:

Note: DTM coverage is required. The option of ‘height segmented’ enables a greater level of detail for variable roof heights but results in a noisier representation of the buildings.

Parameter	Description	Default Value	Optional Value	Example
level_of_detail	The level of building detail, either non-height segemented or height-segmented.	non_height_segmented	height_segmented	"level_of_detail": "height_segmented"
vertical_system	The vertical coordinate system to define the origin of the height.	EGM2008	ELLIPSOID, EGM96	"vertical_system": "EGM96"

Example Vivid Terrain Buildings order with default values:

Example Vivid Terrain Buildings order with default values:

{
   "settings": {
         "product_name": "buildings",
         "aoi": {
              "type": "Feature",
              "geometry": {
                   "type": "Polygon",
                   "coordinates": [
                    [
                         [
                              -77.07986908814675,
                              38.92366474267453
                         ],
                         [
                              -77.07986908814675,
                              38.86693932273354
                         ],
                         [
                              -76.98544542389106,
                              38.86693932273354
                         ],
                         [
                              -76.98544542389106,
                              38.92366474267453
                         ],
                         [
                              -77.07986908814675,
                              38.92366474267453
                         ]
                    ]
               ]
          }
     }
},
  "output_configs":[
        {
            "type": "amazon_s3",
            "bucket": "bucket-name",
            "prefix": "set a unique prefix name"
        }
   ],
"notifications": [
      {
           "type": "email",
           "target": "youremail@email.com",
           "level": "FINAL_ONLY"
      }
  ]
}

Vegetation Vectors

Vivid Terrain Vegetation describes the vegetation footprint in a vector format with height attribution for a 3D representation. The vectors are automatically extracted from the Vivid Terrain 3D Surface Model.

POST  https://api.maxar.com/ordering/v1/pipelines/3d/vegetation/

Parameter	Value
File format	ESRI Shapefile
Reference system	WGS84 G1674
Coordinate system	UTM
Vertical threshold	2m

Optional ordering parameters for Vivid Terrain Vegetation:

Parameter	Default Value	Optional Value	Example
cut_by_buildings_vectors	true	false	"cut_by_buildings_vectors": false
vertical_system	EGM2008	ELLIPSOID, EGM96	"vertical_system: "ELLIPSOID"
vegetation_representation	stacked	non_stacked	"vegetation_representation": "non-stacked"

Note: DTM coverage is required. When cut_by_buildings_vectors is set to false, vegetation polygons will overlap building polygons. The option of ‘non-stacked’ will render simplified cylindrical vegetation polygons that have a single diameter attributed to a single height for each assumed tree location.

Example Vivid Terrain Vegetation request with defaults

{
   "settings": {
         "product_name": "vegetation",
         "aoi": {
              "type": "Feature",
              "geometry": {
                   "type": "Polygon",
                   "coordinates": [
                    [
                         [
                              -77.07986908814675,
                              38.92366474267453
                         ],
                         [
                              -77.07986908814675,
                              38.86693932273354
                         ],
                         [
                              -76.98544542389106,
                              38.86693932273354
                         ],
                         [
                              -76.98544542389106,
                              38.92366474267453
                         ],
                         [
                              -77.07986908814675,
                              38.92366474267453
                         ]
                    ]
               ]
          }
     }
},
 "output_configs":[
        {
            "type": "amazon_s3",
            "bucket": "bucket-name",
            "prefix": "set a unique prefix name"
        }
   ],
"notifications": [
      {
           "type": "email",
           "target": "youremail@email.com",
           "level": "INTERMEDIATE"
      }
  ]
}

Validate an order request

To validate your order before placing it, send your request body to the /validate endpoint first.

POST https://api.maxar.com/ordering/v1/pipelines/3d/vegetation/validate

This will verify that your request is formatted correctly and contains the required settings and allowed values for those settings.

Successful response

  "data": {
    "usage": {
      "product_id": 472,
      "units": "sqkm",
      "quantity": 320.97577101135454,
      "description": "total_coverage_percent [100%]"
    }
  },
  "links": {
    "request": "https://api.maxar.com/ordering/v1/pipelines/3d/vegetation/validate"
  },
  "request_timestamp": "2025-03-27T20:12:56Z",
  "response_timestamp": "2025-03-27T20:13:17Z",
  "request_duration": 21
}

Get a usage estimate

To get a usage estimate for the order, send an order request to the /estimate endpoint. The response includes the request body and a usage estimate in square kilometers.

POST https://api.maxar.com/ordering/v1/pipelines/3d/vegetation/estimate

Estimate response

{
  "data": {
    "usage_estimate": [
      {
        "pipeline_id": "3d/vegetation",
        "product_id": 472,
        "metrics": [
          {
            "units": "sqkm",
            "quantity": 320.976
          }
        ],
        "date_reported": "2025-03-27T20:15:22Z"
      }
    ],
    "order_config": {
      "pipeline_id": "3d/vegetation",
      "output_config": {
        "amazon_s3": {
          "bucket": "example-bucket",
          "prefix": "example-prefix"
        }
      },
      "notifications": [
        {
          "type": "email",
          "target": "user@example.com",
          "level": "INTERMEDIATE"
        }
      ],
      "metadata": {
        "project_name": "north-albuquerque"
      },
      "settings": {
        "product_name": "vegetation",
        "aoi": {
          "type": "Feature",
          "geometry": {
            "type": "Polygon",
            "coordinates": [
              [
                [
                  -106.694584,
                  35.14967
                ],
                [
                  -106.4534,
                  35.14967
                ],
                [
                  -106.4534,
                  35.281419
                ],
                [
                  -106.694584,
                  35.281419
                ],
                [
                  -106.694584,
                  35.14967
                ]
              ]
            ]
          }
        }
      }
    }
  },
  "links": {
    "request": "https://api.maxar.com/ordering/v1/pipelines/3d/vegetation/estimate"
  },
  "request_timestamp": "2025-03-27T20:15:03Z",
  "response_timestamp": "2025-03-27T20:15:22Z",
  "request_duration": 19
}

Get order status

Once an order is placed, you can monitor its status or review the details of your order by making the following request with your order ID.

POST 
https://api.maxar.com/ordering/v1/orders/:id

The id was returned in the response body to your order request. It can also be found in your notifications.

Cancel an order

Orders can be canceled before delivery begins by making the following request with the order ID:

POST https://api.maxar.com/ordering/v1/orders/{id}/cancel

Successful status code: 202 Accepted

Example Cancel Order response 202

{
    "data": {
        "order_id": "123412341234"
    },
    "links": {
        "request": "https://api.maxar.com/ordering/v1/orders/123412341234/cancel"
    },
    "request_timestamp": "2023-09-29T20:49:50Z",
    "response_timestamp": "2023-09-29T20:49:51Z",
    "request_duration": 1.0
}

Example Cancel Order response 400

In this example, the order was already delivered so the order can no longer be cancelled. The API returns an error.

Status: 400 Bad request

{
    "links": {
        "request": "https://api.maxar.com/ordering/v1/orders/123412341234/cancel"
    },
    "request_timestamp": "2024-12-02T19:56:14Z",
    "response_timestamp": "2024-12-02T19:56:15Z",
    "request_duration": 1.0,
    "error": {
        "error_code": "invalid_request",
        "error_type": "invalid_request_error",
        "error_messages": [
            "Order is already in delivery and cannot be canceled"
        ]
    }
}

Once the delivery process has started, the request cannot be canceled.