API

API#

This module contains the API clients for different satellite data providers.

Base API#

class sat_download.api.base.SatelliteAPI(username: str, password: str)[source]#

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:

  • username (str) – Username or API key for authentication with the satellite data provider

  • password (str) – Password or secret for authentication with the satellite data provider

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

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:

Combined dictionary of search results from all iterations

Return type:

SearchResults

Notes

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

abstract download(image_id: str, outname: str)[source]#

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

Returns:

Implementation may return None or status message on success

Return type:

None or str

Notes

This is an abstract method that concrete implementations must override.

abstract search(filters: SearchFilters) → Dict[str, SatelliteImage][source]#

Search for satellite imagery using specified filters.

Parameters:

filters (SearchFilters) – The search filters to apply to the search

Returns:

Dictionary mapping product IDs to SatelliteImage objects

Return type:

SearchResults

Notes

This is an abstract method that concrete implementations must override.

OData API#

class sat_download.api.odata.ODataAPI(username: str, password: str)[source]#

Bases: SatelliteAPI

Implementation of SatelliteAPI for the Copernicus Data Space Ecosystem OData API.

This class provides methods to search and download satellite imagery from the Copernicus Data Space Ecosystem using their OData API.

Parameters:

  • username (str) – Username for authentication with the Copernicus Data Space API

  • password (str) – Password for authentication with the Copernicus Data Space API

SEARCH_URL#

Endpoint URL for searching satellite products

Type:

str

DOWNLOAD_URL#

Endpoint URL for downloading satellite products

Type:

str

TOKEN_URL#

Endpoint URL for obtaining authentication tokens

Type:

str

Notes

Authentication is performed using Keycloak OAuth2 tokens which are obtained as needed for download operations.

See also

sat_download.api.base.SatelliteAPI

Base class defining the API interface

sat_download.api.usgs.USGSAPI

Implementation for USGS Earth Explorer API

DOWNLOAD_URL = 'https://download.dataspace.copernicus.eu/odata/v1/Products'#
SEARCH_URL = 'https://catalogue.dataspace.copernicus.eu/odata/v1/Products'#
TOKEN_URL = 'https://identity.dataspace.copernicus.eu/auth/realms/CDSE/protocol/openid-connect/token'#
download(image_id: str, outname: str) → None[source]#

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

Returns:

Success message on successful download

Return type:

str

Raises:

Exception – If the download fails

Notes

Implementation of the abstract download method for the Copernicus Data Space API. Uses tqdm to display a progress bar during download.

search(filters: SearchFilters) → Dict[str, SatelliteImage][source]#

Search for satellite imagery using specified filters.

Parameters:

filters (SearchFilters) – The search filters to apply to the search

Returns:

Dictionary mapping product IDs to SatelliteImage objects

Return type:

SearchResults

Raises:

Exception – If the API request fails

Notes

Implementation of the abstract search method for the Copernicus Data Space API.

USGS API#

class sat_download.api.usgs.USGSAPI(username, password)[source]#

Bases: SatelliteAPI

Implementation of SatelliteAPI for the USGS Earth Explorer API.

This class provides methods to search and download satellite imagery from the USGS Earth Explorer service using their Machine-to-Machine (M2M) API.

Parameters:

  • username (str) – Username for authentication with the USGS Earth Explorer API

  • password (str) – API token for authentication (not the user’s password)

API_URL#

Base URL for the USGS M2M API

Type:

str

LOGIN_ENDPOINT#

Endpoint for authentication

Type:

str

SEARCH_ENDPOINT#

Endpoint for searching scenes

Type:

str

DOWNLOAD_REQUEST_ENDPOINT#

Endpoint for requesting download URLs

Type:

str

DOWNLOAD_OPTIONS_ENDPOINT#

Endpoint for fetching download options

Type:

str

Notes

Authentication is performed using API tokens which must be generated through the USGS Earth Explorer portal. The password parameter should actually be the API token, not the user’s password.

See also

sat_download.api.base.SatelliteAPI

Base class defining the API interface

sat_download.api.odata.ODataAPI

Implementation for Copernicus Data Space API

API_URL = 'https://m2m.cr.usgs.gov/api/api/json/stable/'#
DOWNLOAD_OPTIONS_ENDPOINT = 'download-options'#
DOWNLOAD_REQUEST_ENDPOINT = 'download-request'#
LOGIN_ENDPOINT = 'login-token'#
SEARCH_ENDPOINT = 'scene-search'#
download(image_id: str, outname: str) → None[source]#

Download a satellite image by its ID (URL).

Parameters:

  • image_id (str) – The download URL for the image (not entity ID)

  • outname (str) – The output filename where the image will be saved

Returns:

The file is saved to the specified location on success

Return type:

None

Notes

Implementation of the abstract download method for USGS API. Uses tqdm to display a progress bar during download. Unlike other APIs, the image_id parameter is actually the download URL.

search(filters: SearchFilters) → Dict[str, SatelliteImage][source]#

Search for satellite imagery using specified filters.

Parameters:

filters (SearchFilters) – The search filters to apply to the search

Returns:

Dictionary mapping product IDs to SatelliteImage objects

Return type:

SearchResults

Raises:

Exception – If the API request fails

Notes

Implementation of the abstract search method for the USGS Earth Explorer API. Additional filtering is performed client-side on the returned results.

Contents