Object Detection (Inference)

Ordering and downloading object detection data is in limited release and is not currently available to all accounts.

Overview

The Object Detection Inference API is used to place orders for object detections on Maxar imagery. The API enables users to order detections of the following objects:

Aircraft
Construction equipment
Military equipment
Vehicles
Vessels

Note:

Object detection runs can only be executed on imagery available in the Raster Analytics API. This does not contain the entire Maxar archive. Some images can be added to the Raster Analytics API from the MGP Pro UI by using the "Request to Exploit" function. See the Raster Analytics Guide for more information.
If an image in your request is not available, the entire order request will fail and you will be informed the image does not exist.
The Discovery API can be used to check image availability. Images available in Raster Analytics can be found in the cloud-optimized-archive catalog. See the Searching the Catalog section of the Raster Analytics Guide.
Object Detection orders are run on-demand only. It is not possible to use Monitoring to watch for object detections. However you can set a Monitor to watch an AOI for new imagery and use Auto-Ordering to automatically order Object Detection on matching imagery. See Object Detection Monitoring for an example.

Supported requests

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

Request	Description	Method	Path
Place an order	Places an order that will be delivered to your specified cloud storage location.	POST	`/ordering/v1/pipelines/insights/object-detection/order`
Validate order before submitting	Verifies that the request JSON is formatted correctly and that the settings are valid.	POST	`/ordering/v1/pipelines/insights/object-detection/validate`
Estimate Usage before submitting	Estimates how expensive the order will be.	POST	`/ordering/v1/pipelines/insights/object-detection/estimate`
Get the details of an order	Submit an order ID to view the order's details and status information.	GET	`/ordering/v1/orders/{id}`
Cancel an order	Submit an order ID to cancel the order before the delivery process begins.	POST	`/ordering/v1/orders/{id}/cancel`

Placing an order

Example URL for an object-detection order:

POST https://api.maxar.com/ordering/v1/pipelines/insights/object-detection/order

Settings

When placing an order, order settings specific to the type of content selected are passed in the settings object.

Object detection orders are described using syntax. Each Feature in the FeatureCollection represents running an object detection model on a given image. The Feature's geometry describes where to run the model in the image. To run the model over the whole image you can pass a geometry of null. The Feature's properties fields are used to specify the image ID and the model to run.

Field	Type	Description	Required	Default Value	Allowed Values
inputs	FeatureCollection	Parameters to run the inference pipeline.	Yes	N/A	N/A
image	boolean	If true image will be delivered along with object detections.	No	`false`	`true` or `false`
mask	boolean	If true enable object detection mask. To view the masks for each model, see model masks.	No	`false`	`true` or `false`

Note: the image option is considered an image delivery and will consume additional credits.

FeatureCollection

Field	Type	Description	Required	Default Value	Allowed Values
type	string	Type of feature collection.	Yes	N/A	`FeatureCollection`
features	Feature array	Each feature can be a different model or image but will be delivered together.	Yes	N/A	N/A

Feature

Field	Type	Description	Required	Default Value	Allowed Values
type	string	Feature type.	Yes	N/A	`Feature`
geometry	GeoJSON Polygon, MultiPolygon, or `null`	Areas of interest over which to run inference.	Yes	N/A	N/A
properties	Properties	Properties for the inference run.	Yes	N/A	N/A

If you provide null for the geometry, the model will be run on the full image.

Properties

Field	Type	Description	Required	Default Value	Allowed Values
model	string	Model name (case sensitive). To view a list of subclasses for each model, see model classes.	Yes	N/A	`Aircraft`, `Construction`, `Military`, `Vehicle`, or `Vessel`
image	string	Catalog ID.	Yes	N/A	N/A

Example order request body

This is an example of an order request body for object detection content:

{
    "settings": {
        "image": false;
        "mask": false
        "inputs": {
            "type": "FeatureCollection",
            "features": [{
                "type": "Feature",
                "geometry": null,
                "properties": {
                    "image": "1020010106CCC400",
                    "model": "Aircraft"
                }
            }]
        }
    },
    "output_configs": [{
        "type": "amazon_s3",
        "bucket": "example-bucket",
        "prefix": "example-prefix"
    }],
    "notifications": [{
        "type": "email",
        "target": "username@myemail.com",
        "level": "INITIAL_FINAL"
    }],
    "metadata": {
        "project_name": "example-project-name"
    }
}

Example Order with geometry

{
    "settings": {
        "image": false,
        "mask": false,
        "inputs": {
            "type": "FeatureCollection",
            "features": [{
                "type": "Feature",
                "geometry": {
                    "type": "Polygon",
                    "coordinates": [[
                        [-105.003495, 39.911555],
                        [-105.003495, 39.914018],
                        [-105.000298, 39.914018],
                        [-105.000298, 39.911555],
                        [-105.003495, 39.911555]
                    ]]
                },
                "properties": {
                    "image": "1040010093CBF900",
                    "model": "Vehicle"
                }
            }]
        }
    },
    "output_configs": [{
        "type": "amazon_s3",
        "bucket": "example-bucket",
        "prefix": "example-prefix"
    }],
    "notifications": [{
        "type": "email",
        "target": "username@myemail.com",
        "level": "INITIAL_FINAL"
    }],
    "metadata": {
        "project_name": "example-project-name"
    }
}

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

