API Plugins#

Api plugins must inherit the following class and implement query() and download():

class eodag.plugins.apis.base.Api(provider: str, config: PluginConfig)[source]#

Plugins API Base plugin

An Api plugin has three download methods that it must implement:

  • query: search for products

  • download: download a single EOProduct

  • download_all: download multiple products from a SearchResult

The download methods must:

  • download data in the outputs_prefix folder defined in the plugin’s configuration or passed through kwargs

  • extract products from their archive (if relevant) if extract is set to True (True by default)

  • save a product in an archive/directory (in outputs_prefix) whose name must be the product’s title property

  • update the product’s location attribute once its data is downloaded (and eventually after it’s extracted) to the product’s location given as a file URI (e.g. ‘file:///tmp/product_folder’ on Linux or ‘file:///C:/Users/username/AppData/LOcal/Temp’ on Windows)

  • save a record file in the directory outputs_prefix/.downloaded whose name is built on the MD5 hash of the product’s remote_location attribute (hashlib.md5(remote_location.encode("utf-8")).hexdigest()) and whose content is the product’s remote_location attribute itself.

  • not try to download a product whose location attribute already points to an existing file/directory

  • not try to download a product if its record file exists as long as the expected product’s file/directory. If the record file only is found, it must be deleted (it certainly indicates that the download didn’t complete)

clear() → None[source]#

Method used to clear a search context between two searches.

discover_product_types() → Optional[Dict[str, Any]][source]#

Fetch product types list from provider using discover_product_types conf

discover_queryables(**kwargs: Any) → Optional[Dict[str, Any]][source]#

Fetch queryables list from provider using discover_queryables conf

Parameters

kwargs (Any) – additional filters for queryables (productType and other search arguments)

Returns

fetched queryable parameters dict

Return type

Optional[Dict[str, Annotated[Any, FieldInfo]]]

download(product: EOProduct, auth: Optional[PluginConfig] = None, progress_callback: Optional[ProgressCallback] = None, wait: int = 2, timeout: int = 20, **kwargs: Any) → Optional[str][source]#

Base download method. Not available, it must be defined for each plugin.

Parameters

  • product (EOProduct) – The EO product to download

  • auth (PluginConfig) – (optional) The configuration of a plugin of type Authentication

  • progress_callback (ProgressCallback) – (optional) A progress callback

  • wait (int) – (optional) If download fails, wait time in minutes between two download tries

  • timeout (int) – (optional) If download fails, maximum time in minutes before stop retrying to download

  • kwargs (Union[str, bool, dict]) – outputs_prefix (str), extract (bool), delete_archive (bool) and dl_url_params (dict) can be provided as additional kwargs and will override any other values defined in a configuration file or with environment variables.

Returns

The absolute path to the downloaded product in the local filesystem (e.g. ‘/tmp/product.zip’ on Linux or ‘C:UsersusernameAppDataLocalTempproduct.zip’ on Windows)

Return type

str

download_all(products: SearchResult, auth: Optional[PluginConfig] = None, downloaded_callback: Optional[DownloadedCallback] = None, progress_callback: Optional[ProgressCallback] = None, wait: int = 2, timeout: int = 20, **kwargs: Any) → List[str][source]#

Base download_all method.

Parameters

  • products (SearchResult) – Products to download

  • auth (PluginConfig) – (optional) The configuration of a plugin of type Authentication

  • downloaded_callback (Callable[[EOProduct], None] or None) – (optional) A method or a callable object which takes as parameter the product. You can use the base class DownloadedCallback and override its __call__ method. Will be called each time a product finishes downloading

  • progress_callback (ProgressCallback) – (optional) A progress callback

  • wait (int) – (optional) If download fails, wait time in minutes between two download tries

  • timeout (int) – (optional) If download fails, maximum time in minutes before stop retrying to download

  • kwargs (Union[str, bool, dict]) – outputs_prefix (str), extract (bool), delete_archive (bool) and dl_url_params (dict) can be provided as additional kwargs and will override any other values defined in a configuration file or with environment variables.

Returns

List of absolute paths to the downloaded products in the local filesystem (e.g. ['/tmp/product.zip'] on Linux or ['C:\Users\username\AppData\Local\Temp\product.zip'] on Windows)

Return type

list

get_defaults_as_queryables(product_type: str) → Dict[str, Any][source]#

Return given product type defaut settings as queryables

Parameters

product_type (str) – given product type

Returns

queryable parameters dict

Return type

Dict[str, Annotated[Any, FieldInfo]]

query(product_type: Optional[str] = None, items_per_page: int = 20, page: int = 1, count: bool = True, **kwargs: Any) → Tuple[List[EOProduct], Optional[int]][source]#

Implementation of how the products must be searched goes here.

This method must return a tuple with (1) a list of EOProduct instances (see eodag.api.product module) which will be processed by a Download plugin (2) and the total number of products matching the search criteria. If count is False, the second element returned must be None.

This table lists all the api plugins currently available:

eodag.plugins.apis.usgs.UsgsApi(provider, config)

A plugin that enables to query and download data on the USGS catalogues

eodag.plugins.apis.ecmwf.EcmwfApi(provider, ...)

A plugin that enables to build download-request and download data on ECMWF MARS.

eodag.plugins.apis.cds.CdsApi(provider, config)

A plugin that enables to build download-request and download data on CDS API.