Monitoring an Area

Overview

The Monitoring API allows you to create a monitor without auto-ordering. Such a monitor only notifies you when imagery matches your monitor's match criteria. This type of monitor allows you to parse imagery and selectively order individual or multiple images.

Supported requests

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

Request Type	Path	Description
List Sources	GET /monitoring/v1/sources/{namespace}/{source_name}	Lists all currently available sources for monitoring.
Create a monitor	POST /monitoring/v1/monitors	Creates a monitor to watch for new imagery within an AOI that matches specified criteria.
List Monitors	GET /monitoring/v1/monitors	Retrieves a list of monitor configurations which the user has access to.
Get specific monitor	GET /monitoring/v1/monitors/{monitor_id}	Retrieves the single monitor configuration for the submitted `monitor_id`.
Update an existing monitor	PATCH /monitoring/v1/monitors/{monitor_id}	Updates an existing monitor.
Toggle monitor	POST /monitoring/v1/monitors/{monitor_id}/{action}	Toggles whether a monitor is enabled or disabled.
List monitor events	GET /monitoring/v1/monitors/{monitor_id}/events	Retrieves a list of events for a specific monitor.
List source events	GET /monitoring/v1/sources/{namespace}/{source_name}/events/{events_id}	Retrieves a list of events for a specific source.

Constructing a monitor

This document describes the parts of the monitoring creation process that are applicable for all content types. For specific auto-ordering functionality, review the other documents in this directory.

Parameter	Required	Description	Example
`source`	required	The source in which to look for new imagery.	`"discovery/catalog"`
`start_datetime`	optional	The starting time of your monitor, in ISO format.	`"2023-02-18T00:00:00+00:00"`
`end_datetime`	optional	The ending time of your monitor, in ISO format.	`"2023-04-18T00:00:00+00:00"`
`description`	optional	A description of your monitor.	`"Albuquerque holiday monitor"`
`aoi_geojson`	required	A geoJSON array of the coordinates for your monitor.	See the AOI section below.
`erode_area`	optional	Determines whether the AOI of your monitor will erode as matches occur.	`"true"`
`erosion_complete_threshold_pct`	optional	The percentage of area within your AOI that needs to erode for your monitor to be considered complete. The default value is 100	`"80"`
`match_criteria`	required	The criteria an incoming image needs to match to be considered as part of your monitor.	See the match criteria section below.
`order_when_complete`	optional	Determines whether a monitor delays any auto-ordering until the area of your monitor fully erodes or falls below the `erosion_complete_threshold_pct` value. The default value is `false`	`"true"`
`monitor_notifications`	optional	Where notifications of events will be sent to for your monitor.	See the notifications section below.
`metadata`	optional	Supplemental information to store with your monitor.	`"245681782"`

Sources

Monitors can be set to watch for imagery appearing in different sources. For a full list of sources and their additional parameters, see our Sources documentation.

Set a monitor date range (optional)

To set a date range for your monitor, add the "start_datetime": and/or "end_datetime": field with an ISO formatted date to your request. For example, "2023-02-18T00:00:00+00:00" or "2024-03-08T20:52:32Z". If no "start_datetime": is set, the monitor will start when the request is processed. If no "end_datetime": is set, the monitor will run until canceled by the owner.

Your start and end times must be input as zulu time following ISO 8601 standards with UTC offsets. If you do not add any modifiers after your zulu time, local time will be assumed. For example, an input of "2023-04-7T4:00:00-4:00" will create a monitor beginning on April 7th, 2023 at midnight Eastern Daylight Time.

Describe your monitor (optional)

You can give your monitor a description to help identify it later in a monitor list or a match notification.

Define your Area of Interest (AOI) (required)

Monitors require an AOI in GeoJSON geometry format.

Example AOI

"aoi_geojson": {
        "type": "Polygon",
        "coordinates": [
            [
                [-106.8, 35.1],
				[-106.4, 35.1],
				[-106.4, 35.4],
				[-106.8, 35.4],
				[-106.8, 35.1]
            ]
        ]
    },

