Skip to content

Monitor Resource

Last updated: August 29, 2022


Monitor

/monitor

Monitor for new imagery acquisitions based on an AOI and optional query criteria.

See also: Monitoring User Guide

Monitor endpoints

http method path name description
POST /monitor/ Create a Monitor Create a Monitor that notifies you when an image is found that matches the user-submitted parameters.
GET /monitor/history/{monitor_id}/history View a monitor's match history Get the match history for a specific monitor.
GET /monitor/config/{monitor_id} Get a specific monitor Get the details for a specific monitor in your account.
GET /monitor List monitors List monitors you created.
DEL /monitor/config/{monitor_id} Delete a monitor Delete a monitor by ID. This deactivates the monitor, but does not delete the record.

Headers

key value description
Authorization Bearer {{token}} Authentication method for ARD API requests.
Content-Type application/json Applies to POST, PATCH, PUT requests, which require a JSON body.

Create a Monitor

POST /monitor/

Example:

POST https://ard.maxar.com/api/v1/monitor

Request body

parameter required description example
name optional A human-readable name for easy reference in notifications and monitor listing. "name": "albuquerque"
description optional A human-readable description of the monitor. "description": "monitor for new imagery Albuquerque, NM, USA"
intersects required if not using bbox The geometry for the AOI to be monitored; accepts GeoJSON or WKT geometries "intersects": "POLYGON ((-106.8 35.1,-106.4 35.1,-106.4 35.4,-106.8 35.4,-106.8 35.1))"
bbox required if not including intersects The bounding box coordinates for the AOI to be monitored, in [minx, miny, maxx, maxy] format. "bbox": [-106.8, 35.1, -106.4, 35.4]
query optional The query parameters the monitor will use to finding matching imagery. See Query fields table below.
actions required An array field to list the action object of "notify" for monitoring. See Actions object.

Query fields

parameter default value description example
aoi:cloud_free_percentage none The percentage of the AOI intersection area not covered by clouds. "aoi:cloud_free_percentage":{"gte": 95.0}
aoi:data_percentage none The percentage of the tile area intersected by the AOI. "aoi:data_percentage":{"gte": 75.0}
collect_day optional The day the imagery was collected. Can be a single value or range with an operator. "collect_day": {"between": ["15", "21"]}
collect_month optional The month the imagery was collected. Can be a single value or a range with an operator. "collect_month": {"in": ["12", "01", "02"]}
collect_month_day optional The month and day the imagery was collected. Can be a single value or a range with operator. "collect_month_day": {"between": ["03-20","06-21"]}
view:azimuth none The angle measured from the sub-satellite point (point on the ground below the platform) between the scene center and true north. Measured clockwise from north in degrees (0-360). "view:azimuth": {"lte": 60}
view:off_nadir none The angle from the sensor between nadir (straight down) and the scene center, measured in degrees (0-90). (Note: for tiles, this is the average off-nadir angle of the full image strip.) "view:off_nadir": {"lte": 20}
view:sun_azimuth none From the scene center point on the ground, this is the angle between true north and the sun. Measured clockwise in degrees (0-360). "view:sun azimuth": {"lte": 30}
view:sun_elevation "gte": 5 The angle from the tangent of the scene center point to the sun. Measured from the horizon in degrees (0-90). See "nighttime imagery" note below. "view:sun_elevation": {"gte": 20}
multi_resolution_avg none The average multispectral resolution for the strip. This is the native resolution as collected by the satellite. "multi_resolution_avg":{"lte": 2.0}
multi_resolution_max none The maximum multispectral resolution for the strip. This is the native resolution as collected by the satellite. "multi_resolution_max":{"eq": 8.0}
multi_resolution_min none The minimum multispectral resolution for the strip. This is the native resolution as collected by the satellite. "multi_resolution_min":"eq": 1.7}
off_nadir_max none The maximum off-nadir angle of the full image strip. "off_nadir_max": {"eq": "20"}
off_nadir_min none The minimum off-nadir angle of the full image strip. "off_nadir_min": {"eq": 0}
pan_resolution_avg none The average panchromatic resolution for the strip. This is the native resolution as collected by the satellite. "pan_resolution_avg": {"lte": .47}
pan_resolution_max none The maximum panchromatic resolution for the strip. This is the native resolution as collected by the satellite. "multi_resolution_max": {"eq": .60}"
pan_resolution_min none The minimum panchromatic resolution for the strip. This is the native resolution as collected by the satellite. "multi_resolution_min": {"eq": .40}
platform geoeye-01, worldview-02, worldview-03, and worldview-04 The name of the satellite used to collect the image. Allowed values are geoeye-01, worldview-02, worldview-03, and worldview-04. For worldview-03, only VNIR imagery is available as ARD. "platform": {"eq": "worldview-03"}

Note: By default, results include imagery from geoeye-01, worldview-02, worldview-03, and worldview-04. See WorldView-1 Ordering for examples of ordering WorldView-1 imagery..*