Example Order response

Status: 202 Accepted

{
    "data": {
        "id": "order-id",
        "date_created": "2024-12-02T19:56:02Z",
        "date_modified": "2024-12-02T19:56:03Z",
        "creator_id": "creator-id",
        "creator_group_id": "creator-group-id",
        "pipeline_id": "insights/object-detection",
        "output_configs": [{
            "type": "amazon_s3",
            "bucket": "example-bucket",
            "prefix": "example-prefix"
        }],
        "notifications": [{
            "type": "email",
            "target": "username@myemail.com",
            "level": "INITIAL_FINAL"
        }],
        "metadata": {
            "project_name": "example-project-name"
        },
        "status": "RECEIVED",
        "status_details": {},
        "cancellation_requested": false,
        "process_details": {},
        "delivery_details": {},
        "order_links": {
            "self": "https://api.maxar.com/ordering/v1/orders/order-id",
            "events": "https://api.maxar.com/ordering/v1/orders/order-id/events"
        },
        "settings": {
            "image": false,
            "mask": false,
            "inputs": {
                "type": "FeatureCollection",
                "features": [{
                    "type": "Feature",
                    "geometry": {
                        "type": "Polygon",
                        "coordinates": [[
                            [-105.003495, 39.911555],
                            [-105.003495, 39.914018],
                            [-105.000298, 39.914018],
                            [-105.000298, 39.911555],
                            [-105.003495, 39.911555]
                        ]]
                    },
                    "properties": {
                        "image": "1040010093CBF900",
                        "model": "Vehicle"
                    }
                }]
            }
        }
    },
    "links": {
        "request": "https://api.maxar.com/ordering/v1/pipelines/insights/object-detection/order"
    },
    "request_timestamp": "2024-12-02T19:56:00Z",
    "response_timestamp": "2024-12-02T19:56:04Z",
    "request_duration": 4.0
}

Validating 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/insights/object-detection/validate

This will verify that your request is formatted correctly and has valid settings.

Example validation response 200

Status: 200 OK

{
    "data": {
        "message": "OK"
    },
    "links": {
        "request": "https://api.maxar.com/ordering/v1/pipelines/insights/object-detection/validate"
    },
    "request_timestamp": "2024-12-02T19:37:38Z",
    "response_timestamp": "2024-12-02T19:37:47Z",
    "request_duration": 9.0
}

Example validation response 400

In this example, validation did not pass because the image property is missing.

Status: 400 Bad request

{
    "links": {
        "request": "https://api.maxar.com/ordering/v1/pipelines/insights/object-detection/validate"
    },
    "request_timestamp": "2024-12-02T19:24:55Z",
    "response_timestamp": "2024-12-02T19:24:56Z",
    "request_duration": 1.0,
    "error": {
        "error_code": "invalid_request_body",
        "error_type": "invalid_request_error",
        "error_messages": [
            "Invalid order settings: $.inputs.features[0].properties: {\"model\": \"Vehicle\"} is not valid under the following schemas [{\"description\": \"Inference input properties schema.\", \"title\": \"InferenceInputProperties\", \"type\": \"object\", \"properties\": {\"image\": {\"title\": \"Image\", \"type\": \"string\", \"description\": \"Image catalog ID.\"}, \"model\": {\"title\": \"Model\", \"type\": \"string\", \"description\": \"Model name.\"}}, \"required\": [\"model\", \"image\"]}, {\"type\": \"null\"}] due to some or all of the following errors [\"$.inputs.features[0].properties: \"image\" is a required property\", \"$.inputs.features[0].properties: {\"model\": \"Vehicle\"} is not of type \"null\"\"]"
        ]
    }
}

Estimating usage for an order request

To get usage for an order before placing it, send your request body to the /estimate endpoint first.

POST https://api.maxar.com/ordering/v1/pipelines/insights/object-detection/estimate

Example usage estimate response 200

Status: 200 OK

