Vivid Mosaic 15 cm Basemaps

This Guide explains how to order Vivid Mosaic 15 cm basemap imagery. To order Vivid Mosaic 30 cm basemaps, see Ordering Vivid 30 cm basemaps. Vivid Mosaic 30cm and Vivid Mosaic 15 cm orders accept the same request body. Only the optional parameters vary.

Overview

Vivid Mosaic 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 Mosaic 15 cm can be ordered for download by making a request to the 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 Mosaic 15 cm, 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 Mosaic 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 Mosaic 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 Mosaic 15 cm: 0.16 meters

Maximum allowed GSD for Vivid Mosaic 15 cm: 15.0 meters

Example: Vivid Mosaic 15 cm order

This example shows a Vivid Mosaic 15 cm 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": "user@example.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": "user@example.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 Mosaic 15cm order delivery. There may be additional files in your delivery. Additional spec information about these files is available upon request. Contact your Vantor 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]