Vivid Standard Basemaps

This Guide explains how to order Vivid Standard 30 cm basemap imagery. To order Vivid Advanced basemap imagery, see Ordering Vivid Advanced 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 Standard 30 cm basemap imagery 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 Standard, these are:

Namespace: basemaps
Name: vividstandard30

POST https://api.maxar.com/ordering/v1/pipelines/basemaps/vividstandard30/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"=.5`
mosaic_identifiers	JSON Array of Strings	No	An optional list of specific Vivid Standard products to include in the assembly of the product. The default behavior is to return the most current mosaic. Note: The addition of this field is only used in specific cases. See Mosaic identifiers.	`"mosaic_identifiers": "Vivid_Standard_30_HR01_23Q4"`
output_bands	string	No	Vivid Standard 30cm products are available as either 3-band (RGB) products or 4-band (BGRN) products. Vivid Standard 30cm products will be delivered as 3-band products unless this output bands parameter is included in the request to specify that the product should be delivered as 4-bands (BGRN).	`"output_bands":"BGRN",`

Note: The default order will have the output_bands parameter set to RGB. Therefore, it is not necessary to include the output_bands parameter in the order request unless a 4-band product is required.

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 Standard: 0.31 meters

Maximum allowed GSD for Vivid Standard: 15.0 meters

Mosaic identifiers

Mosaic identifiers should only be included for cases where you are requesting a specific production build there is an optional setting to include mosaic_identifiers. In this case the default behavior of presenting the most current mosaic will be overridden with the given mosaic_identifiers.

When this parameter isn't specified, then the system automatically determines which of the most recent published versions of Vivid Standard products intersect the provided AOI and includes those products in the order to the layout engine.

If a Vivid product is included in the list that doesn't intersect the specified AOI, then it is ignored.

At least one of the specified products must intersect the specified AOI.

["Vivid_Standard_30_HR01_23Q4", "Vivid_Standard_30_IT01_23Q4", "Vivid_Standard_30_FR01_23Q4", "Vivid_Standard_30_PL01_23Q4", "Vivid_Standard_30_AT01_23Q4", "Vivid_Standard_30_DE02_23Q4", "Vivid_Standard_30_DE01_23Q4", "Vivid_Standard_30_NL01_23Q4"]

Example Vivid Standard order

{
    "settings": {
        "aoi": {
            "type": "Polygon",
            "coordinates": [
                [
                      [130.11722536556212,32.17215990537166],
                      [130.15958976798888,32.172159905372695],
                      [130.1595897679839,32.19453856905048],
                      [130.11722536556212,32.19453856905291],
                      [130.11722536556212,32.17215990537166]
                    ]
                ]
      }
    },
   "output_configs":[
        {
            "type": "download",
            "format": "zip"
        }
   ],
    "notifications": [
        {
            "type": "email",
            "target": "email@myemail.com",
            "level": "INTERMEDIATE"
        }
    ],
    "metadata": {
        "description": "UAT-vividstandard-aoi1-nagashima"
    }
}

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": "vividstandard-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
if mosaic_identifiers are included, validation checks that they're available.

Request URL:

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

Example valid response:

{
    "data": {
        "status": "VALID",
        "status_details": {
            "message": "The order is valid."
        },
        "usage": [
            {
                "product_id": 236,
                "units": "sqkm",
                "quantity": 21346.207,
                "description": "Vivid Standard 30cm"
            }
        ]
    },
    "links": {
        "request": "https://api.maxar.com/ordering/v1/pipelines/basemaps/vividstandard30/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/vividstandard30/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 Standard 30 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_Standard_{orderID}/
├──📁 metadata_strips/
│  ├──📄 Vivid_Standard_{orderID}.dbf
│  ├──📄 Vivid_Standard_{orderID}.dbf
│  ├──📄 Vivid_Standard_{orderID}.prj
│  ├──📄 Vivid_Standard_{orderID}.shp
│  └──📄 Vivid_Standard_{orderID}.shx
├──📁 metadata_tiles/
│  └──  📄 Vivid_Standard_{orderID}.geojson
└──📁 raster_tiles/
   ├── 📄 Vivid_Standard_{orderID}_{quadkey}.tif
   └── 📄 [ ... additional tiles] 

Vivid Standard Basemaps

Overview​

Place an order​

Request URL​

Settings​

Area of Interest (AOI)​

Output GSD (Ground Sample Distance)​

Mosaic identifiers​

Example Vivid Standard order​

Validate an order request​

Get a usage estimate​

Get order status​

Cancel an order​

Order output files​