Skip to content

Search Types

Overview

The sat_download.data_types.search module defines the data structures used to specify search criteria and represent search results.

API Reference

SatelliteImage

SatelliteImage dataclass 

SatelliteImage(
    uuid: str,
    date: str,
    sensor: str,
    brother: str,
    identifier: str,
    filename: str,
    tile: str,
)

Class representing the metadata of a satellite image.

This class stores standardized metadata about satellite imagery from different sources like Sentinel and Landsat for consistent processing.

Attributes:

Name Type Description
uuid str

Unique identifier for the image
date str

Acquisition date of the image in format 'YYYYMMDD'
sensor str

Sensor or satellite platform name (e.g., 'Sentinel-2', 'Landsat-8')
brother str

Satellite constellation member identifier (e.g., 'A' for Sentinel-2A)
identifier str

Combined satellite and brother identifier (e.g., 'Sentinel-2A')
filename str

Output filename for downloaded image
tile str

Tile or path/row identifier for the image
Notes

The structure of attributes is designed to work across different satellite data providers with a consistent interface.

SearchFilters

SearchFilters dataclass 

SearchFilters(
    collection: str,
    start_date: str,
    end_date: str,
    processing_level: str | None = None,
    geometry: str | None = None,
    tile_id: str | None = None,
    contains: List[str] | None = None,
)

Class for specifying search filters for satellite imagery.

This class provides a standardized way to specify search criteria across different satellite data providers and APIs.

Parameters:

Name Type Description Default
collection str

Collection identifier (e.g., 'SENTINEL-2', 'landsat_ot_c2_l1')

 required
start_date str

Start date for the search in format 'YYYY-MM-DD'

 required
end_date str

End date for the search in format 'YYYY-MM-DD'

 required
processing_level str

Processing level filter (e.g., 'L1C', 'L2A')

 None
geometry str

WKT geometry string for spatial filtering (e.g., 'POINT(lon lat)')

 None
tile_id str

Specific tile identifier to filter by

 None

Examples:

>>> filters = SearchFilters(
...     collection="SENTINEL-2",
...     processing_level="L1C",
...     start_date="2024-10-01",
...     end_date="2024-10-31",
...     tile_id="30TWM",
... )
>>> filters.is_set('geometry')
False

Functions

is_set 

is_set(value: str) -> bool

Check if a filter attribute is set (not None).

Parameters:

Name Type Description Default
value str

The name of the attribute to check

 required

Returns:

Type Description
bool

True if the attribute exists and is not None, False otherwise
Source code in sat_download\data_types\search.py 
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
def is_set(self, value : str) -> bool:
    """
    Check if a filter attribute is set (not None).

    Parameters
    ----------
    value : str
        The name of the attribute to check

    Returns
    -------
    bool
        True if the attribute exists and is not None, False otherwise
    """
    return self.__dict__.get(value, None) is not None

SearchResults

SearchResults module-attribute 

SearchResults = Dict[str, SatelliteImage]

Type alias representing search results from satellite APIs.

A dictionary mapping product IDs (keys) to SatelliteImage objects (values).

Usage Examples

Creating SearchFilters

from sat_download.data_types.search import SearchFilters
from sat_download.enums import COLLECTIONS

# Minimal filters (required fields only)
filters = SearchFilters(
    collection=COLLECTIONS.SENTINEL_2.value,
    start_date="2024-01-01",
    end_date="2024-01-31"
)

# Full filters
filters = SearchFilters(
    collection=COLLECTIONS.SENTINEL_2.value,
    start_date="2024-01-01",
    end_date="2024-01-31",
    processing_level="L2A",
    geometry="POINT(-3.7 40.4)",
    tile_id="30TWM",
    contains=["MSIL2A"]
)

# Check if a filter is set
if filters.is_set('tile_id'):
    print(f"Searching for tile: {filters.tile_id}")

Working with SatelliteImage

from sat_download.data_types.search import SatelliteImage

# Images are typically created by the factory
# but can be created manually for testing
image = SatelliteImage(
    uuid="20240115_S2A",
    date="20240115",
    sensor="Sentinel-2",
    brother="A",
    identifier="Sentinel-2A",
    filename="S2A_MSIL2A_20240115T105421.zip",
    tile="30TWM"
)

print(f"Sensor: {image.sensor}")
print(f"Date: {image.date}")
print(f"Tile: {image.tile}")
print(f"File: {image.filename}")

Working with SearchResults

from sat_download.api.odata import ODataAPI
from sat_download.data_types.search import SearchFilters, SearchResults

api = ODataAPI(username="user", password="pass")
filters = SearchFilters(...)

# Search returns SearchResults (Dict[str, SatelliteImage])
results: SearchResults = api.search(filters)

# Iterate over results
for product_id, image in results.items():
    print(f"{product_id}: {image.filename}")

# Get number of results
print(f"Found {len(results)} images")

# Check if results exist
if results:
    first_id = list(results.keys())[0]
    first_image = results[first_id]

Filter Reference

Required Fields

Field Type Description
collection str Collection identifier from COLLECTIONS enum
start_date str Search start date (YYYY-MM-DD format)
end_date str Search end date (YYYY-MM-DD format)

Optional Fields

Field Type Default Description
processing_level str \| None None Processing level (L1C, L2A, T1, T2)
geometry str \| None None WKT geometry string
tile_id str \| None None Tile/path-row identifier
contains List[str] \| None None Strings to filter by name

Geometry Formats

The geometry field accepts WKT (Well-Known Text) format:

# Point
geometry = "POINT(-3.7037902 40.4167754)"

# Polygon (rectangle)
geometry = "POLYGON((-4 40, -3 40, -3 41, -4 41, -4 40))"

# Polygon (complex shape)
geometry = "POLYGON((-3.8 40.3, -3.6 40.3, -3.6 40.5, -3.7 40.6, -3.8 40.5, -3.8 40.3))"

References