Core Imagery

Overview

The following core imagery products can be ordered through the Ordering API.

Content Type	Namespace	Name	Imagery Specification
System-Ready(1B)	`imagery`	`system-ready`	System-Ready Imagery Data Sheet
View-Ready(2A)	`imagery`	`view-ready`	View-Ready Imagery Data Sheet
View-Ready-Ortho (OR2A)	`imagery`	`view-ready-ortho`	View-Ready Imagery Data Sheet
Map-Ready (3D)	`imagery`	`map-ready`	Map-Ready Imagery Data Sheet

This documentation describes the requirements that are specific for ordering core imagery content. To see the full description of an order request, see the Ordering API Guide. Code examples in this document show ordering system-ready (1B) imagery.

Core imagery product type information

Each core imagery product type has a set of product details with specified values. Some of these values can be overridden when the order is placed. Each product's default values are described below.

System-Ready (1B) product defaults

Name	Default Value
resampling_kernel	MTF
best_available_gsd	true
compression	DEFLATE
customer_framing	Scene
dynamic_range_adjustment	none
file_format	GeoTIFF
output_bit_depth	16
product_type	1B
product_option	Pan_or_Any_Bundle
scene_length_km	14
scene_overlap_km	0.5
acomp	none

View-Ready (2A) product defaults

Name	Default Value
resampling_kernel	ENH
best_available_gsd	true
compression	DEFLATE
dynamic_range_adjustment	auto
file_format	GeoTIFF
output_bit_depth	8
product_type	2A
product_option	Pan_or_3_Band_PanSharpen
projection_datum_option	UTM_WGS84_Meter
tiling	16kx16k
acomp	none

View-Ready-Ortho (OR2A) product defaults

Name	Default Value
resampling_kernel	CC
best_available_gsd	true
compression	DEFLATE
dynamic_range_adjustment	none
file_format	GeoTIFF
output_bit_depth	16
product_type	OR2A
product_option	Pan_or_Any_Bundle
projection_datum_option	UTM_WGS84_Meter
tiling	16kx16k
acomp	none

Map-Ready (3D) Product defaults

Name	Default Value
resampling_kernel	ENH
best_available_gsd	true
compression	DEFLATE
dynamic_range_adjustment	auto
file_format	GeoTIFF
output_bit_depth	8
product_type	3D
product_option	Pan_or_3_Band_PanSharpen
projection_datum_option	UTM_WGS84_Meter
tiling	16kx16k
acomp	none

Allowed values

The values for the fields listed in this table can be overridden and replaced with one of the allowed values. 8Band bundles that end in _L and MS1_MS3 are product options for ordering WorldView Legion imagery.

Name	Allowed Values
product_option	`"3BandPanSharpen"`, `"4BandBundle"`, `"4BandPanSharpen"`, `"8BandBundle"`, `"8BandBundle_L`, `"8BandPanSharpen"`, `8BandPanSharpen_L`,`"Any_8Band_Bundle"`, `"Any_Bundle"`,`"MS1"`, `"MS1_MS2"`, `"MS1_MS3"`, `"Pan"`, `"Pan_or_3_Band_PanSharpen"`, `"Pan_or_4_Band_PanSharpen"`, `"Pan_or_Any_8Band_Bundle"`, `"Pan_or_Any_Bundle"`, `"Pan_or_Pan_MS1"`, `"Pan_or_Pan_MS1_MS2"`, `"Pan_or_Pan_MS1_MS3"`, `"Pan_or_Pan_MS1_or_Pan_MS1_MS2"`
file_format	`"GeoTIFF"`, `"GeoTIFF-32"`, `"NITF 2.1"`, `"NITF 2.1 NCDRD"`
compression	`"DEFLATE"`, `"LZW"`, `"NPJE"`, `"None"`
dynamic_range_adjustment	`"auto"`, `"manual"`, `"none'`
acomp	`"acomp"`, `"none"`
output_bit_depth	`8`, `16`
resampling_kernel	`"Bilinear"`,`"CC"`,`"DHS"`,`"MTF"`,`"NN"` `"ENH"`
projection_datum_option	`Geographic_WGS84_DecimalDegree, UTM_NAD83_Meter, UTM_WGS84_Meter`
is_high_definition *	`true`, `false`
use_best_gsd	`true`, `false`
requested_gsd	`.15`, `.30`

To see a list of allowed values for a specific product type, you can make an API request to get the schema for the pipeline that processes the product.

