Skip to content

Base API Module

Overview

The sat_download.api.base module provides the abstract base class SatelliteAPI that defines the contract all provider API implementations must fulfill.

API Reference

SatelliteAPI 

SatelliteAPI(username: str, password: str)

Bases: ABC

Abstract base class for satellite data API clients.

This class defines the common interface for interacting with different satellite data provider APIs, such as Copernicus Data Space and USGS.

Parameters:

Name Type Description Default
username str

Username or API key for authentication with the satellite data provider

 required
password str

Password or secret for authentication with the satellite data provider

 required
Notes

Concrete implementations should handle the specific authentication mechanisms and API endpoints required by each satellite data provider.

See Also

sat_download.api.odata.ODataAPI : Implementation for Copernicus Data Space API sat_download.api.usgs.USGSAPI : Implementation for USGS Earth Explorer API

Source code in sat_download\api\base.py 
31
32
33
def __init__(self, username : str, password : str) -> None:
    self.username = username
    self.password = password

Functions

search abstractmethod 

search(filters: SearchFilters) -> SearchResults

Search for satellite imagery using specified filters.

Parameters:

Name Type Description Default
filters SearchFilters

The search filters to apply to the search

 required

Returns:

Type Description
SearchResults

Dictionary mapping product ID to SatelliteImage objects
Notes

This is an abstract method that concrete implementations must override.

Source code in sat_download\api\base.py 
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
@abstractmethod
def search(self, filters : SearchFilters) -> SearchResults:
    """
    Search for satellite imagery using specified filters.

    Parameters
    ----------
    filters : SearchFilters
        The search filters to apply to the search

    Returns
    -------
    SearchResults
        Dictionary mapping product ID to SatelliteImage objects

    Notes
    -----
    This is an abstract method that concrete implementations must override.
    """
    pass

download abstractmethod 

download(
    image_id: str, outname: str, verbose: int
) -> str | None

Download a satellite image by its ID.

Parameters:

Name Type Description Default
image_id str

The unique identifier of the image to download.

 required
outname str

The output filename where the image will be saved.

 required
verbose int

Verbosity level for logging the download process. 0 = silent, >0 = progress bar,

 required

Returns:

Type Description
str | None

The file path of the downloaded image if the download is successful. Returns None if the download fails.
Notes
  • This is an abstract method that concrete implementations must override.
  • Implementations should handle any necessary authentication and API-specific download logic.
  • Exceptions should be handled appropriately to ensure the application remains stable.
Source code in sat_download\api\base.py 
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
@abstractmethod
def download(self, image_id: str, outname: str, verbose : int) -> str | None:
    """
    Download a satellite image by its ID.

    Parameters
    ----------
    image_id : str
        The unique identifier of the image to download.
    outname : str
        The output filename where the image will be saved.
    verbose : int
        Verbosity level for logging the download process. 0 = silent, >0 = progress bar,

    Returns
    -------
    str | None
        The file path of the downloaded image if the download is successful.
        Returns None if the download fails.

    Notes
    -----
    - This is an abstract method that concrete implementations must override.
    - Implementations should handle any necessary authentication and API-specific
      download logic.
    - Exceptions should be handled appropriately to ensure the application remains stable.
    """
    pass

bulk_search(filters: SearchFilters) -> SearchResults

Perform an iterative search over a date range by breaking it into smaller queries.

This method handles large time-range searches by iteratively searching smaller time periods and combining the results.

Parameters:

Name Type Description Default
filters SearchFilters

The search filters to apply, including date range

 required

Returns:

Type Description
SearchResults

Combined dictionary of search results from all iterations
Notes

This implementation progressively narrows the search window by updating the end_date of the filters based on the most recent image found.

Source code in sat_download\api\base.py 
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
def bulk_search(self, filters : SearchFilters) -> SearchResults:
    """
    Perform an iterative search over a date range by breaking it into smaller queries.

    This method handles large time-range searches by iteratively searching smaller
    time periods and combining the results.

    Parameters
    ----------
    filters : SearchFilters
        The search filters to apply, including date range

    Returns
    -------
    SearchResults
        Combined dictionary of search results from all iterations

    Notes
    -----
    This implementation progressively narrows the search window by updating
    the end_date of the filters based on the most recent image found.
    """
    last_filters = None
    end = datetime.strptime(filters.end_date, '%Y-%m-%d')

    results : SearchResults = {}
    products : SearchResults = self.search(filters)

    while bool(products) and last_filters != filters:            
        last_filters = deepcopy(filters)

        for product in products.values():
            date = datetime.strptime(product.date, '%Y%m%d')
            if date < end:
                end = date

        results.update(products)
        filters.end_date = end.strftime('%Y-%m-%d')
        products = self.search(filters)

    return results

Available Implementations

Class Provider Collections Module
ODataAPI Copernicus Data Space Ecosystem Sentinel-2, Sentinel-3 sat_download.api.odata
USGSAPI USGS Earth Explorer Landsat 8 sat_download.api.usgs

Usage Example

from sat_download.api.odata import ODataAPI
from sat_download.data_types.search import SearchFilters
from sat_download.enums import COLLECTIONS

# Create API instance
api = ODataAPI(username="user", password="pass")

# Define search filters
filters = SearchFilters(
    collection=COLLECTIONS.SENTINEL_2.value,
    start_date="2024-01-01",
    end_date="2024-01-31",
    tile_id="30TWM"
)

# Search for images
results = api.search(filters)
print(f"Found {len(results)} images")

# Download images
for image_id, image in results.items():
    api.download(image_id, f"./images/{image.filename}", verbose=1)

Creating a New Implementation

To add support for a new satellite data provider, inherit from SatelliteAPI:

from sat_download.api.base import SatelliteAPI
from sat_download.data_types.search import SearchFilters, SearchResults

class NewProviderAPI(SatelliteAPI):
    """Implementation for a new satellite data provider."""

    API_URL = "https://api.newprovider.com/v1/"

    def __init__(self, username: str, password: str) -> None:
        super().__init__(username, password)
        self._authenticate()

    def search(self, filters: SearchFilters) -> SearchResults:
        # Implement provider-specific search
        pass

    def download(self, image_id: str, outname: str, verbose: int) -> str | None:
        # Implement provider-specific download
        pass

Design Patterns

The base module implements several design patterns:

  • Abstract Factory Pattern: Defines interface for creating API clients
  • Template Method Pattern: bulk_search() defines algorithm skeleton

See: Design Patterns

See Search Types for full documentation on SearchFilters, SatelliteImage, and SearchResults.