Vivid Advanced Basemaps

This Guide explains how to order Vivid Advanced basemap imagery. To order Vivid Standard basemaps, see Ordering Vivid Standard basemaps. Vivid Advanced and Vivid Standard accept the same request body. Only the optional parameters vary.

Overview

Maxar Vivid basemaps provide high-quality, visually consistent views of Earth. These basemaps are ideal for use as map contextual layers, for extracting map features at scale, and for visualization within an application. Vivid Advanced can be ordered for download by making a request to the MGP Ordering API.

Place an order

Request URL

An Order request URL requires a "namespace" and a "name. These tell the Ordering API what product to order.

POST https://api.maxar.com/ordering/v1/pipelines/{namespace}/{name}/order

For Vivid Advanced, these are:

• Namespace: basemaps
• Name: vividadvanced15

POST https://api.maxar.com/ordering/v1/pipelines/basemaps/vividadvanced15/order

Settings

The "settings" object is a required component of an ordering request. "Settings" tells the Ordering API the Area of Interest the basemap imagery should intersect. In addition, you can override the output ground sample distance (gsd) for downsampling and exclude terracolor imagery as a backfill option. These are explained in more detail below.

Setting	Type	Required	Description	Example
AOI	GeoJSON String	Yes	The GeoJSON polygon or multipolygon definition of the area of interest (AOI) that is to be used as the extent of the resulting Vivid mosaic product that will be constructed for the order.	See ordering example for formatting.
include_terracolor	Boolean	No	Indicates whether 150 m Landsat (Terracolor) imagery pixels should be used to fill out the order AOI if high resolution Vivid imagery isn't available within all areas of the AOI. Bathymetry imagery is included in the definition of Terracolor. Defaults to "true".	include_terracolor=false
output_gsd	Number	No	Specifies the ground sample distance in meters for a pixel of the requested product in situations where the output product should have a lower GSD than the native GSD of the underlying Vivid product. See Output GSD.	output_gsd=0.15

Area of Interest (AOI)

AOI Format The AOI must be formatted as a GeoJSON polygon or multipolygon

AOI size The AOI must fall within the minimum and maximum:

• Minimum AOI size: 0.10 sqkm
• Maximum AOI size: 500,000 sqkm

Output GSD (Ground Sample Distance)

The output GSD parameter should only be used if downsampling is being requested.

Minimum allowed GSD for Vivid Advanced: 0.16 meters

Maximum allowed GSD for Vivid Advanced: 15.0 meters

Example: Vivid Advanced order

This example shows a Vivid Advanced order request body with the required fields.

{
    "settings": {
        "aoi": {
            "type": "Polygon",
            "coordinates": [
                [
                  [-99.14756444477842,19.413369945629753],
                  [-99.11785819143236,19.413369945629753],
                  [-99.11785819143236,19.44196181195376],
                  [-99.14756444477842,19.44196181195376],
                  [-99.14756444477842,19.413369945629753]
              ]
          ]
      }
    },
   "output_configs":[
        {
            "type": "download",
            "format": "zip"
        }
   ],
    "notifications": [
        {
            "type": "email",
            "target": "email@myemail.com",
            "level": "INTERMEDIATE"
        }
    ],
    "metadata": {
        "description": "vividadvanced-mexicocity"
    }
}

Example with optional parameters

   {
    "settings": {
        "aoi": {
            "type": "Polygon",
            "coordinates": [
                [
                 [-116.40076390570952,28.57075189209303],
                  [-108.0604091578171,28.570751891474302],
                  [-108.06040915533963,34.1932674504456],
                  [-116.40076390662584,34.193267450287024],
                  [-116.40076390570952,28.57075189209303]
              ]
          ]
      },
      "include_terracolor": false,
      "output_gsd": 0.5
    },

   "output_configs":[
        {
            "type": "download",
            "format": "zip"
        }
   ],
    "notifications": [
        {
            "type": "email",
            "target": "email@myemail.com",
            "level": "INTERMEDIATE"
        }
    ],
    "metadata": {
        "description": "vividadvanced-swmexico"
    }
}

See the Outputs and Notifications guides for more information on these sections of the order payload.

Validate an order request

To validate your order before placing it, send your request body to the /validate endpoint first. Validation checks for the following:

• the request body is formatted correctly
• the required fields are included
• only allowed values are used
• the AOI is in GeoJSON format
• the AOI falls between the minimum and maximum allowed size

Request URL:

POST https://api.maxar.com/ordering/v1/pipelines/basemaps/vividadvanced15/validate

Example validation response 200

Status: 200 OK

{
    "data": {
        "status": "VALID",
        "status_details": {
            "message": "The order is valid."
        },
        "usage": [
            {
                "product_id": 23,
                "units": "sqkm",
                "quantity": 21346.207,
                "description": "Vivid Standard 30cm"
            }
        ]
    },
    "links": {
        "request": "https://api.maxar.com/ordering/v1/pipelines/basemaps/vividadvanced15/validate"
    },
    "request_timestamp": "2024-12-04T18:08:35Z",
    "response_timestamp": "2024-12-04T18:08:47Z",
    "request_duration": 12.0
}

Get a usage estimate

This endpoint returns the usage estimate and a copy of the json request body.

Request URL:

POST https://api.maxar.com/ordering/v1/pipelines/basemaps/vividadvanced15/estimate

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.

Order output files

This list shows the primary set of files included in a Vivid Advanced order delivery. There may be additional files in your delivery. Additional spec information about these files is available upon request. Contact your Maxar representative.

📄 {orderID}_manifest.json
📄 {orderID}_request.json
📁 Vivid_Advanced_2_{orderID}/
├──📁 metadata_strips/
│  ├──📄 Vivid_Advanced_2_{orderID}.dbf
│  ├──📄 Vivid_Advanced_2_{orderID}.dbf
│  ├──📄 Vivid_Advanced_2_{orderID}.prj
│  ├──📄 Vivid_Advanced_2_{orderID}.shp
│  └──📄 Vivid_Advanced_2_{orderID}.shx
├──📁 metadata_tiles/
│  └──  📄 Vivid_Advanced_2_{orderID}.geojson
└──📁 raster_tiles/
   ├── 📄 Vivid_Advanced_2_{orderID}_{quadkey}.tif
   └── 📄 [ ... additional tiles]