Query operators

operator description example
between The field value is between the filter values, inclusive (synonym for range). "view:azimuth": {"between": [90, 270]}.
contains The filter value is in the field value. If the field value is a string, then the filter value is matched as a substring of the field value. If the field value is a list/array, then the filter value is matched as an element of the list. "instruments": {"contains": "VNIR"}.
eq The field value is equal to the filter value. "platform": {"eq": "worldview-02"}.
gt The field value is greater than the filter value. "aoi:cloud_free_percentage":
gte The field value is greater than or equal to the filter value. "aoi:cloud_free_percentage": {"gte": 90}.
in The field value is one of the listed filter values. "platform": {"in": ["geoeye-01", "worldview-03"]}.
lt The field value is less than the filter value. "view:off_nadir": {"lt": 30}.
lte The field value is less than or equal to the filter value. "view:off_nadir": {"lte": 30}.
not-contains The filter value is not in the field value. If the field value is a string, then the filter value is matched as a substring of the field value. If the field value is a list/array, then the filter value is matched as an element of the list. "instruments": {"not-contains": "SWIR"}.
range The field value is between the filter values, inclusive (synonym for between). "view:azimuth": {"range": [90, 270]}.

Actions object

parameter required description example
action Required The action "notify" is required so that the user receives a notification when the monitoring finds new matching imagery. "action": "notify"
notifications required The notifications object specifies the type of notification to send when new imagery that matches the monitor is found. See examples below.
type required The type is "email" or "sns". Both types can be requested. See examples below.
address required for "email" type A valid email address where the notifications will be sent. See example below.
topic_arn required for "sns" type. The topic arn where the sns notifications should be sent. See example below.

Example Requests: Create a Monitor

This request uses an AOI in bounding box format and an "email" notification type.

{
    "name": "albuquerque",
    "description": "monitor for new seasonal 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": "myemail@email.com"
        }]
    }]
}

This example uses a WKT formatted polygon AOI and an SNS notification type.

{
  "name": "albuquerque",
  "description": "monitor for new imagery Albuquerque, NM, USA",
    "intersects": "POLYGON ((-106.8 35.1,-106.4 35.1,-106.4 35.4,-106.8 35.4,-106.8 35.1))",
    "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": "sns",
            "topic_arn": "valid-topic-arn"
        }]
    }]
}

Monitor Response

Example response

{
    "monitor": {
        "cell_ids": [
            "Z13-031133231111",
            "Z13-031133231113",
            "Z13-031133231131",
            "Z13-031133231133",
            "Z13-031133231311",
            "Z13-031133231313",
            "Z13-031133231331",
            "Z13-031133320000"      
        ],
        "monitor_id": "5863093108873554704",
        "name": "albuquerque",
        "description": "monitor for new imagery Albuquerque, NM, USA",
        "account_id": "5589150080369207736",
        "user_id": "967f33a5-1d80-4a74-9334-fcae93fd203f",
        "active": true,
        "intersects": null,
        "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
            },
            "platform": {
                "in": [
                    "geoeye-01",
                    "worldview-02",
                    "worldview-03",
                    "worldview-04"
                ]
            },
            "instruments": {
                "not-contains": "SWIR"
            }
        },
        "actions": [
            {
                "action": "notify",
                "notifications": [
                    {
                        "type": "email",
                        "address": "shea.barnes@mymail.com"
                    }
                ]
            }
        ],
        "created": "2022-02-23T17:39:24Z"
    },
    "links": {
        "self": "https://ard.maxar.com/api/v1/monitor/config/5863093108873554704",
        "history": "https://ard.maxar.com/api/v1/monitor/history/5863093108873554704",
        "account": "https://ard.maxar.com/api/v1/admin/account/5589150080369207736"
    },
    "response_timestamp": "2022-02-23T17:39:24Z"
}

Response fields

field description example
cell_ids The list of cells that will be monitored for new imagery. These are cells that intersect the AOI in the monitor request. The cell_id number convention is [utm zone]-[quadkey address]. "cell_ids": ["Z38-211131111020"]
monitor_id The unique identifier assigned when the monitor is created. "monitor_id": "578624547149604"
name The optional name given to the monitor. "name": "albuquerque"
description The optional description given to the monitor. "description": "monitor for new imagery Albuquerque, NM, USA"
account_id The ID for the account the monitor was created in. "account_id": "55842405131901"
user_id The ID for the user who created the monitor. "user_id": "c5f3a292-6d3d-4dae-84d0"
active Values are true/false. When a monitor is deactivated, this value will be "false", and the monitor will no longer watch for new matching imagery. "active": true
intersects If the AOI was submitted in WKT or GeoJSON geometry format, it will display here. If no "intersects" value was submitted, this value for this field will be "null". "intersects": "POLYGON ((-106.8 35.1,-106.4 35.1,-106.4 35.4,-106.8 35.4,-106.8 35.1))"
bbox If the AOI was submitted as a bbox, it will display here. If no bbox was submitted, the value for this field will be "null". "bbox": [44.663653, -6.042026, 44.853207, -5.901495]
query The query object displays the query fields and values the monitor uses to look for matching new matching imagery acquisitions. See examples in the "request" section above.
actions The actions object shows the settings for notifying the user when the monitor finds new matching imagery. See examples in the "request" section above.
created The date and time the monitor was created. "created": "2021-11-09T16:56:51Z"
links Links to additional information associated with the monitor. See links table.
response_timestamp The date and time the response was generated. "response_timestamp": "2021-11-09T16:56:51Z"
link description
self Information related to your user record.
history The match history for the monitor.
account Information about the account you are associated with.

