EODataAccessGateway#

Constructor#

EODataAccessGateway([user_conf_file_path, ...])

An API for downloading a wide variety of geospatial products originating from different types of providers.

Configuration#

EODataAccessGateway.set_preferred_provider(...)

Set max priority for the given provider.

EODataAccessGateway.get_preferred_provider()

Get the provider currently set as the preferred one for searching products, along with its priority.

EODataAccessGateway.update_providers_config(...)

Update providers configuration with given input.

EODataAccessGateway.update_product_types_list(...)

Update eodag product types list

Catalog#

EODataAccessGateway.available_providers([...])

Gives the sorted list of the available providers

EODataAccessGateway.list_product_types([...])

Lists supported product types.

EODataAccessGateway.guess_product_type(**kwargs)

Find eodag product types codes that best match a set of search params

EODataAccessGateway.fetch_product_types_list([...])

Fetch product types list and update if needed

EODataAccessGateway.discover_product_types([...])

Fetch providers for product types

Crunch#

EODataAccessGateway.crunch(results, **kwargs)

Apply the filters given through the keyword arguments to the results

EODataAccessGateway.get_cruncher(name, **options)

Build a crunch plugin from a configuration

Download#

EODataAccessGateway.download(product[, ...])

Download a single product.

EODataAccessGateway.download_all(search_result)

Download all products resulting from a search.

Serialize/Deserialize#

EODataAccessGateway.serialize(search_result)

Registers results of a search into a geojson file.

EODataAccessGateway.deserialize(filename)

Loads results of a search from a geojson file.

EODataAccessGateway.deserialize_and_register(...)

Loads results of a search from a geojson file and register products with the information needed to download itself

STAC#

EODataAccessGateway.load_stac_items(filename)

Loads STAC items from a geojson file / STAC catalog or collection, and convert to SearchResult.

Misc#

EODataAccessGateway.group_by_extent(searches)

Combines multiple SearchResults and return a list of SearchResults grouped by extent (i.e.

EODataAccessGateway.guess_product_type(**kwargs)

Find eodag product types codes that best match a set of search params

EODataAccessGateway.list_queryables([provider])

Fetch the queryable properties for a given product type and/or provider.
class eodag.api.core.EODataAccessGateway(user_conf_file_path: Optional[str] = None, locations_conf_path: Optional[str] = None)[source]#

An API for downloading a wide variety of geospatial products originating from different types of providers.

Parameters

  • user_conf_file_path (str) – (optional) Path to the user configuration file

  • locations_conf_path (str) – (optional) Path to the locations configuration file

available_providers(product_type: Optional[str] = None) → List[str][source]#

Gives the sorted list of the available providers

Parameters

product_type (str) – (optional) Only list providers configured for this product_type

Returns

the sorted list of the available providers

Return type

list

crunch(results: eodag.api.search_result.SearchResult, **kwargs: Any) → eodag.api.search_result.SearchResult[source]#

Apply the filters given through the keyword arguments to the results

Parameters

results (SearchResult) – The results of a eodag search request

Returns

The result of successively applying all the filters to the results

Return type

SearchResult

static deserialize(filename: str) → eodag.api.search_result.SearchResult[source]#

Loads results of a search from a geojson file.

Parameters

filename (str) – A filename containing a search result encoded as a geojson

Returns

The search results encoded in filename

Return type

SearchResult

deserialize_and_register(filename: str) → eodag.api.search_result.SearchResult[source]#

Loads results of a search from a geojson file and register products with the information needed to download itself

Parameters

filename (str) – A filename containing a search result encoded as a geojson

Returns

The search results encoded in filename

Return type

SearchResult

discover_product_types(provider: Optional[str] = None) → Optional[Dict[str, Any]][source]#

Fetch providers for product types

Parameters

provider (str) – (optional) The name of a provider to fetch. Defaults to all providers (None value).

Returns

external product types configuration

Return type

dict

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

Download a single product.

This is an alias to the method of the same name on EOProduct, but it performs some additional checks like verifying that a downloader and authenticator are registered for the product before trying to download it.

If the metadata mapping for downloadLink is set to something that can be interpreted as a link on a local filesystem, the download is skipped (by now, only a link starting with file:/ is supported). Therefore, any user that knows how to extract product location from product metadata on a provider can override the downloadLink metadata mapping in the right way. For example, using the environment variable: EODAG__CREODIAS__SEARCH__METADATA_MAPPING__DOWNLOADLINK="file:///{id}" will lead to all EOProduct’s originating from the provider creodias to have their downloadLink metadata point to something like: file:///12345-678, making this method immediately return the later string without trying to download the product.

Parameters

  • product (EOProduct) – The EO product to download

  • progress_callback (ProgressCallback or None) – (optional) A method or a callable object which takes a current size and a maximum size as inputs and handle progress bar creation and update to give the user a feedback on the download progress

  • 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

Return type

str

Raises

PluginImplementationError

Raises

RuntimeError

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

Download all products resulting from a search.

Parameters

  • search_result (SearchResult) – A collection of EO products resulting from a search

  • 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 or None) – (optional) A method or a callable object which takes a current size and a maximum size as inputs and handle progress bar creation and update to give the user a feedback on the download progress

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

  • 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

