Monitor Resource¶

Last updated: December 1, 2022

Monitor¶

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

Request types¶

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.
monitor_type	optional	The type of monitor to create, must be one of ["standard", "single-match".]
dry_run	optional	Set `dry_run` to true to validate your monitor request before submitting. the default value is false.	`"dry_run": false`
expires	optional	Set a date for the monitor to be deactivated.	Must be formatted as an ISO-8601 date, YYYY-MM-DD.
datetime	optional	Specify a date, date and time, date range, or open-ended date range for matching imagery. Must be in ISO-8601 8601 format, and it must be in the future. If no start date is supplied, the monitor starts at the date and time of submission. If no end date is supplied, the monitor ends when the `expires` date is reached or when the account's original contract end date has passed.	"datetime": "2023-03-01T09:00:00Z/.."
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 Request: Create a Monitor¶

{
    "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": "2022-12-15",
    "datetime": "2022-10-25T09:00:00Z/2023-10-26T13:00:00Z",
    "actions": [{
        "action": "notify",
        "notifications": [{
            "type": "email",
            "address": "sheabarnes@myemail.com"
        }]
    }]
}

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

Monitor Response¶

Example response: Standard monitor¶

{
    "monitor": {
        "cell_ids": [
            "Z13-031133231111",
            "Z13-031133231113",
            "Z13-031133231131",
            "Z13-031133231133",
            "Z13-031133231311",
            "Z13-031133231313",
            "Z13-031133231331",
            "Z13-031133320000"      
        ],
        "monitor_id": "999909310887359999",
        "name": "albuquerque",
        "description": "monitor for new imagery Albuquerque, NM, USA",
        "account_id": "55891500803692NNNN",
        "user_id": "967f33a5-1d80-4a74-9334-nnnn",
        "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"
}

Example Response: Single-match monitor¶

{
    "monitor": {
        "cell_ids": [
            "Z13-031133231111",
            "Z13-031133231113",
            "Z13-031133231131",
            "Z13-031133231133",
            "Z13-031133231311",
            "Z13-031133231313",
            "Z13-031133231331",
            "Z13-031133320000",
            "Z13-031133320001",
            "Z13-031133320002",
            "Z13-031133320003",
            "Z13-031133320010",
            "Z13-031133320011",
            "Z13-031133320012",        
        ],
        "monitor_id": "6061084311638223651",
        "name": "albuquerque",
        "description": "monitor for new seasonal 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@myemail.com"
                    }
                ]
            }
        ],
        "created": "2022-11-23T21:52:34Z",
        "remaining_aoi": "{\"type\": \"Polygon\", \"coordinates\": [[[-106.4, 35.1], [-106.4, 35.4], [-106.8, 35.4], [-106.8, 35.1], [-106.4, 35.1]]]}",
        "remaining_cell_ids": [
            "Z13-031133231111",
            "Z13-031133231113",
            "Z13-031133231131",
            "Z13-031133231133",
            "Z13-031133231311",
            "Z13-031133231313",
            "Z13-031133231331"          
        ],
        "monitor_type": "single-match",
        "percent_remaining": 50,
        "expires": "2023-12-15",
        "datetime": "2022-10-25T09:00:00Z/2023-10-26T13:00:00Z"
    },
    "links": {
        "self": "https://ard-dev.maxar.com/api/v1/monitor/config/6061084311638223651",
        "history": "https://ard-dev.maxar.com/api/v1/monitor/history/6061084311638223651",
        "account": "https://ard-dev.maxar.com/api/v1/admin-main/account/5589150080369207736"
    },
    "response_timestamp": "2022-11-23T21:52:34Z"
}

Response fields¶

The following fields are returned in a response to either a standard or single-match monitor type:

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"
tasking_id	If the monitor was created by a tasking request, the corresponding tasking ID be included in the response.	"tasking_id": "7777040499"
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"
monitor_type	Allowed monitor types are `single-match` and `standard`.	"monitor_type": "single-match"
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"

Additional fields in a single-match monitor response:¶

field	description	example
remaining_aoi	The coordinates for the remaining area that has not been fulfilled with an imagery match yet.
remaining_cell_ids	The remaining cells that have not been fulfilled with an imagery match.
percent_remaining	The percentage of the AOI that has not been matched yet.

If the single-match monitor was generated by a tasking request, the tasking_id will be included in the response.

Links table¶

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