*The is_high_definition: true should not be used alone. When using this field, you also need to specify a requested gsd and set "use best gsd" to false.

For example, you need all three of these fields to create a 15 CM HD order:

        "is_high_definition": true,
        "requested_gsd": 0.15,
        "use_best_gsd": false,

For requested GSD, use 0.3 for native 50 cm imagery, and 0.15 for native 30 cm imagery.

Supported requests

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

Example URL for ordering system-ready imagery:

GET https://api.maxar.com/ordering/v1/pipelines/imagery/system-ready

Resampling kernels

Resampling kernels are algorithms that alter the pixel size or resolution of an image. Resampling is necessary to align the pixels in an image to a coordinate grid. Resampling techniques alter the original pixel values.

Resampling Kernel	Description	Use With	Example
Bilinear	Interpolates based on four nearest neighbors, smoother than nearest neighbor but can blur edges. Available for panchromatic, MS, and bundles.	Not available for pansharpened.	`"resampling_kernel": "Bilinear"`
Cubic Convolution(CC)	Uses a cubic equation to interpolate, providing smoother results than bilinear. Provides slightly sharper edge detail than the bilinear interpolation method.	Available for panchromatic, pansharpened, MS, and bundles.	`"resampling_kernel": "CC"`
Enhanced (ENH)	Uses a high-pass Laplacian filter applied to the panchromatic data as a preprocessing step before pansharpening. The result is an image with very fine detail and excellent color balance.	Available for panchromatic and pansharpened. Not available for MS or bundles.	`"resampling_kernel": "ENH"`
MTF	Uses an 8 x 8-pixel window to determine the value of the destination pixel. Produces the sharpest edge detail of all the methods.	Available for panchromatic, MS, and bundles. Not available for pansharpened.	`"resampling_kernel": "MTF"`
Nearest Neighbor (NN)	Selects the radiance value from the nearest pixel in the input image. Does not alter the radiance values of the original image. This method can result in a blocky or disjointed image because no averaging is performed.	Available for panchromatic, MS, and bundles. Not available for pansharpened.	`"resampling_kernel": "NN"`
DHS	The DHS kernel should be mainly used when images are resampled to a GSD that is greater than the captured resolution. (ie, the native GSD is 31 cm but it is resampled to 50 cm). The end effect of this kernel is to make images softer, so to reduce aliasing.	n/a	`"resampling_kernel": "DHS"`

Limitations

Map-Ready images can only be produced from collects with an off-nadir angle of less than 30 degrees in order to meet horizontal accuracy specifications.

Supported requests

The following requests can be made to the Ordering API. The base path is api.maxar.com.

Note: The API interface uses the term pipeline to reference the process that creates and delivers the requested content. The output of the pipeline is the ordered content.

Request Type	Method	Path	Description
Place an Order	`POST`	`ordering/v1/pipelines/imagery/{name}/order`	Place an order for imagery.
Validate Order	`POST`	`ordering/v1/pipelines/imagery/{name}/validate`	Verify that the order passes validation checks before submission.
Estimate Usage	`POST`	`ordering/v1/pipelines/imagery/{name}/estimate`	Get a usage estimate for an order request before placing the order.
Get Order Details	`GET`	`ordering/v1/orders/{orderID}`	Get the details and status of an order request.
Cancel Order	`POST`	`ordering/v1/orders/{orderid}/cancel`	Cancels the order specified in the URL path. Orders cannot be canceled once the delivery process has started.

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: imagery
Name: system-ready, view-ready, view-ready-ortho, or map-ready

POST https://api.maxar.com/ordering/v1/pipelines/basemaps/imagery/map-ready

Content-specific settings

When placing an order, some information is specific to the type of content selected. This information is grouped together as "settings". The table below describes the required and optional information for core imagery orders.

Field	Required	Type	Description	Example
customer_description	Required	string	A brief description for the order. Must be less than 100 characters.	`"customer_description": "north albuquerque"`
inventory_ids	Required	array	Array of Catalog ids. A Catalog ID is a unique identifier for an image acquisition.	`"inventory_ids": ["104001007E8B1F00","104001007BC14F00"]`
aoi	Optional	object	A single polygon GeoJSON geometry. If an AOI is included, only the parts of the image that intersect the AOI are delivered.	See example order request for an AOI example.

AOI rules

If an AOI is included, it must meet the following requirements:

