EODataAccessGateway
Contents
EODataAccessGateway#
Constructor#
|
An API for downloading a wide variety of geospatial products originating from different types of providers. |
Configuration#
Set max priority for the given provider. |
|
Get the provider currently set as the preferred one for searching products, along with its priority. |
|
Update providers configuration with given input. |
|
Update eodag product types list |
Catalog#
Gives the sorted list of the available providers |
|
Lists supported product types. |
|
|
Find the eodag product type code that best matches a set of search params |
Fetch product types list and update if needed |
|
Fetch providers for product types |
Search#
|
Look for products matching criteria on known providers. |
Search and return all the products matching the search criteria. |
|
Iterate over the pages of a products search. |
Crunch#
|
Apply the filters given through the keyword arguments to the results |
|
Build a crunch plugin from a configuration |
Download#
|
Download a single product. |
|
Download all products resulting from a search. |
Serialize/Deserialize#
|
Registers results of a search into a geojson file. |
|
Loads results of a search from a geojson file. |
Loads results of a search from a geojson file and register products with the information needed to download itself |
STAC#
|
Loads STAC items from a geojson file / STAC catalog or collection, and convert to SearchResult. |
Misc#
|
Combines multiple SearchResults and return a list of SearchResults grouped by extent (i.e. |
|
Find the eodag product type code that best matches a set of search params |
- class eodag.api.core.EODataAccessGateway(user_conf_file_path=None, locations_conf_path=None)[source]#
An API for downloading a wide variety of geospatial products originating from different types of providers.
- Parameters
- crunch(results, **kwargs)[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
- static deserialize(filename)[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
- deserialize_and_register(filename)[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
- download(product, progress_callback=None, wait=2, timeout=20, **kwargs)[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 withfile:/
is supported). Therefore, any user that knows how to extract product location from product metadata on a provider can override thedownloadLink
metadata mapping in the right way. For example, using the environment variable:EODAG__CREODIAS__SEARCH__METADATA_MAPPING__DOWNLOADLINK="file:///{id}"
will lead to allEOProduct
’s originating from the providercreodias
to have theirdownloadLink
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 downloadprogress_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 progresswait (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
- Raises
- Raises
- download_all(search_result, downloaded_callback=None, progress_callback=None, wait=2, timeout=20, **kwargs)[source]#
Download all products resulting from a search.
- Parameters
search_result (
SearchResult
) – A collection of EO products resulting from a searchdownloaded_callback (Callable[[
EOProduct
], None] or None) – (optional) A method or a callable object which takes as parameter theproduct
. You can use the base classDownloadedCallback
and override its__call__
method. Will be called each time a product finishes downloadingprogress_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 progresswait (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
- fetch_product_types_list(provider=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_preferred_provider()[source]#
Get the provider currently set as the preferred one for searching products, along with its priority.
- static group_by_extent(searches)[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)[source]#
Find the eodag product type code that best matches 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
- Raises
- list_product_types(provider=None, fetch_providers=True)[source]#
Lists supported product types.
- Parameters
- Returns
The list of the product types that can be accessed using eodag.
- Return type
- Raises
- load_stac_items(filename, recursive=False, max_connections=100, provider=None, productType=None, timeout=5, **kwargs)[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
Deprecated since version 2.2.1: Use the
StaticStacSearch
search plugin instead.
- search(page=1, items_per_page=20, raise_errors=False, start=None, end=None, geom=None, locations=None, provider=None, **kwargs)[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=ISO3kwargs (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=None, start=None, end=None, geom=None, locations=None, **kwargs)[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=ISO3kwargs (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=20, start=None, end=None, geom=None, locations=None, **kwargs)[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=ISO3kwargs (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, filename='search_results.geojson')[source]#
Registers results of a search into a geojson file.
- Parameters
search_result (
SearchResult
) – A collection of EO products resulting from a searchfilename (str) – (optional) The name of the file to generate
- Returns
The name of the created file
- Return type
- set_preferred_provider(provider)[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