A collection of the absolute paths to the downloaded products

Return type

list

fetch_product_types_list(provider: Optional[str] = None) → None[source]#

Fetch product types list and update if needed

Parameters

provider (str) – (optional) The name of a provider for which product types list should be updated. Defaults to all providers (None value).

get_cruncher(name: str, **options: Any) → Crunch[source]#

Build a crunch plugin from a configuration

Parameters

  • name (str) – The name of the cruncher to build

  • options (dict) – The configuration options of the cruncher

Returns

The cruncher named name

Return type

Crunch

get_preferred_provider() → Tuple[str, int][source]#

Get the provider currently set as the preferred one for searching products, along with its priority.

Returns

The provider with the maximum priority and its priority

Return type

tuple(str, int)

static group_by_extent(searches: List[eodag.api.search_result.SearchResult]) → List[eodag.api.search_result.SearchResult][source]#

Combines multiple SearchResults and return a list of SearchResults grouped by extent (i.e. bounding box).

Parameters

searches (list) – List of eodag SearchResult

Returns

list of SearchResult

guess_product_type(**kwargs: Any) → List[str][source]#

Find eodag product types codes that best match a set of search params

Parameters

kwargs – A set of search parameters as keywords arguments

Returns

The best match for the given parameters

Return type

list[str]

Raises

NoMatchingProductType

list_product_types(provider: Optional[str] = None, fetch_providers: bool = True) → List[Dict[str, Any]][source]#

Lists supported product types.

Parameters

  • provider (str) – (optional) The name of a provider that must support the product types we are about to list

  • fetch_providers (bool) – (optional) Whether to fetch providers for new product types or not

Returns

The list of the product types that can be accessed using eodag.

Return type

list(dict)

Raises

UnsupportedProvider

list_queryables(provider: Optional[str] = None, **kwargs: Any) → Dict[str, Annotated[Any, FieldInfo]][source]#

Fetch the queryable properties for a given product type and/or provider.

Parameters

  • provider (str) – (optional) The provider.

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

Returns

A dict containing the EODAG queryable properties, associating parameters to their annotated type

Return type

Dict[str, Annotated[Any, FieldInfo]]

load_stac_items(filename: str, recursive: bool = False, max_connections: int = 100, provider: Optional[str] = None, productType: Optional[str] = None, timeout: int = 5, **kwargs: Any) → eodag.api.search_result.SearchResult[source]#

Loads STAC items from a geojson file / STAC catalog or collection, and convert to SearchResult.

Features are parsed using eodag provider configuration, as if they were the response content to an API request.

Parameters

  • filename (str) – A filename containing features encoded as a geojson

  • recursive (bool) – (optional) Browse recursively in child nodes if True

  • max_connections (int) – (optional) Maximum number of connections for HTTP requests

  • provider (str) – (optional) Data provider

  • productType (str) – (optional) Data product type

  • timeout (float) – (optional) Timeout in seconds for each internal HTTP request

  • kwargs (Any) – Parameters that will be stored in the result as search criteria

