Image Search¶

Utilities for searching and retrieving Sentinel-2 imagery from Google Earth Engine.

Overview¶

The gee_acolite.utils.search module provides simplified functions for searching Sentinel-2 images in the GEE catalog, with filters for region of interest, time range, and specific tile.

Flow Diagram¶

flowchart TD A[Search Parameters] --> B{Search Type} B -->|search| C[Simple Search] B -->|search_list| D[Multi-date Search] B -->|search_with_cloud_proba| E[With Cloud Probability] C --> F[filterBounds ROI] D --> G[Multiple Date Ranges] E --> H[Join S2 + Cloud Probability] F --> I[filterDate] G --> J[First Image per Range] H --> K[Add Cloud Band] I --> L{Tile Filter?} J --> L K --> L L -->|Yes| M[filter MGRS_TILE] L -->|No| N[ee.ImageCollection] M --> N style A fill:#e1f5ff style N fill:#e1ffe1

Functions¶

search ¶

search(roi: Geometry, start: str, end: str, collection: str = 'S2_HARMONIZED', tile: Optional[str] = None) -> ImageCollection

Search for Sentinel-2 images in a region and time period.

Parameters:

Name	Type	Description	Default
`roi`	`Geometry`	Region of interest.	required
`start`	`str`	Start date in format 'YYYY-MM-DD'.	required
`end`	`str`	End date in format 'YYYY-MM-DD'.	required
`collection`	`str`	Sentinel-2 collection name (default: 'S2_HARMONIZED'). Options: 'S2_HARMONIZED', 'S2', 'S2_SR', 'S2_SR_HARMONIZED'.	`'S2_HARMONIZED'`
`tile`	`str`	Specific tile identifier to filter (e.g., 'T30SYJ').	`None`

Returns:

Type	Description
`ImageCollection`	Collection of matching Sentinel-2 images.

Source code in gee_acolite/utils/search.py

def search(roi : ee.Geometry, start : str, end : str, 
           collection : str = 'S2_HARMONIZED', tile : Optional[str] = None) -> ee.ImageCollection:
    """
    Search for Sentinel-2 images in a region and time period.

    Parameters
    ----------
    roi : ee.Geometry
        Region of interest.
    start : str
        Start date in format 'YYYY-MM-DD'.
    end : str
        End date in format 'YYYY-MM-DD'.
    collection : str, optional
        Sentinel-2 collection name (default: 'S2_HARMONIZED').
        Options: 'S2_HARMONIZED', 'S2', 'S2_SR', 'S2_SR_HARMONIZED'.
    tile : str, optional
        Specific tile identifier to filter (e.g., 'T30SYJ').

    Returns
    -------
    ee.ImageCollection
        Collection of matching Sentinel-2 images.
    """
    if tile is None:
        sentinel2_l1 = ee.ImageCollection(f'COPERNICUS/{collection}').filterBounds(roi).filterDate(start, end)
    else:
        sentinel2_l1 = ee.ImageCollection(f'COPERNICUS/{collection}').filterBounds(roi).filterDate(start, end).filter(ee.Filter.stringContains('PRODUCT_ID', tile))

    return sentinel2_l1

search_list ¶

search_list(roi: Geometry, starts: list[str], ends: list[str], collection: str = 'S2_HARMONIZED', tile: Optional[str] = None) -> ImageCollection

Search for multiple Sentinel-2 images using date pairs.

Retrieves the first image matching each date range. Useful for selecting specific acquisitions.

Parameters:

Name	Type	Description	Default
`roi`	`Geometry`	Region of interest.	required
`starts`	`list of str`	List of start dates in format 'YYYY-MM-DD'.	required
`ends`	`list of str`	List of end dates in format 'YYYY-MM-DD'.	required
`collection`	`str`	Sentinel-2 collection name (default: 'S2_HARMONIZED').	`'S2_HARMONIZED'`
`tile`	`str`	Specific tile identifier to filter.	`None`

Returns:

Type	Description
`ImageCollection`	Collection with first image from each date range.

Source code in gee_acolite/utils/search.py

def search_list(roi : ee.Geometry, starts : list[str], ends : list[str], 
                collection : str = 'S2_HARMONIZED', tile : Optional[str] = None) -> ee.ImageCollection:
    """
    Search for multiple Sentinel-2 images using date pairs.

    Retrieves the first image matching each date range. Useful for
    selecting specific acquisitions.

    Parameters
    ----------
    roi : ee.Geometry
        Region of interest.
    starts : list of str
        List of start dates in format 'YYYY-MM-DD'.
    ends : list of str
        List of end dates in format 'YYYY-MM-DD'.
    collection : str, optional
        Sentinel-2 collection name (default: 'S2_HARMONIZED').
    tile : str, optional
        Specific tile identifier to filter.

    Returns
    -------
    ee.ImageCollection
        Collection with first image from each date range.
    """
    return ee.ImageCollection.fromImages([search(roi, start, end, collection, tile).first() for start, end in zip(starts, ends)])

search_with_cloud_proba ¶

search_with_cloud_proba(roi: Geometry, start: str, end: str, collection: str = 'S2_HARMONIZED', tile: Optional[str] = None) -> ImageCollection

Search Sentinel-2 images and join with Cloud Probability data.

Retrieves Sentinel-2 images and joins them with the corresponding cloud probability data from COPERNICUS/S2_CLOUD_PROBABILITY.

Parameters:

Name	Type	Description	Default
`roi`	`Geometry`	Region of interest.	required
`start`	`str`	Start date in format 'YYYY-MM-DD'.	required
`end`	`str`	End date in format 'YYYY-MM-DD'.	required
`collection`	`str`	Sentinel-2 collection name (default: 'S2_HARMONIZED').	`'S2_HARMONIZED'`
`tile`	`str`	Specific tile identifier to filter.	`None`

Returns:

Type	Description
`ImageCollection`	Collection with Cloud Probability data joined.

Source code in gee_acolite/utils/search.py

def search_with_cloud_proba(roi : ee.Geometry, start : str, end : str, 
                            collection : str = 'S2_HARMONIZED', tile : Optional[str] = None) -> ee.ImageCollection:
    """
    Search Sentinel-2 images and join with Cloud Probability data.

    Retrieves Sentinel-2 images and joins them with the corresponding
    cloud probability data from COPERNICUS/S2_CLOUD_PROBABILITY.

    Parameters
    ----------
    roi : ee.Geometry
        Region of interest.
    start : str
        Start date in format 'YYYY-MM-DD'.
    end : str
        End date in format 'YYYY-MM-DD'.
    collection : str, optional
        Sentinel-2 collection name (default: 'S2_HARMONIZED').
    tile : str, optional
        Specific tile identifier to filter.

    Returns
    -------
    ee.ImageCollection
        Collection with Cloud Probability data joined.
    """
    s2_collection = search(roi, start, end, collection, tile)
    return join_s2_with_cloud_prob(s2_collection)

Available Sentinel-2 Collections¶

GEE Collection	Description	Use with gee_acolite
`S2_HARMONIZED`	L1C Harmonised (2015–present)	✅ Recommended
`S2`	L1C original (2015–2022)	⚠️ Deprecated
`S2_SR_HARMONIZED`	L2A Harmonised (already corrected)	❌ Not applicable
`S2_SR`	L2A original (already corrected)	❌ Not applicable

Recommended collection

Use S2_HARMONIZED for atmospheric correction with ACOLITE. It provides consistent L1C data across Sentinel-2A and 2B and is the actively maintained collection.

Usage Examples¶

Basic Search¶

import ee
from gee_acolite.utils.search import search

ee.Initialize(project='your-project-id')

roi = ee.Geometry.Rectangle([-0.5, 39.3, -0.1, 39.7])

images = search(
    roi=roi,
    start='2023-06-01',
    end='2023-06-30',
    collection='S2_HARMONIZED',
)

print(f'Images found: {images.size().getInfo()}')

Filter by Specific Tile¶

# Fix the MGRS tile to avoid duplicate coverage across adjacent tiles
images = search(
    roi=roi,
    start='2023-01-01',
    end='2023-12-31',
    tile='30SYJ',  # Valencia, Spain
)

Search for Specific Dates¶

from gee_acolite.utils.search import search_list

start_dates = ['2023-03-15', '2023-06-20', '2023-09-10']
end_dates   = ['2023-03-16', '2023-06-21', '2023-09-11']

specific_images = search_list(
    roi=roi,
    starts=start_dates,
    ends=end_dates,
    tile='30SYJ',
)

print(f'Images selected: {specific_images.size().getInfo()}')

Search with Cloud Probability¶

from gee_acolite.utils.search import search_with_cloud_proba

# Joins S2_HARMONIZED with the S2_CLOUD_PROBABILITY dataset
images = search_with_cloud_proba(
    roi=roi,
    start='2023-06-01',
    end='2023-06-30',
    tile='30SYJ',
)

# Images now carry a 'cloud_prob' property containing the cloud probability image

Cloud Masking Integration¶

sequenceDiagram participant User participant Search participant S2_L1C as S2_HARMONIZED participant S2_Cloud as S2_CLOUD_PROBABILITY participant Output User->>Search: search_with_cloud_proba(roi, dates) Search->>S2_L1C: filterBounds + filterDate Search->>S2_Cloud: filterBounds + filterDate Search->>Search: Join on system:index Search->>Output: ImageCollection with 'cloud_prob' property Output->>User: Images + Cloud Probability

Sentinel-2 Tile Identifiers¶

Sentinel-2 tiles follow the MGRS (Military Grid Reference System) naming convention:

Format: [UTM Zone][Latitude Band][100km Square]

Common examples:

Tile	Location
`30SYJ`	Valencia, Spain
`31TBE`	Barcelona, Spain
`29TNE`	Galicia, Spain
`30STJ`	Alicante, Spain

# Find the tile containing a point
def find_tile_at_point(lon, lat):
    point = ee.Geometry.Point([lon, lat])
    sample = (ee.ImageCollection('COPERNICUS/S2_HARMONIZED')
              .filterBounds(point)
              .first())
    return sample.get('MGRS_TILE').getInfo()

valencia_tile = find_tile_at_point(-0.376, 39.470)
print(f'Valencia tile: {valencia_tile}')  # 30SYJ

Pre-filtering by Cloud Cover¶

# Filter by metadata before running correction (saves getInfo() calls)
images = search(roi, '2023-06-01', '2023-06-30')
images = images.filter(ee.Filter.lt('CLOUDY_PIXEL_PERCENTAGE', 10))
print(f'Images with <10% clouds: {images.size().getInfo()}')

Image Search¶

Overview¶

Flow Diagram¶

Functions¶

search ¶

search_list ¶

search_with_cloud_proba ¶

Available Sentinel-2 Collections¶

Usage Examples¶

Basic Search¶

Filter by Specific Tile¶

Search for Specific Dates¶

Search with Cloud Probability¶

Cloud Masking Integration¶

Sentinel-2 Tile Identifiers¶

Pre-filtering by Cloud Cover¶

References¶