View a monitor's match history

View the match history for a monitor.

GET /monitor/history/{monitor_id}/history
Example:

GET https://ard.maxar.com/api/v1/monitor/history/58630784888201494

Path parameters

parameter description example
monitor_id To view match history for a specific monitor, include the requested monitor ID in the path. 58630784888201494

Query parameters

All query parameters are optional. If no limit is set, a default of 10 results will be returned, starting with the most recent.

Match history response

The response returns an object for each imagery acquisition discovered by the monitor because it matched the criteria. The "created" date indicates the day the monitor found the matching acquisition. This is typically the same date the image was acquired by the satellite.

200 OK: Success

404: Monitor not found

Response example

{
    "data": [
        {
            "monitor_id": "5863093108873554704",
            "account_id": "5589150080369207736",
            "acquisition_id": "105001002986D100",
            "query_id": "Q5865654636534245594",
            "query_url": "https://ard.maxar.com/api/v1/metadata/query/Q5865654636534245594",
            "created": "2022-02-27T06:28:42Z"
        },
        {
            "monitor_id": "5863093108873554704",
            "account_id": "5589150080369207736",
            "acquisition_id": "105001002979F200",
            "query_id": "Q5864972603159854595",
            "query_url": "https://ard.maxar.com/api/v1/metadata/query/Q5864972603159854595",
            "created": "2022-02-26T07:53:37Z"
        },
        {
            "monitor_id": "5863093108873554704",
            "account_id": "5589150080369207736",
            "acquisition_id": "105001002979EF00",
            "query_id": "Q5864740705090812326",
            "query_url": "https://ard.maxar.com/api/v1/metadata/query/Q5864740705090812326",
            "created": "2022-02-26T00:12:53Z"
        }
    ],
    "has_more": false,
    "object": "list",
    "url": "https://ard.maxar.com/api/v1/monitor/history/5863093108873554704"
}

Response fields

field description example
monitor_id The ID for the monitor that made the match. "monitor_id": "5778229983415384..."
account_id The ID for the account the monitor was created in. account_id": "5584240513190185..."
acquisition_id The monitor found that this imagery acquisition matched the requested criteria. "acquisition_id": "3333333333"
select_id The select ID is created when the monitor finds a new acquisition and notifies the monitor creator that a match was made. This select ID can be used to order the acquisition. "select_id": "5593392884763461609"
created The date and time the monitor discovered the imagery acquisition. This is typically the same day the image is acquired by the satellite. "created": "2021-01-01T09:09:09Z"

Get a specific monitor

Get the details for a specific monitor.

GET /monitor/config/{monitor_id}

Example:

GET https://ard.maxar.com/api/v1/monitor/config/58630784888201494

Path parameters

parameter description example
monitor_id To view match history for a specific monitor, include the requested monitor ID in the path. 57862454714960...

Response

See the example and fields table for the POST create a monitor.

List monitors

GET /monitor

Lists the monitors you've created. The default request returns active monitors only. Append ?active_only=false to view both active and inactive monitors.

Example:

GET https://ard.maxar.com/api/v1/monitor?active_only=false

Query parameters

query param description example
filter Filter results that match values contained in the given key separated by a colon. Partial matches will also be returned. A request can include more than one "filter" field/value pair. created": "2021-01-01T09:09:09Z
limit The number of items to return in the response. This defaults to 10. limit=5
starting_after The token provided at the end of a paging request after which further responses will be returned, paging forward. starting_after={token string}
ending_before The token provided at the end of a paging request after which further responses will be returned, paging backward. ending_before={token string}

Response

Delete a Monitor

DEL /monitor/config/{monitor_id}

Making a DELETE request for a monitor deactivates the monitor. The "active" field will be set to false, and the monitor will not look for matching imagery. This request does not permanently delete the record for the monitor, but the monitor cannot be reactivated.

Example:

DEL https://ard.maxar.com/monitor/config/586307848882014940

Path parameters

parameter description example
monitor_id To view match history for a specific monitor, include the requested monitor ID in the path. 57862454714960...

Response

204 No Content: Success

404 Not Found: Monitor ID not found
Back to top