Skip to content

Monitoring for New Acquisitions

Last updated: June 20, 2022


See also: Monitor API Reference

Overview

ARD monitors let you watch for new imagery acquisitions based on an Area of Interest (AOI) and optional matching criteria. When the monitor finds a newly acquired matching image, it sends a notification. An ID number from the notification can be used to order the image.

A monitor only looks for new imagery as it is acquired by the satellites. It does not look for imagery that already exists in the archive. To find historical imagery from the Maxar archive, use the Select API.

Use this guide to:

  1. Create a Monitor by specifying an AOI and any additional match criteria.

  2. Learn about the contents of the notification that is sent when a new matching image acquisition is found.

  3. Order the new imagery by using the match query ID in the "select_id" field of an order request.

You can also view the match history for a monitor, view the matching criteria for the monitor, and see a list of monitors you've created. Monitors can be deactivated when they are no longer useful.

Step 1: Create a monitor

To set up a new monitor, you'll submit the following information in an API request:

  • a name for the monitor (optional)

  • a description for the monitor (optional)

  • an AOI in bounding box, WKT, or GeoJSON format (required)

  • additional matching query criteria (optional)

  • a notification type of "email" or "sns" (required). Both types can be included in a single request.

Back to top

Create a monitor from an existing imagery selection

A monitor is a useful tool for finding new imagery to add to a stack of imagery you've previously selected and ordered. To do this, create your monitor using the AOI and query criteria from the original selection request. If your original selection criteria included the datetime field or the stack_depth field, you should not include those in your monitor.

Monitor example

You can create a monitor request from the Select example by removing datetime and stack_depth and adding name and description (both optional) and a "notify" section.

{
    "name": "albuquerque",
    "description": "traffic flow project monitor for new imagery Albuquerque, NM, USA",
    "bbox": [-106.8, 35.1, -106.4, 35.4],
    "query": {
    "collect_month_day": {
            "between": ["03-20", "06-21"]
        },
        "aoi:cloud_free_percentage": {
            "gte": 95.0
        },
        "aoi:data_percentage": {
            "gte": 75.0
        },
        "view:off_nadir": {
            "lt": 30
        },
        "view:sun_elevation": {
            "gt": 5
        }
    },
    "actions": [{
        "action": "notify",
        "notifications": [{
                "type": "email",
                "address": "shea.barnes@myemail.com"
            },
            {
                "type": "sns",
                "topic_arn": "arn:aws:sns:us-east-1:817603998267:albuquerque-monitor-sns-ReceiveMonitorEventTopic-JY3Y3Z60O2KE"
            }
        ]
    }]
}
Back to top

Naming and describing a monitor

You can give your monitor a name to help identify it later in a monitor list or a match notification. For example, if you set up a monitor to watch for new imagery in an area of Albuquerque, New Mexico, USA, you can name it "albuquerque" for easy reference. Naming your monitor is optional.

You can also add an optional description to the monitor for more detail. For example, you can describe your "albuquerque" monitor as a "traffic flow project monitor for new imagery Albuquerque, NM, USA".

Adding an AOI to your monitor

An AOI is required to set up a monitor. You can submit a polygon in GeoJSON geometry or WKT format in the intersects field or bounding box coordinates in the bbox field.

field value
intersects Accepts a polygon or multipolygon in GeoJSON geometry or WKT format.
bbox Accepts bounding box coordinates in [minx, miny, maxx, maxy] format.

Optional matching criteria

Additional matching criteria can be used to set up a monitor. See the Monitor API Reference for a list of available query fields.

Notifications

Setting up a monitor requires a notification type. The accepted types are "notification" and "sns". Your request can use one notification type or both. It can also include more than one of either notification type.

Example monitor request

POST https://ard.maxar.com/api/v1/monitor/
{
    "name": "albuquerque",
    "description": "traffic flow project monitor for new imagery Albuquerque, NM, USA",
    "bbox": [-106.8, 35.1, -106.4, 35.4],
    "query": {
        "aoi:cloud_free_percentage": {
            "gte": 95.0
        },
        "aoi:data_percentage": {
            "gte": 75.0
        },
        "view:off_nadir": {
            "lt": 30
        },
        "view:sun_elevation": {
            "gt": 5
        }
    },
    "actions": [{
        "action": "notify",
        "notifications": [{
                "type": "email",
                "address": "shea.barnes@myemail.com"
            },
            {
                "type": "sns",
                "topic_arn": "arn:aws:sns:us-east-1:817603998267:albuquerque-monitor-sns-ReceiveMonitorEventTopic-JY3Y3Z60O2KE"
            }
        ]
    }]
}

Step 2: Get a new imagery notification

Monitors continuously look for new imagery acquisitions that match their criteria. Each matched acquisition will trigger a new notification, which means every notification has only one acquisition ID listed. Notifications can be received in email or an SNS topic.

The notification includes the following information:

item description
Acquisition ID The Acquisition ID for the new image.
Monitor The name and ID number for the monitor that found the match If no name was given, only the ID will be provided.
Description A description of the monitor to help identify it later.
Query ID You can use this ID number to place an order by placing it in the "select_id" field of an order request. The ID always starts with a "Q". Example:Q58629704881870092. We also refer to this ID as the "query ID".
Links A set of links to the results in different formats.
Monitor link A link to the monitor and its matching criteria.

All links in notifications require authentication.

Back to top

Example email notification

Monitor notification email example

  • If a Monitor does not have a name, the email will only display the monitor ID.

  • If the monitor is not given a description, the email will say "Description: none".

Example:

Example email header with monitor id and description equals none

Example SNS notification

  "monitor_id": 186240496009840965,
  "monitor_name": albuquerque
  "monitor_description": traffic flow project monitor for new imagery Albuquerque, NM, USA
  "acquisition_id": 1040010073C0CF00,
  "query_id": Q58629704881870092,
  "links":
    "details": "https://ard.maxar.com/api/v1/metadata/query/Q58629704881870092",
    "geojson": "https://ard.maxar.com/api/v1/metadata/query/Q58629704881870092/results?format=geojson",
    "stac": "https://ard.maxar.com/api/v1/metadata/query/Q58629704881870092/results?format=stac",
    "monitor":"https://ard.maxar.com/api/v1/monitor/config/186240496009840965"

Back to top

Step 3: Ordering a matched acquisition

When a monitor finds a match, it assigns an ID to the results, called a query ID. This ID always starts with a "Q", for example Q5862970488187009. The ID is included in the email or sns notification.

You can order the matching imagery from the monitor by using the query ID in the select_id field of an order request body. This will order the tiles from the matched acquisition that intersect the AOI for the monitor. Only tiles that match any provided query criteria will be ordered. If new imagery found by a monitor is ordered, it falls into the "fresh" imagery age category (90 days or newer).

Back to top

Example order

The query ID from the example email notification is Q58629704881870092.

{
    "select_id": "Q58629704881870092",
    "output_config": {
        "amazon_s3": {
            "bucket": "my-ard-bucket",
            "prefix": "albuquerque_project"
        }
    },
    "bundle_adjust": true,
    "notifications": [{
        "type": "email",
        "address": "shea.barnes@myemail.com"
    }]
}

For more information about placing an order, see the ARD Ordering Guide.

Back to top

More Monitor API requests

The following actions can also be taken by making a request to the Monitor API. See Monitor API Reference for example queries and responses.

  • View the match history for a monitor

  • List all of your monitors

  • Get the details of a specific monitor

  • Delete a monitor (this deactivates the monitor but does not permanently delete the record)

Back to top

Back to top