Returns

The search results encoded in filename

Return type

SearchResult

Deprecated since version 2.2.1: Use the StaticStacSearch search plugin instead.

search(page: int = 1, items_per_page: int = 20, raise_errors: bool = False, start: Optional[str] = None, end: Optional[str] = None, geom: Optional[Union[str, Dict[str, float], BaseGeometry]] = None, locations: Optional[Dict[str, str]] = None, provider: Optional[str] = None, **kwargs: Any) → Tuple[SearchResult, int][source]#

Look for products matching criteria on known providers.

The default behaviour is to look for products on the provider with the highest priority supporting the requested product type. These priorities are configurable through user configuration file or individual environment variable. If the request to the provider with the highest priority fails or is empty, the data will be request from the provider with the next highest priority. Only if the request fails for all available providers, an error will be thrown.

Parameters

  • page (int) – (optional) The page number to return

  • items_per_page (int) – (optional) The number of results that must appear in one single page

  • raise_errors (bool) – (optional) When an error occurs when searching, if this is set to True, the error is raised

  • start (str) – (optional) Start sensing time in ISO 8601 format (e.g. “1990-11-26”, “1990-11-26T14:30:10.153Z”, “1990-11-26T14:30:10+02:00”, …). If no time offset is given, the time is assumed to be given in UTC.

  • end (str) – (optional) End sensing time in ISO 8601 format (e.g. “1990-11-26”, “1990-11-26T14:30:10.153Z”, “1990-11-26T14:30:10+02:00”, …). If no time offset is given, the time is assumed to be given in UTC.

  • geom (Union[str, dict, shapely.geometry.base.BaseGeometry]) –

    (optional) Search area that can be defined in different ways:

    • with a Shapely geometry object: shapely.geometry.base.BaseGeometry

    • with a bounding box (dict with keys: “lonmin”, “latmin”, “lonmax”, “latmax”): dict.fromkeys(["lonmin", "latmin", "lonmax", "latmax"])

    • with a bounding box as list of float: [lonmin, latmin, lonmax, latmax]

    • with a WKT str

  • locations (dict) – (optional) Location filtering by name using locations configuration {"<location_name>"="<attr_regex>"}. For example, {"country"="PA."} will use the geometry of the features having the property ISO3 starting with ‘PA’ such as Panama and Pakistan in the shapefile configured with name=country and attr=ISO3

  • kwargs (Union[int, str, bool, dict]) – Some other criteria that will be used to do the search, using paramaters compatibles with the provider

  • provider (str) – (optional) the provider to be used. If set, search fallback will be disabled. If not set, the configured preferred provider will be used at first before trying others until finding results.

Returns

A collection of EO products matching the criteria and the total number of results found

Return type

tuple(SearchResult, int)

Note

The search interfaces, which are implemented as plugins, are required to return a list as a result of their processing. This requirement is enforced here.

search_all(items_per_page: Optional[int] = None, start: Optional[str] = None, end: Optional[str] = None, geom: Optional[Union[str, Dict[str, float], BaseGeometry]] = None, locations: Optional[Dict[str, str]] = None, **kwargs: Any) → SearchResult[source]#

Search and return all the products matching the search criteria.

It iterates over the pages of a search query and collects all the returned products into a single SearchResult instance.

Requests are attempted to all providers of the product ordered by descending piority.

