Skip to content

Area of Interest (AOI) Examples and Guidelines

Last updated: April 4, 2022

Overview

Defining an Area of Interest (AOI) is an important part of the ARD imagery selection and ordering process. When selecting imagery based on a set of query criteria, the AOI is a required field and a key component of the selection process. When selecting imagery by one or more acquisition IDs, the AOI is optional, but is useful in limiting ordered imagery to only the geographic area you need.

AOIs can be combined with temporal fields to request imagery in an area over a series of time. See Temporal Queries for more information.

AOI formats

Maxar ARD accepts the following formats for defining an AOI:

  • a WKT polygon or multipolygon

  • a GeoJSON polygon or multipolygon geometry

  • a GeoJSON feature collection

  • Bounding box (bbox)

Examples are provided later in this document.

AOI input fields

To select imagery by query criteria, your request must include an AOI. When selecting imagery by acquisition ID, you have the option to submit an AOI to limit the selection results.

When ordering imagery, if a select ID is used to order, an additional AOI is not accepted. If an order is placed using Acquisitions, you have the option to submit an AOI with the order request.

There are two fields that can be used to submit an AOI.

field description
intersects Accepts a WKT or GeoJSON polygon, multipolygon geometry, or feature collection.
bbox Accepts a bounding box in the format [minx, miny, maxx, maxy].

Choose either the intersects or the bbox field to submit an AOI. If both are submitted, the select or order request will return an error.

AOI rules and validation

  • An AOI must be at least 1 square kilometer (sq km).

  • An individual polygon within a multipolygon must be at least 1 sq km.

  • Only 2-dimensional geometries are accepted. A 3-D geometry is not a valid input.

  • The maximum number of vertices allowed in a polygon or multipolygon is 1000.

  • The rotated rectangle containing the polygon must be at least 250m wide.

  • A polygon cannot cross the anti-meridian, or +180°/-180° longitude. An AOI that crosses the anti-meridian should be formatted as a multipolygon that includes a polygon for each side of the line.

  • When selecting or ordering by acquisition IDs, the geographic boundaries of the acquisition must intersect with the AOI.

  • The AOI must be within the boundaries of Maxar's Digital Elevation Model (DEM). This excludes Greenland, the Arctic, and Antarctica. See About ARD for more information about DEM coverage.

  • The "intersects" field must contain a valid polygon or multipolygon geometry in WKT or GeoJSON format.

  • Specifically when ordering HD imagery, there are some AOIs that will be unable to return HD imagery. These AOIs are "restricted". If you try to order HD imagery in these AOIs, you will receive this error message.

The area of the requested image must intersect with the AOI

For imagery to be selected or ordered, the area of the requested image must intersect with the AOI. If no data from the image intersects with the AOI, the "select" response will show 0 estimated usage. The "order" request will result in an error.

One or more requested acquisitions don't intersect the AOI

Imagery can be selected or ordered by submitting one or more acquisition IDs and an AOI. If the footprint of the requested acquisition does not intersect the AOI, the image will not be selected or ordered.

Mismatch between estimated and actual image footprints

The imagery selection and order validation steps use an estimated image footprint, based on metadata. The estimated footprint and the actual footprint can be slightly different. Most of the time, the difference doesn't impact the ordering process.

Occasionally, when only the edge of the estimated footprint intersects with the AOI, the shift is enough that the actual footprint does not intersect. In this scenario, the imagery would pass select and order validation, but the non-intersecting tile or tiles cannot be ordered. When this occurs, the intersecting image tiles in the order are delivered, and a report is generated that lists the non-intersecting tiles that could not be delivered.

Examples

Example with polygon AOI in WKT format

{
    "datetime": "2020-07-01T00:00:00Z/2021-01-25T00:00:00Z",
    "intersects": "POLYGON ((-106.8 35.1,-106.4 35.1,-106.4 35.4,-106.8 35.4,-106.8 35.1))",
    "stack_depth": 3,
    "query": {
        "platform": {
            "eq": "geoeye-01"
        },
        "aoi:cloud_free_percentage": {
            "gte": 95.0
        },
        "aoi:data_percentage": {
            "gte": 75.0
        }
    }

}

Example with multipolygon AOI in WKT format