AOI erosion (boolean, optional)

If a monitor is set with "erode_area": true then the the matching image's area will be subtracted from your monitor's AOI, and your monitor will be updated with the reduced AOI. New imagery over eroded portions of the AOI will not be registered as matches. If your AOI has been eroded beyond the erosion_complete_threshold_pct, then your monitor is automatically disabled. If order_when_complete is true, the system will wait to place any orders until after the monitor has surpassed your erosion_complete_threshold_pct value. If false, the system will place orders as matches occur.

As an additional option, you can make your monitor auto-order imagery only when your total AOI falls to 0 or below your erosion_complete_threshold_pct value by setting the order_when_complete object to "true".

Include additional matching criteria (optional)

You can include additional matching criteria to further filter your monitor results. You can filter results by cloud free percentage, sun elevation, off-nadir angle, and more. Below is table with all current match criteria filters. A list of available fields may also be found by making a request to the GET Source endpoint for the configured Source.

operation	description	example
`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}`
`gt`	The field value is greater than the filter value.	`"eo:cloud_cover": {"gt": 90}`
`gte`	The field value is greater than or equal to the filter value.	`"eo:cloud_cover": {"gte": 90}`
`eq`	The field value is equal to the filter value.	`"platform": {"eq": "worldview-02"}`
`ne`	The field value is not equal to the filter value.	`"platform": {"ne": "geoeye-01"}`
`exists`	The named field exists or not in the record, depending on the supplied value.	To include records where a field named `demo-field` exists: `"demo-field": {"exists": true}`. To include records where a field named `missing-field` does not exist: `"missing-field": {"exists": false}`.
`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"}`
`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": "VNIR"}`
`in`	The field value is one of the listed filter values.	`"platform": {"in": ["geoeye-01", "worldview-02"]}`
`not-in`	The field value is not one of the listed filter values.	`"platform": {"not-in": ["geoeye-01", "worldview-02"]}`
`begins-with`	The field value has the filter value as the start of the value.	`"platform": {"begins-with": "worldview"}`
`between`	The field value is between the filter values, inclusive (synonym for `range`).	`"view:azimuth": {"between": [90, 270]}`
`range`	The field value is between the filter values, inclusive (synonym for `between`).	`"view:azimuth": {"range": [90, 270]}`
`later-than`	The field value is a date occurring after the filter value date. This field can also handle natural language expressions like "1 day ago" and "2 hours ago".	`"datetime": {"later-than": "1 day ago"}`

Dynamic match criteria fields (optional)

Fields that provide useful spatial calculations over the supplied AOI are dynamically added to all events. Use the fields described below to add criteria for cloud cover and event coverage within the AOI.

field	description
`aoi:coverage_pct`	The percentage of the event's geometry that covers the monitor AOI.
`aoi:coverage_sqkm`	The area in square kilometers of the event's geometry that covers the monitor AOI.
`aoi:cloud_coverage_pct`	The percentage of the AOI covered with clouds.

Notifications

Notifications can be configured to send messages to different outlets when the monitor finds a matching event. Multiple notifications can be specified if needed. These notification objects share the same structure as ordering notifications, but do not have a level property.

Example notifications configuration:

"monitor_notifications": [
  {
    "type": "email",
    "target": "username@myemail.com"
  },
  {
    "type": "SNS",
    "target": "arn:aws:sns:us-east-2:123456789012:YourTopic"
  },
]

For more detals on notification options, see Monitoring Notifications.

Example API requests

Sources

For a list of all available sources, review our Sources guide.

Example:

GET https://api.maxar.com/monitoring/v1/sources/discovery/catalog

Create a monitor

Below is an example for a standard monitor request without auto-ordering.

Example standard monitoring request

