DOCSEARCHbyAlgolia
Submit Docs

eodag

repository·develop·Indexed 19 days ago

https://github.com/cs-si/eodag

Earth Observation Data Access Gateway (EODAG) is a plugin-oriented Python framework and CLI tool for searching, aggregating, and downloading remote sensed images through a unified API. It abstracts differences between data providers and supports the SpatioTemporal Asset Catalog (STAC) specification for data representation. The framework is extensible via custom search, download, auth, and API plugins.

Tokens
38.4K
Snippets
115
Records
192
Agent score
63%

What's inside eodag

  1. Overview of EODAG (Earth Observation Data Access Gateway)

    develop

    EODAG is a command line tool and a Python library designed for searching and downloading remotely sensed images. It provides a unified API for data access, allowing users to interact with various data providers (such as AWS/GCS EO catalogs, Copernicus, CNES, ESA, USGS/Landsat, etc.) using a consistent interface.

    Key features include:

    • Unified API: Search and download products from different providers using the same commands/methods.
    • Dual Interface: Available as both a Command Line Interface (CLI) and a Python library.
    • STAC Support: Supports STAC and Static STAC catalogs.
    • Extensibility: New providers can be added via configuration files or by developing plugins.
    • Large Catalog: Comes pre-configured with over 270 collections.

  2. What is EODAG and how does it work?

    develop

    EODAG (Earth Observation Data Access Gateway) is a plugin-oriented Python framework and command-line tool designed to provide a unified API for accessing Earth Observation (EO) data. It abstracts away the complexities of different data providers, including varying discovery methods (STAC, OData, OpenSearch), access protocols (HTTP, S3, direct file system), and authentication mechanisms (OIDC, JWT, Basic Auth).

    The EODAG SDK provides three core capabilities:

    1. List collections: Retrieve a list of supported products and their descriptions.
    2. Search products: Search for specific products within a collection based on provided criteria.
    3. Download products: Download products "as is" to a local environment.

    EODAG uses a modular plugin architecture composed of three plugin types:

    • Catalog search plugins: Handle data discovery (e.g., STAC, OpenSearch), path building, quicklook retrieval, and result aggregation.
    • Download plugins: Manage local data retrieval (e.g., via HTTP, S3) while ensuring a consistent directory organization.
    • Authentication plugins: Handle user authentication for external services (e.g., JSON Token, Basic Auth, OIDC).

  3. Use EODataAccessGateway as the main entry point

    develop

    The EODataAccessGateway is the primary interface for interacting with eodag. It orchestrates the entire workflow for accessing Earth observation data, including:

    • Loading and managing configurations.
    • Accessing data catalogs.
    • Performing searches for data.
    • Applying filters to results.
    • Executing download operations.

  4. Use the SearchResult class to manage search results

    develop
    The SearchResult class is the primary interface for handling and manipulating results returned from the EODAG API. It allows you to filter results (e.g., by date, property, or spatial overlap), navigate through paginated results, and convert the data into various formats like dictionaries, PySTAC objects, or geospatial geometries (Shapely/WKT).

  5. Manage provider search priority

    develop

    When multiple providers offer the same collection (e.g., Sentinel 2 Level-1C), EODAG uses the provider with the highest priority.

    • Priority Value: An integer value. A higher value means higher priority.
    • Default Behavior: Currently, PEPS is the default preferred provider. To make another provider the preferred one, you must set its priority to an integer higher than all other providers offering that collection.
    • Fallback: If you target a specific provider that does not offer a requested collection, EODAG will automatically fall back to the provider with the highest priority that does offer it.

  6. Handle progress bars in download operations

    develop

    Eodag uses eodag.utils.ProgressCallback to manage progress bars during download and extraction.

    Automatic Progress Bar Management

    When calling EOProduct.download() or EODataAccessGateway.download_all(), eodag automatically handles the instantiation and closing of progress bars. Plugins do not need to manage the lifecycle of these bars themselves.

    Custom Progress Callbacks

    You can pass a custom eodag.utils.ProgressCallback instance to EODataAccessGateway.download or EODataAccessGateway.download_all.

    • If you pass a callback to download(product, progress_callback=bar), the provided bar is used for the product's download/extraction and is kept open by eodag.
    • If you pass a callback to download_all(products, progress_callback=bar), the provided bar is used to track the total product count and is closed by eodag. A duplicate of this bar is then used to track individual product downloads/extractions and is kept open.

  7. Manage search results with SearchResult

    develop

    The SearchResult object acts as a container for data returned from search operations. It provides:

    • Filtering capabilities to refine results.
    • Conversion methods to transform result data.
    • A standardized interface for manipulating and navigating search results.

  8. How EODAG works: Plugin Architecture

    develop

    EODAG is a plugin-oriented Python framework designed to provide a unified API for accessing Earth Observation (EO) data regardless of the provider. It uses three types of plugins to compose its functionality:

    • Catalog search plugins: Responsible for searching data (e.g., via STAC, OpenSearch, OData), building paths, retrieving quicklooks, and combining results.
    • Download plugins: Handle local data retrieval (e.g., via HTTP, S3) and ensure a consistent directory organization.
    • Authentication plugins: Manage user authentication for external services (e.g., JSON Token, Basic Auth, OIDC).

    The core SDK workflow revolves around three main capabilities: listing collections, searching products, and downloading products.

  9. Implement a custom search plugin

    develop

    To create a custom search plugin in eodag, you must create a class that inherits from eodag.plugins.search.base.Search and implements the query method. This method is responsible for executing the search logic and returning results compatible with the eodag search interface.

    from eodag.plugins.search.base import Search

class MyCustomSearch(Search):
    def query(self, **kwargs):
        # Implement search logic here
        pass

  11. Manage product assets with the Assets module

    develop
    The eodag.api.product._assets module provides the Assets and Asset classes to manage resources associated with an EOProduct. These assets typically include files, metadata, or other data packages belonging to a product. You can use these classes to access, manipulate, and extend operations related to the assets within a product's data package.

  12. Search by guessing collections from parameters

    develop

    If the collection name is unknown, EODAG can attempt to guess it based on search parameters. Supported parameters include:

    • instruments (e.g., MSI)
    • constellation (e.g., SENTINEL2)
    • platform (e.g., S2A)
    • processing-level (e.g., L1)
    • sensor-type (e.g., OPTICAL)
    • keywords (case-insensitive, ignores - or _ characters)
    eodag search \
--constellation SENTINEL2 \
--processing-level L1 \
--box 1 43 2 44 \
--start 2021-03-01 --end 2021-03-31