{
    "data": {
        "usage_estimate": [{
            "pipeline_id": "insights/object-detection",
            "metrics": [{
                "units": "sqkm",
                "quantity": 0.07475448323726654,
                "description": null,
                "usage_details": {}
            }],
            "product_id": 485,
            "date_reported": "2024-12-02T19:44:17Z"
        }],
        "order_config": {
            "pipeline_id": "insights/object-detection",
            "output_configs": [{
                "type": "amazon_s3",
                "bucket": "example-bucket",
                "prefix": "example-prefix"
            }],
            "notifications": [{
                "type": "email",
                "target": "username@myemail.com",
                "level": "INITIAL_FINAL"
            }],
            "metadata": {
                "project_name": "example-project-name"
            },
            "settings": {
                "image": false,
                "mask": false,
                "inputs": {
                    "type": "FeatureCollection",
                    "features": [{
                        "type": "Feature",
                        "geometry": {
                            "type": "Polygon",
                            "coordinates": [[
                                [-105.003495, 39.911555],
                                [-105.003495, 39.914018],
                                [-105.000298, 39.914018],
                                [-105.000298, 39.911555],
                                [-105.003495, 39.911555]
                            ]]
                        },
                        "properties": {
                            "image": "1040010093CBF900",
                            "model": "Vehicle"
                        }
                    }]
                }
            }
        }
    },
    "links": {
        "request": "https://api.maxar.com/ordering/v1/pipelines/insights/object-detection/estimate"
    },
    "request_timestamp": "2024-12-02T19:44:13Z",
    "response_timestamp": "2024-12-02T19:44:17Z",
    "request_duration": 4.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.

Canceling an order

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.

Note: The request cannot be canceled once the delivery process has started.

Order output files

The object detection orders include a GeoJSON (.geojson) file for each catalog ID plus some additional order metadata files. If image is set to true in the order settings, the order will also include a GeoTIFF (.tif) image for each catalog ID. The naming convention is as follows:

📄 <mgp-order-ID>_manifest.json
📄 <mgp-order-ID>-request.json
📁 <mgp-order-ID>
├── 📄 <catalog-ID>.geojson
├── 📄 <catalog-ID>.tif
└── ... (additional TIFF and GeoJSON pairs per image)

Example GeoJSON file containing object detections:

{
    "type": "FeatureCollection",
    "name": "output",
    "crs": {
        "type": "name",
        "properties": {
            "name": "urn:ogc:def:crs:OGC:1.3:CRS84"
        }
    },
    "features": [
        {
            "type": "Feature",
            "properties": {
                "id": "5cd13e07-5172-485b-b4f1-91f6d6ba1cd3",
                "class": "Car",
                "confidence": 0.52396756410598755,
                "image": "1040010093CBF900",
                "url": "https://api.maxar.com/analytics/v1/raster/ortho/geotiff?function=pansharp_ortho&p=collect_identifier=%221040010093CBF900%22&p=crs=%22UTM%22&p=bands=%22red%2Cgreen%2Cblue%22&p=dra=true&p=acomp=false&p=hd=false&p=ancillary_type=null",
                "datetime": "2024-03-23T17:38:45.279Z",
                "model": "Vehicle",
                "version": "1.3.0",
                "order": "6668428953001637032"
            },
            "geometry": {
                "type": "Polygon",
                "coordinates": [[
                    [-105.001265946098485, 39.913800962457245],
                    [-105.001266442058892, 39.913822824594547],
                    [-105.001199000079282, 39.913823731819498],
                    [-105.001198504140291, 39.91380186968189],
                    [-105.001265946098485, 39.913800962457245]
                ]]
            }
        },
        ...
    ]
}

Model classes

This list shows the available models and their respective subclasses:

Aircraft

Fixed Wing Civilian Large
Fixed Wing Civilian Medium
Fixed Wing Civilian Small
Fixed Wing Military Large
Fixed Wing Military Medium
Fixed Wing Military Small
Military Folded Wing
Rotary Wing
UAV

Construction equipment

Bulldozer
Cement Mixer
Crane Truck
Dump/Haul Truck
Excavator
Ground Grader
Large Crane

Military equipment

Armored Personnel Carrier
Field Artillery (Active)
Field Artillery (Inactive)
Military Truck
Mobile Missile/Rocket Launcher
Tank/Self-Propelled Artillery

Vehicles

Bus
Car
Cargo Truck
Construction Truck
Tractor Trailer
Trailer No Truck
Truck Tractor No Trailer
Utility Vehicle

Vessels

Aircraft Carrier
Barge
Bulk Carrier
Civilian Small Boat
Container Ship
Crane Vessel
Fishing Vessel
General Cargo Ship
Ore Carrier
Passenger Vessel
Roll On Roll Off
Submarine
Tanker
Tugboat
Warship
Yacht

Model masks

Land and water masks derived from OpenStreeMap Land and Water polygons are available to further refine the area of interest when ordering object detections. This table shows the available models and their corresponding mask.

Model	Mask
Aircraft	Land
Construction Equipment	Land
Military Equipment	Land
Vehicles	Land
Vessels	Water

Note that the masks are used to include rather than exclude object detections. Only object detections that intersect the mask are included in the results. For example, enabling the Vehicle model's mask will limit detections to vehicles found on land. Cars on a ferry or container ship would be excluded.

Object Detection (Inference)

Overview​

Supported requests​

Placing an order​

Settings​

FeatureCollection​

Feature​

Properties​

Example order request body​

Validating an order request​

Estimating usage for an order request​

Get order status​

Canceling an order​

Order output files​

Model classes​

Aircraft​

Construction equipment​

Military equipment​

Vehicles​

Vessels​

Model masks​