{
    "datetime": "2020-07-01T00:00:00Z/2021-01-25T00:00:00Z",
    "intersects": "MULTIPOLYGON (((-67.845741 -56.01511,-67.845804 -55.991597,-67.845902 -55.955949,-67.846019 -55.920264,-67.846131 -55.884553,-67.8462006832504 -55.8710455233253,-68.294492 -55.869099,-68.294492 -56.020506468297,-68.032065 -56.032349,-68.0320439637212 -56.0202743490237,-67.845741 -56.01511)),((-66.774902 -56.0292484707944,-66.774902 -55.869099,-67.8394048188919 -55.8710624958558,-67.84006 -55.905257,-67.840373 -55.95711,-67.840379 -55.958173,-67.6648552070019 -55.9445196160331,-67.664849 -55.97695,-67.664845 -56.017043,-67.3940726885931 -56.0148988893146,-67.394058 -56.018891,-67.2718149443154 -56.0157802627885,-67.271887 -56.035121,-67.2131748877145 -56.0306555305853,-67.213162 -56.032798,-66.90581 -56.041776,-66.905762 -56.032921,-66.9056911682216 -56.0204715039239,-66.774902 -56.0292484707944)))",
    "stack_depth": 3,
    "query": {
        "platform": {
            "eq": "geoeye-01"
        },
        "aoi:cloud_free_percentage": {
            "gte": 95.0
        },
        "aoi:data_percentage": {
            "gte": 75.0
        }
    }

}

Example with GeoJSON geometry

This example shows a GeoJSON geometry as the "intersects" field value.

{
    "datetime": "2020-07-01T00:00:00Z/2021-01-25T00:00:00Z",
    "intersects": {
            "type": "Polygon",
            "coordinates": [
                [
                    [-106.8, 35.1],
                    [-106.4, 35.1],
                    [-106.4, 35.4],
                    [-106.8, 35.4],
                    [-106.8, 35.1]
                ]
            ]
        },
    "stack_depth": 3,
    "query": {
        "aoi:cloud_free_percentage": {
            "gte": 95.0
        },
        "aoi:data_percentage": {
            "gte": 75.0
        }
    }

}

Example with bounding box AOI

{
    "datetime": "2020-07-01T00:00:00Z/2021-01-25T00:00:00Z",
    "image_age_category": ["fresh", "standard"],
    "bbox": [-106.8, 35.1, -106.4, 35.4],
    "stack_depth": 3,
    "query": {
        "platform": {
            "eq": "worldview-02"
        },
        "aoi:cloud_free_percentage": {
            "gte": 95.0
        },
        "aoi:data_percentage": {
            "gte": 75.0
        }
    }

}

Errors

Error: Polygon or total AOI does not meet minimum size requirement

  • The total AOI (polygon, multipolygon, bbox) must be at least 1 sq km.

  • Each polygon within a multipolygon must be at least 1 sq km.

{
    "message": "Bad Request: Problem with intersects/bbox field: Polygons must be at least 1 sqkm; found one with area of 0.67 sqkm.",
    "code": "invalid_aoi",
    "type": "invalid_request_error"
}
Error: Polygon does not meet the minimum width requirement
{
    "message": "Bad Request: Polygons must be wider than 250 meters; found one with width of 209.82 meters.",
    "code": "invalid_aoi",
    "type": "invalid_request_error"
}
Error: The AOI geometry has more than 1000 vertices.
{
    "message": "Bad Request: Too many vertices in geometry (1165; max 1000)",
    "code": "invalid_aoi",
    "type": "invalid_request_error"
}
Error: The geometry provided in the intersects field is not a polygon or multipolygon.
{
    "message": "Bad Request: AOI must be a polygon or multi-polygon",
    "code": "invalid_aoi",
    "type": "invalid_request_error"
}
Error: The geometry in the intersects field must be properly formatted.
{
    "message": "Bad Request: Problem with intersects/bbox field: Geometry must be properly formatted WKT or GeoJSON.",
    "code": "invalid_aoi",
    "type": "invalid_request_error"
}

Check the formatting of your geometry. If you're using a GeoJSON input, make sure it's a geometry, not a feature collection. Feature collections are not a valid input.

Error: AOI falls outside of Maxar's DEM boundaries

Select

This will cause the "select" request to return a status of "FAILED" with the following message:

"state": "FAILED",
"error_message": {
  "Error": "Covering Cells",
  "Cause": "Something went wrong while determining the cells covering your area: AOI does not intersect the Digital Elevation Model (DEM)"
}

Order

{
    "message": "Bad Request: Acquisition 104001005E5D8700 cannot be ordered because it falls within a geographic location not covered by our Digital Elevation Model (DEM)",
    "code": "invalid_parameters",
    "type": "invalid_request_error"
}
Error: The acquisition IDs and AOI provided do not intersect.

Select Imagery: The request will succeed, but will return no imagery.

Order Imagery: An order request will produce the following error:

{
    "message": "Bad Request: Acquisition 10300100B3841C00 cannot be ordered because it is outside the bounds of the provided aoi",
    "code": "invalid_parameters",
    "type": "invalid_request_error"
}
Error: Request includes an AOI in the intersects field and the bbox field.
{
    "message": "Bad Request: 'intersects' and 'bbox' cannot be used in the same request",
    "code": "invalid_parameters",
    "type": "invalid_request_error"
}
Back to top