Parameters

  • items_per_page (int) – (optional) The number of results requested internally per page. The maximum number of items than can be requested at once to a provider has been configured in EODAG for some of them. If items_per_page is None and this number is available for the searched provider, it is used to limit the number of requests made. This should also reduce the time required to collect all the products matching the search criteria. If this number is not available, a default value of 50 is used instead. items_per_page can also be set to any arbitrary value.

  • start (str) – (optional) Start sensing time in ISO 8601 format (e.g. “1990-11-26”, “1990-11-26T14:30:10.153Z”, “1990-11-26T14:30:10+02:00”, …). If no time offset is given, the time is assumed to be given in UTC.

  • end (str) – (optional) End sensing time in ISO 8601 format (e.g. “1990-11-26”, “1990-11-26T14:30:10.153Z”, “1990-11-26T14:30:10+02:00”, …). If no time offset is given, the time is assumed to be given in UTC.

  • geom (Union[str, dict, shapely.geometry.base.BaseGeometry]) –

    (optional) Search area that can be defined in different ways:

    • with a Shapely geometry object: shapely.geometry.base.BaseGeometry

    • with a bounding box (dict with keys: “lonmin”, “latmin”, “lonmax”, “latmax”): dict.fromkeys(["lonmin", "latmin", "lonmax", "latmax"])

    • with a bounding box as list of float: [lonmin, latmin, lonmax, latmax]

    • with a WKT str

  • locations (dict) – (optional) Location filtering by name using locations configuration {"<location_name>"="<attr_regex>"}. For example, {"country"="PA."} will use the geometry of the features having the property ISO3 starting with ‘PA’ such as Panama and Pakistan in the shapefile configured with name=country and attr=ISO3

  • kwargs (Union[int, str, bool, dict]) – Some other criteria that will be used to do the search, using parameters compatible with the provider

Returns

An iterator that yields page per page a collection of EO products matching the criteria

Return type

Iterator[SearchResult]

search_iter_page(items_per_page: int = 20, start: Optional[str] = None, end: Optional[str] = None, geom: Optional[Union[str, Dict[str, float], BaseGeometry]] = None, locations: Optional[Dict[str, str]] = None, **kwargs: Any) → Iterator[SearchResult][source]#

Iterate over the pages of a products search.

Parameters

  • items_per_page (int) – (optional) The number of results requested per page

  • start (str) – (optional) Start sensing time in ISO 8601 format (e.g. “1990-11-26”, “1990-11-26T14:30:10.153Z”, “1990-11-26T14:30:10+02:00”, …). If no time offset is given, the time is assumed to be given in UTC.

  • end (str) – (optional) End sensing time in ISO 8601 format (e.g. “1990-11-26”, “1990-11-26T14:30:10.153Z”, “1990-11-26T14:30:10+02:00”, …). If no time offset is given, the time is assumed to be given in UTC.

  • geom (Union[str, dict, shapely.geometry.base.BaseGeometry]) –

    (optional) Search area that can be defined in different ways:

    • with a Shapely geometry object: shapely.geometry.base.BaseGeometry

    • with a bounding box (dict with keys: “lonmin”, “latmin”, “lonmax”, “latmax”): dict.fromkeys(["lonmin", "latmin", "lonmax", "latmax"])

    • with a bounding box as list of float: [lonmin, latmin, lonmax, latmax]

    • with a WKT str

  • locations (dict) – (optional) Location filtering by name using locations configuration {"<location_name>"="<attr_regex>"}. For example, {"country"="PA."} will use the geometry of the features having the property ISO3 starting with ‘PA’ such as Panama and Pakistan in the shapefile configured with name=country and attr=ISO3

  • kwargs (Union[int, str, bool, dict]) – Some other criteria that will be used to do the search, using paramaters compatibles with the provider

Returns

An iterator that yields page per page a collection of EO products matching the criteria

Return type

Iterator[SearchResult]

static serialize(search_result: eodag.api.search_result.SearchResult, filename: str = 'search_results.geojson') → str[source]#

Registers results of a search into a geojson file.

Parameters

  • search_result (SearchResult) – A collection of EO products resulting from a search

  • filename (str) – (optional) The name of the file to generate

Returns

The name of the created file

Return type

str

set_preferred_provider(provider: str) → None[source]#

Set max priority for the given provider.

Parameters

provider (str) – The name of the provider that should be considered as the preferred provider to be used for this instance

update_product_types_list(ext_product_types_conf: Dict[str, Optional[Dict[str, Dict[str, Any]]]]) → None[source]#

Update eodag product types list

Parameters

ext_product_types_conf (dict) – external product types configuration

update_providers_config(yaml_conf: str) → None[source]#

Update providers configuration with given input. Can be used to add a provider to existing configuration or update an existing one.

Parameters

yaml_conf (str) – YAML formated provider configuration