Monitoring for New Acquisitions¶

Last updated: December 1, 2022

Overview¶

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

A Monitor only looks for new images as they are acquired by the satellites. It does not look for imagery that already exists in the archive.

Create a monitor¶

To create a Monitor API request, there are required fields and additional optional fields.

Name and describe your monitor (optional)¶

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 may name it "albuquerque" for easy reference.

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

Define your Area of Interest (AOI) (required)¶

A monitor must include an AOI in one of the following fields:

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.

Include additional matching criteria (optional)¶

Include additional matching criteria to further filter your results. For example, you can filter results by cloud free percentage, sun elevation, off-nadir angle, and more. See the Monitor API Reference for a list of available query fields.

Specify the monitor type (optional)¶

There are two types of monitors:

A "standard" monitor continues to look for imagery until the date or date range in the request has passed or the monitor is deactivated.
A "single-match" monitor looks for imagery for each cell that intersects the AOI one time. Once the AOI is filled in, the monitor is no longer active.

The default monitor type is "standard". To change the default, include "monitor_type": "single-match" in your request.

An ARD tasking request generates a single-match monitor to track progress. A monitor generated by a tasking request will include the tasking_id in the response.

Validate your monitor request before submitting (optional)¶

To verify that your monitor request is valid before submitting, include "dry_run": true. This verifies that your request is valid, but does not create a monitor. Once you've verified that your request is valid, change the value of this field to false, or remove it from the request body. The default value is false.

Set a monitor expiration date (optional)¶

To set a deactivation date for your monitor, add the expires field with an ISO formatted date to your request. For example, "expires": "2022-12-15". If no expiration is set, the monitor expires when the account's original contract end date is passed. Note that if the contract end date is extended, the monitor end date is not updated.

Set an imagery date or date range (optional)¶

To limit monitor matching to a single date or a date range, include the datetime field in your request. The value must be an ISO-8601 formatted date, date and time, or date range.

Any of the following can be used with the date datetime field.

date/time formats	example
date only	`"datetime": "2020-07-01"`
date and time	`"datetime": "2020-07-01T00:00:00Z"`
date range	`"datetime": "2020-07-01T00:00:00Z/2021-01-25T23:59:59Z"`
date range with open end date	`"datetime": "2020-07-01/.."`
date range with open start date	`"datetime": "../2021-01-25"`

To set an open-ended date range, use two dots in place of a date/time. For example, "datetime": "../2018-02-28" means the start date is open-ended.

When an open-ended start date is submitted, the monitor starts watching on the date and time of submission.
When an open-ended end date is submitted, the monitor stops watching when the account's original end date is passed. Note that if the contract end date is extended, the monitor end date is not updated.
If no time interval is supplied with the end date, the monitor stops watching at 23:59:59 on the last day.

If both the expires field and the datetime field are used in a request, the earliest date applies.

In this example, the monitor will expire before the datetime end date is reached.

    "expires": "2023-03-15",
    "datetime": "2023-01-01/2023-05-01"

In this example, the monitor will remain in "active" state, but will stop watching when the datetime end date is reached.

    "expires": "2023-07-15",
    "datetime": "2023-01-01/2023-05-01"

Set up notifications (required)¶

Setting up a monitor requires a notifications type in the actions object. The accepted types are "email" and "sns". You can include one notification type or both types in a single request.

Monitor request example¶

{
    "name": "albuquerque",
    "description": "monitor for new seasonal 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
        }
    },
    "monitor_type": "single-match",
    "dry_run": true,
    "expires": "2023-07-15",
    "actions": [{
        "action": "notify",
        "notifications": [{
            "type": "email",
            "address": "sheabarnes@myemail.com"
        }]
    }]
}

See the Monitor API Reference documentation for a response example and field definitions.

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.

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

To receive SNS notifications, you need an SNS topic with an access policy that allows ARD to publish notifications.

To learn how to set up an SNS topic, see the Amazon SNS Documentation.

Access policy¶

Your SNS topic must have an access policy that gives ARD publish access.

Edit your access policy configurations to include the ARD principal, and with the required "Publish" action. Below is an example of a functional Access Policy that can be copied and pasted directly into the JSON editor.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::334489843805:root"
      },
      "Action": "sns:Publish",
      "Resource": "*"
    }
  ]
}

The values in the JSON object for Effect, Principal, and Action should not be changed.

You can replace "*" with a resource or submit it as is.

The notifications object requires the following:

the notification type must be "sns" .
a topic Amazon Resource Name (ARN) is required. The naming convention for a topic ARN is arn:aws:sns:[region]:[aws account id]:[topic].

"notifications": [
      {
          "type": "sns",
          "topic_arn": "arn:aws:sns:us-east-1:1234567890987:my-topic"
      }
  ]

  "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"

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).

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.

Additional 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 monitors
Get the details of a specific monitor
Delete a monitor (this deactivates the monitor but does not permanently delete the record).