{
	"source": "discovery/catalog",
	"start_datetime": "ISO formatted date/time",
	"end_datetime": "ISO formatted date/time",
	"description": "description goes here",
	"aoi_geojson": {
		"type": "Polygon",
		"coordinates": [
            [
                [-106.8, 35.1],
				[-106.4, 35.1],
				[-106.4, 35.4],
				[-106.8, 35.4],
				[-106.8, 35.1]
            ]
        ]
	},
	"match_criteria": {
		"platform": {
			"in": ["worldview-03", "worldview-02"]
		},
		"eo:cloud_cover": {
			"lt": 75
		},
		"aoi:coverage_sqkm": {
			"gte": 1
		}
	},
    "erode_area": true,
	"monitor_notifications": [{
		"type": "email",
		"target": "username@myemail.com"
	}]
}

Updating an existing monitor

This request requires a monitor ID parameter as well as a json file. The json file only needs to have the field and updated value(s) for the specific fields that should be updated.

field	description	data type	example
`"description"`	A description of your monitor.	String or null	`"Monitor of Albuquerque"`
`"start_datetime"`	The starting time of your monitor	ISO formatted datetime string	`"2023-06-18T00:00:00+00:00"`
`"end_datetime"`	The starting time of your monitor	ISO formatted datetime string	`"2023-06-20T00:00:00+00:00"`
`"monitor_notifications"`	Where you would like notifications to be sent.	Array or null	`[{"type": "email", "target": "user@example.com"}]`
`"order_templates"`	Where you would like any auto-ordered imagery to be delivered.	Array or null	`[{"pipeline": "discovery/catalog", "template": {"settings": pipeline settings template goes here }}}]`
`"metadata"`	Supplemental information stored with your monitor.	Object or null	`null`

Example updating a monitor request

{
    "description": "new description",
}

This example updates the description of a monitor, as well as disables the monitor. You may also enable or disable your monitor by submit a post request with your monitor ID followed by disable or enable.

Note: Any updating of a monitor can only be done before your monitor's end_datetime.

Listing monitors

There are a variety of parameters, all of which are optional, to include to focus your monitor search:

parameter	description
`limit`	The number of items to return in this response. The default is 10.
`starting_after`	The token (base-64-encoded key) after which further responses will be returned, paging forward.
`ending_before`	The token (base-64-encoded key) after which further responses will be returned, paging backward.
`filter`	Filter results that match values contained in the given key separated by a colon. These are not exact matches, so filtering on a value of `string:"bla"` will return all `string:"bla"` along with `string:"blah"`.This field may be repeated if multiple filters are desired.
`sort`	Indicates sort order. The default is ascending alphabetical by name `asc`.

Examples

To filter out disabled monitors use a filter on the enabled field:

GET https://api.maxar.com/monitoring/v1/monitors?limit=2&filter=enabled:true

Metadata fields can be accessed through dotted notation. This request uses multiple filters to search for monitors that are enabled and have a project_name of Sunnyvale:

GET https://api.maxar.com/monitoring/v1/monitors?limit=2&filter=enabled:true&filter=metadata.project_name:Sunnyvale

Listing monitor events

This request has the same optional parameters as the list monitors query.

Example

GET https://api.maxar.com/monitoring/v1/monitors/123123123123123/events

Get specific monitor

The only parameter in this request is the monitor_id value of the monitor you wish to view information on. This parameter is required.

Example

GET https://api.maxar.com/monitoring/v1/monitors/1234123412341234

Overview​

Supported requests​

Constructing a monitor​

Sources​

Set a monitor date range (optional)​

Describe your monitor (optional)​

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

AOI erosion (boolean, optional)​

Include additional matching criteria (optional)​

Dynamic match criteria fields (optional)​

Notifications​

Example API requests​

Sources​

Example:​

Create a monitor​

Updating an existing monitor​

Listing monitors​

Examples​

Listing monitor events​

Example​

Get specific monitor​

Example​

Overview

Supported requests

Constructing a monitor

Sources

Set a monitor date range (optional)

Describe your monitor (optional)

Define your Area of Interest (AOI) (required)

AOI erosion (boolean, optional)

Include additional matching criteria (optional)

Dynamic match criteria fields (optional)

Notifications

Example API requests

Sources

Example:

Create a monitor

Updating an existing monitor

Listing monitors

Examples

Listing monitor events

Example

Get specific monitor

Example