The geometry filter lets you search for imagery that covers your area of interest (AOI), and control how an item footprint must relate to that AOI. The Data API and the Subscriptions API both support it.

Data API

The Data API GeometryFilter searches for items with a footprint geometry that intersects the geometry you specify.

The filter supports Point, MultiPoint, LineString, MultiLineString, Polygon, and MultiPolygon GeoJSON objects. For best results, the geometry should meet the OpenGIS Simple Features Interface Specification requirements. If you supply an invalid GeoJSON object, the API attempts to correct the geometry and returns matching search results.

An optional relation parameter sets the geometry boolean operation. It takes one of the following values:

• intersects (default): Returns items whose footprint geometry partially or fully overlaps the AOI.
• contains: Returns items where the footprint geometry fully encloses the AOI.
• disjoint: Returns items whose footprint geometry does not intersect the AOI in any way.
• within: Returns items whose entire footprint geometry is contained within the AOI.

Subscriptions API

The Subscriptions API geometry_relation parameter sets the relationship between the subscription geometry and a matched item geometry. This parameter is an extension of the Data API GeometryFilter. It takes one of the following values:

• intersects (default): Returns items whose footprint geometry partially or fully overlaps the subscription geometry.
• contains: Returns items where the footprint geometry fully encloses the subscription geometry.
• within: Returns items whose entire footprint geometry is contained within the subscription geometry.

Note: The Subscriptions API does not support the disjoint relation.

Choosing a relation

intersects is the default. If you do not set geometry_relation on a subscription, the Subscriptions API applies it automatically. It casts the widest net of the three values and returns any scene that touches any part of the AOI, even when the scene covers only part of it.

Use intersects when you want maximum coverage and partial scenes at the edges of the AOI are acceptable. For workflows where only fully covered scenes work — for example, a pipeline that requires complete scene coverage — use contains instead.

Code example

catalog_source = catalog_source(
    item_types=["PSScene"],
    asset_types=["ortho_analytic_4b"],
    start_time=datetime.fromisoformat("2024-11-05T00:00:00Z"),
    geometry=aoi_geojson,
    geometry_relation="intersects"  # default; can be omitted
)