Change Monitoring (Limited Release)

Ordering and downloading CM-SAR (20 m) data is in limited release and is not currently available to all accounts.

Overview

Change Monitoring (CM) SAR 20 m data can be ordered for download by making a request to the MGP Ordering API. When placing an order for CM, specify the following name and namespace in the URL.

Change Type	Namespace	Name	CM Technical Specification
CM-SAR(20m)	`Insights`	`cm-sar-ordering`	CM-SAR

Note: Names and namespaces are case-sensitive.

Ordering CM

This documentation describes the requirements that are specific for ordering CM data. To see the full description of an order request, see the Ordering API Guide. Code examples in this document use the cm-sar-ordering pipeline.

When you place an order for CM, you will:

include the name and the namespace in the URL path.
include the settings object for the pipeline in the order request body.

Supported requests

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

Request	Description
Place an order	Places an order that will be delivered to your specified cloud storage location.	`POST/ordering/v1/pipelines/{namespace}/{name}/order`
Validate order before submitting	Verifies that the request json is formatted correctly and that the settings are valid.	`POST/ordering/v1/pipelines/{namespace}/{name}/validate`
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`

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 CM, these are:

Namespace: Insights
Name: cm-sar-ordering

Example URL for a cm-sar-ordering order:

POST https://api.maxar.com/ordering/v1/pipelines/Insights/cm-sar-ordering/order

This document describes the parts of the ordering process that are specific to a CM order. The full ordering process is described in the Intro to Ordering.

Settings

When placing an order, some information is specific to the type of content selected. This information is grouped together as "settings".

All CM orders require the following settings fields:

Field	Type	Description	Example
start_date	string	ISO 8601 formatted start date of change window, inclusive.	`“start_date”: “2020-02-01"`
end_date	string	ISO 8601 formatted end date of change window, inclusive.	`“end_date”: “2020-02-28"`
change_area_polygon	geoJSON object	Geojson polygon of area to order archived change.	`{“type”:“Polygon”,“coordinates”:[[[...]]]}`

Note: This example shows only the settings section. See the Example Order request for a complete Order example.

"settings":{
    "start_date": "2020-02-01",
    "end_date": "2020-02-28",
    "change_area_polygon": {"type":"Polygon","coordinates":[[[...]]}
}

Change area polygons

Change area polygons must be submitted in GeoJSON format.
The maximum size for a change area polygon is 10,000 sq km.

Example CM order

This is an example of an order request body for CM-SAR content:

{
    "settings": {
        "start_date": "2020-02-01",
        "end_date": "2020-02-28",
        "change_area_polygon": {
            "type": "Polygon",
            "coordinates": [
                    [
                        [47.8, 29.25],
                        [47.8, 29.27],
                        [47.81, 29.27],
                        [47.81, 29.25],
                        [47.8, 29.25]
                    ]
            ]
        }
    },
    "output_configs": [
    {
      "type": "download",
            "format": "zip"
        }
  ],
    "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": "2023-09-29T20:46:55Z",
        "date_modified": "2023-09-29T20:47:05Z",
        "creator_id": "creator-id",
        "creator_group_id": "creator-group-id",
        "pipeline_id": "Insights/cm-sar-ordering",
        "settings": {
            "start_date": "2020-02-01",
            "end_date": "2020-02-28",
            "change_area_polygon": {
                "type": "Polygon",
                "coordinates": [
                    [
                        [
                            47.8,
                            29.25
                        ],
                        [
                            47.8,
                            29.27
                        ],
                        [
                            47.81,
                            29.27
                        ],
                        [
                            47.81,
                            29.25
                        ],
                        [
                            47.8,
                            29.25
                        ]
                    ]
                ]
            }
        },
        "output_configs": [ 
          {
            "type": "download",
            "format": "zip"
          }
        ],
        "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"
        }
    },
    "links": {
        "request": "https://api.maxar.com/ordering/v1/pipelines/Insights/cm-sar-ordering/order"
    },
    "request_timestamp": "2023-09-29T20:46:49Z",
    "response_timestamp": "2023-09-29T20:47:06Z",
    "request_duration": 17.0
}

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/Insights/cm-sar-ordering/validate

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

Example validation response 200

Status: 200 OK

{
    "data": {
        "message": "validation successful"
    },
    "links": {
        "request": "https://api.maxar.com/ordering/v1/pipelines/Insights/cm-sar-ordering/validate"
    },
    "request_timestamp": "2023-10-10T18:49:53Z",
    "response_timestamp": "2023-10-10T18:50:04Z",
    "request_duration": 11.0
}

Example validation response 400

In this example, validation did not pass because the start date was after the end date.

Status: 400 Bad request

{
    "links": {
        "request": "https://api.maxar.com/ordering/v1/pipelines/Insights/cm-sar-ordering/validate"
    },
    "request_timestamp": "2023-10-10T18:58:03Z",
    "response_timestamp": "2023-10-10T18:58:06Z",
    "request_duration": 3.0,
    "error": {
        "error_code": "invalid_request",
        "error_type": "invalid_request_error",
        "error_messages": [
            "Pipeline Insights/cm-sar-ordering: {'message': 'Failure in validating order: Start date must be earlier than end date'}"
        ]
    }
}

Get a usage estimate

To get a usage estimate for the order, send an order request to the /estimate endpoint. The response includes the request body and a usage estimate in square kilometers.

POST https://api.maxar.com/ordering/v1/pipelines/Insights/cm-sar-ordering/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.

Output files

The output of a CM order is a Single GeoJSON feature collection file in the format of {order_id}.geojson.

Change Monitoring (Limited Release)

Overview​

Ordering CM​

Supported requests​

Place an order​

Request URL​

Settings​

Change area polygons​

Example CM order​

Validate an order request​

Get a usage estimate​

Get order status​

Cancel an order​

Output files​