Check out the best practices for handling geometries to learn more about the different aspects to consider when working with geometries, including antimeridian crossings and pole coverings.

When querying, you can specify arbitrary geometries as an area of interest to filter by. Tilebox currently supports Polygon and MultiPolygon geometries as query filters.

​
Filtering by an area of interest

To filter by an area of interest, use either a Polygon or MultiPolygon geometry as the spatial extent parameter.

Here is how to query Sentinel-2 S2A_S2MSI2A data over Colorado for a certain day in April 2025.

from shapely import Polygon
from tilebox.datasets import Client

area = Polygon(  # area roughly covering the state of Colorado
    ((-109.05, 41.00), (-109.045, 37.0), (-102.05, 37.0), (-102.05, 41.00), (-109.05, 41.00)),
)

client = Client()
sentinel2_msi = client.dataset("open_data.copernicus.sentinel2_msi")
collection = sentinel2_msi.collection("S2A_S2MSI2A")
data = collection.query(
    temporal_extent=("2025-04-02", "2025-04-03"),
    spatial_extent=area,
)

​
Intersection mode

By default, the query will return all datapoints that intersect with the specified geometry. For certain use cases you might want to change this behavior and only return datapoints that are fully contained within the specified geometry. Tilebox supports this behavior by specifying a mode for the spatial filter.

mode: intersects

mode: contains

​
Intersects

The intersects mode is the default behavior of spatial queries. It matches all datapoints with geometries that intersect with the query geometry.

area = Polygon(  # area roughly covering the state of Colorado
    ((-109.05, 41.00), (-109.045, 37.0), (-102.05, 37.0), (-102.05, 41.00), (-109.05, 41.00)),
)

data = collection.query(
    temporal_extent=("2025-04-02", "2025-04-03"),
    # intersects is the default, so can also be omitted entirely
    spatial_extent={"geometry": area, "mode": "intersects"},
)
print(f"There are {data.sizes['time']} Sentinel-2A granules intersecting the area of Colorado on April 2nd, 2025")
Output
There are 27 Sentinel-2A granules intersecting the area of Colorado on April 2nd, 2025

​
Contains

area = Polygon(  # area roughly covering the state of Colorado
    ((-109.05, 41.00), (-109.045, 37.0), (-102.05, 37.0), (-102.05, 41.00), (-109.05, 41.00)),
)

data = collection.query(
    temporal_extent=("2025-04-01", "2025-05-02"),
    spatial_extent={"geometry": area, "mode": "contains"},
)
print(f"There are {data.sizes['time']} Sentinel-2A granules fully contained within the area of Colorado on April 2nd, 2025")
Output
There are 16 Sentinel-2A granules fully contained within the area of Colorado on April 2nd, 2025

​
Antimeridian Crossings

In many applications, geometries that cross the antimeridian cause issues. Since such geometries are common in satellite data, Tilebox does take extra care to handle them out of the box correctly, by building the necessary internal spatial index structures in a way that correctly handles antimeridian crossings and pole coverings.

To get accurate results also at query time, it’s recommend to use the spherical coordinate reference system for querying (which is the default), as it correctly handles the non-linearity introduced by the antimeridian in cartesian space.

Even if you stick to the spherical coordinate reference system when querying, it’s still recommended to follow the best practices for handling geometries. In doing so, you can ensure that no geometry related issues will arise even when interfacing with other libraries and tools that may not properly support non-linearities in geometries.

​
Coordinate reference system

Geometry intersection and containment checks can either be performed in a 3D Spherical coordinate system or in a standard 2D cartesian lat/lon coordinate system.

Spherical coordinate reference system

Cartesian coordinate reference system

​
Spherical

The spherical coordinate reference system is the default and recommended one to use. It correctly handles antimeridian crossings and is the most robust option, no matter how the datapoint geometries are cut along the antimeridian.

Irregardless of the coordinate reference system is used, it is always recommended to follow the best practices for handling antimeridian crossings as described in the Antimeridian Crossings section below.

When querying with the spherical coordinate reference system, Tilebox automatically converts all geometries to their x, y, z coordinates on the unit sphere and performs the intersection and containment checks in 3D.

area = Polygon(  # area roughly covering the state of Colorado
    ((-109.05, 41.00), (-109.045, 37.0), (-102.05, 37.0), (-102.05, 41.00), (-109.05, 41.00)),
)

data = collection.query(
    temporal_extent=("2025-04-01", "2025-05-02"),
    # spherical is the default, so can also be omitted entirely
    spatial_extent={"geometry": area, "coordinate_system": "spherical"},
)

​
Cartesian

Tilebox can also be configured to use a standard 2D cartesian lat/lon coordinate system for geometry intersection and containment checks as well. This can be done by specifying the cartesian coordinate reference system when querying.

area = Polygon(  # area roughly covering the state of Colorado
    ((-109.05, 41.00), (-109.045, 37.0), (-102.05, 37.0), (-102.05, 41.00), (-109.05, 41.00)),
)

data = collection.query(
    temporal_extent=("2025-04-01", "2025-05-02"),
    spatial_extent={"geometry": area, "coordinate_system": "cartesian"},
)

When using the cartesian coordinate system, antimeridian crossings may cause issues if datapoint geometries or the query geometry do not properly respect the antimeridian cut. Check out the Antimeridian Crossings section below for best practices to ensure correct results irregardless of the coordinate reference system used.