The geometry must be 2-dimensional and provided as a GeoJSON geometry (GeoJSON feature collections are not supported).
The AOI must only include a single polygon. Multi-polygons are not accepted.
The AOI must be within the boundaries of Maxar's digital elevation model (DEM). This excludes Greenland, the Arctic, and Antarctica.
A polygon cannot cross the anti-meridian, or +180°/-180° longitude. An AOI that crosses the anti-meridian should be formatted as two polygons that includes a polygon for each side of the line. The polygons must be submitted as two separate orders.
The polygon must be at least 250 m long/wide.
The maximum number of vertices allowed is 1000.
The AOI must be at least 1 sq km.
The AOI must be less than 1000 sq km.

Example Core Imagery order

Core imagery order with default settings

This is an example of an order request body with the default settings for a core imagery order. The complete Ordering request body is described in the Ordering API Guide.

This request uses the default settings for the pipeline as shown above. It is possible to override some processing parameters.

{
    "settings": {
        "customer_description": "customer-description",
        "inventory_ids": [
            "104001007E8B1F00",
            "104001007BC14F00"
        ],
        "aoi": {
            "type": "Polygon",
            "coordinates": [
                [
                    [-106.694584, 35.14967],
                    [-106.4534, 35.14967],
                    [-106.4534, 35.281419],
                    [-106.694584, 35.281419],
                    [-106.694584, 35.14967]
                ]
            ]

        }
    },

    "output_configs": [ 
        {
            "type": "download",
            "format": "zip"
        }
    ],

    "notifications": [
      {
        "type": "email",
        "target": "user@example.com",
        "level": "FINAL_ONLY"
      }
    ],

    "metadata": {
        "project_name": "north-albuquerque"
    }
}  

Core imagery order with overrides

This example shows an ordering example with overrides.

{
    "settings": {
      "aoi": {
        "type": "Polygon",
        "coordinates": [
          [
            [
              -123.14830629447482,
              49.272523954428266
            ],
            [
              -123.14830629447482,
              49.24221441101426
            ],
            [
              -123.10082049428735,
              49.24221441101426
            ],
            [
              -123.10082049428735,
              49.272523954428266
            ],
            [
              -123.14830629447482,
              49.272523954428266
            ]
          ]
        ]
      },
      "overrides": {
        "product": {
          "product_details": {
            "compression": "DEFLATE",
            "acomp": "acomp",
            "file_format": "GeoTIFF",
            "product_option": "4BandPanSharpen",
            "is_high_definition": true,
            "output_bit_depth": 16,
            "dynamic_range_adjustment": "none",
            "requested_gsd": 0.3,
            "use_best_gsd": false,
            "projection_datum_option": "Geographic_WGS84_DecimalDegree"
          }
        }
      },
      "customer_description": "WV2 50 to 30cm HD",
      "inventory_ids": [
        "10300101172FE400"
      ]
    
  },

  "output_configs": [ 
    {
      "type": "download",
      "format": "zip"
    }
  ],

  "notifications": [{
    "type": "email",
    "target": "user@example.com",
    "level": "INTERMEDIATE"
  }],


    "metadata": {
        "project_name": "name your project to make it easy to identify later. This is optional."
    }
}  

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

Example Order response 202

Status:202 Accepted

{
   {
  "data": {
    "id": "6585113434270312211",
    "date_created": "2024-11-15T22:24:54Z",
    "date_modified": "2024-11-15T22:25:02Z",
    "creator_id": "f:63a7af62-7902-4925-9382-3d920450a524:676",
    "creator_group_id": "881",
    "pipeline_id": "imagery/view-ready",
    "output_configs": [ 
      {
        "type": "download",
        "format": "zip"
      }
    ],
    "notifications": [
      {
        "type": "email",
        "target": "user@example.com",
        "level": "INTERMEDIATE"
      }
    ],
    "metadata": {
      "project_name": "north-albuquerque"
    },
    "status": "RECEIVED",
    "status_details": {},
    "cancellation_requested": false,
    "process_details": {},
    "delivery_details": {},
    "order_links": {
      "self": "https://api.maxar.com/ordering/v1/orders/6585113...",
      "events": "https://api.maxar.com/ordering/v1/orders/6585113.../events"
    },
    "settings": {
      "customer_description": "customer-description",
      "inventory_ids": [
        "104001007E8B1F00",
        "104001007BC14F00"
      ],
      "aoi": {
        "type": "Polygon",
        "coordinates": [
          [
            [
              -106.694584,
              35.14967
            ],
            [
              -106.4534,
              35.14967
            ],
            [
              -106.4534,
              35.281419
            ],
            [
              -106.694584,
              35.281419
            ],
            [
              -106.694584,
              35.14967
            ]
          ]
        ]
      },
      "overrides": {
        "product": {
          "product_details": {
            "is_high_definition": "true",
            "file_format": "NITF 2.1",
            "product_option": "Pan",
            "compression": "None"
          }
        }
      }
    }
  },
  "links": {
    "request": "https://api.maxar.com/ordering/v1/pipelines/imagery/view-ready/order"
  },
  "request_timestamp": "2024-11-15T22:24:52Z",
  "response_timestamp": "2024-11-15T22:25:03Z",
  "request_duration": 11
}

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/imagery/view-ready/validate

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

Example validation response 200

Status: 200 OK

{
    "data": {
        "message": "validation successful"
    },
    "links": {
        "request": "https://api.maxar.com/ordering/v1/pipelines/imagery/system-ready/validate"
    },
    "request_timestamp": "2023-10-10T21:12:30Z",
    "response_timestamp": "2023-10-10T21:12:32Z",
    "request_duration": 2.0
}

Get a usage estimate

To get a usage estimate for the ordered imagery, make a request to the /estimate endpoint. The response includes the request body and a usage estimate in square kilometers and features.

POST https://api.maxar.com/ordering/v1/pipelines/imagery/system-ready/estimate

Estimate usage response 200

Status: 200 OK

{
    "data": {
        "usage_estimate": [
            {
                "pipeline_id": "imagery/system-ready",
                "metrics": [
                    {
                        "units": "sqkm",
                        "quantity": 320.976,
                        "description": "Imagery greater than 90 days old",
                        "usage_details": {}
                    },
                    {
                        "units": "feature_count",
                        "quantity": 2.0,
                        "description": "Number of images",
                        "usage_details": {}
                    }
                ],
                "product_id": 244,
                "date_reported": "2023-10-10T21:22:01Z"
            }
        ],
        "order_config": {
            "pipeline_id": "imagery/system-ready",
            "settings": {
                "customer_description": "customer-description",
                "inventory_ids": [
                    "104001007E8B1F00",
                    "104001007BC14F00"
                ],
                "aoi": {
                    "type": "Polygon",
                    "coordinates": [
                        [
                            [
                                -106.694584,
                                35.14967
                            ],
                            [
                                -106.4534,
                                35.14967
                            ],
                            [
                                -106.4534,
                                35.281419
                            ],
                            [
                                -106.694584,
                                35.281419
                            ],
                            [
                                -106.694584,
                                35.14967
                            ]
                        ]
                    ]
                },
                "overrides": {
                    "product": {
                        "product_details": {
                            "file_format": "NITF 2.1",
                            "product_option": "Pan",
                            "compression": "None"
                        }
                    }
                }
            },
            "output_configs":[
                {
                    "type": "download",
                    "format": "zip"
                }
            ],
            "notifications": [
                {
                    "type": "email",
                    "target": "user@example.com",
                    "level": "INITIAL_FINAL"
                }
            ],
            "metadata": {
                "project_name": "north-albuquerque"
            }
        }
    },
    "links": {
        "request": "https://api.maxar.com/ordering/v1/pipelines/imagery/system-ready/estimate"
    },
    "request_timestamp": "2023-10-10T21:21:58Z",
    "response_timestamp": "2023-10-10T21:22:01Z",
    "request_duration": 3.0
}

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.

Overview​

Core imagery product type information​

System-Ready (1B) product defaults​

View-Ready (2A) product defaults​

View-Ready-Ortho (OR2A) product defaults​

Map-Ready (3D) Product defaults​

Allowed values​

Supported requests​

Resampling kernels​

Limitations​

Supported requests​

Place an order​

Request URL​

Content-specific settings​

AOI rules​

Example Core Imagery order​

Core imagery order with default settings​

Core imagery order with overrides​

Validate an order request​

Get a usage estimate​

Get order status​

Cancel an order​

Overview

Core imagery product type information

System-Ready (1B) product defaults

View-Ready (2A) product defaults

View-Ready-Ortho (OR2A) product defaults

Map-Ready (3D) Product defaults

Allowed values

Supported requests

Resampling kernels

Limitations

Supported requests

Place an order

Request URL

Content-specific settings

AOI rules

Example Core Imagery order

Core imagery order with default settings

Core imagery order with overrides

Validate an order request

Get a usage estimate

Get order status

Cancel an order