CS-SI / eodag

Earth Observation Data Access Gateway
https://eodag.readthedocs.io
Apache License 2.0
309 stars 40 forks source link
catalog cbers copernicus downloader earth-observation eodag geographic-data geospatial gis landsat modis remote-sensing satellite-imagery search sentinel spatial-imagery stac

.. image:: https://eodag.readthedocs.io/en/latest/_static/eodag_bycs.png :target: https://github.com/CS-SI/eodag

|

.. |pypi-badge| image:: https://badge.fury.io/py/eodag.svg :target: https://badge.fury.io/py/eodag

.. |conda-badge| image:: https://img.shields.io/conda/vn/conda-forge/eodag :target: https://anaconda.org/conda-forge/eodag

.. |rtd-badge| image:: https://readthedocs.org/projects/eodag/badge/?version=latest&style=flat :target: https://eodag.readthedocs.io/en/latest/

.. |gha-badge| image:: https://github.com/CS-SI/eodag/actions/workflows/test.yml/badge.svg :target: https://github.com/CS-SI/eodag/actions

.. |ghi-badge| image:: https://img.shields.io/github/issues/CS-SI/eodag.svg :target: https://github.com/CS-SI/eodag/issues

.. |binder-badge| image:: https://mybinder.org/badge_logo.svg :target: https://mybinder.org/v2/git/https%3A%2F%2Fgithub.com%2FCS-SI%2Feodag.git/master?filepath=docs%2Fnotebooks%2Fintro_notebooks.ipynb

|pypi-badge| |conda-badge| |rtd-badge| |gha-badge| |ghi-badge| |binder-badge|

|

.. |license-badge| image:: https://img.shields.io/pypi/l/eodag.svg :target: https://pypi.org/project/eodag/

.. |versions-badge| image:: https://img.shields.io/pypi/pyversions/eodag.svg :target: https://pypi.org/project/eodag/

|license-badge| |versions-badge|

|

..

Checkout **EODAG Jupyterlab extension**: `eodag-labextension <https://github.com/CS-SI/eodag-labextension>`_!
This will bring a friendly UI to your notebook and help you search and browse for EO products using ``eodag``.

EODAG (Earth Observation Data Access Gateway) is a command line tool and a plugin-oriented Python framework for searching, aggregating results and downloading remote sensed images while offering a unified API for data access regardless of the data provider. The EODAG SDK is structured around three functions:

EODAG is developed in Python. It is structured according to a modular plugin architecture, easily extensible and able to integrate new data providers. Three types of plugins compose the tool:

Since v2.0 EODAG can be run as STAC client or server <https://eodag.readthedocs.io/en/latest/stac.html>_.

Read the documentation <https://eodag.readthedocs.io/en/latest/>_ for more insights.

.. image:: https://raw.githubusercontent.com/CS-SI/eodag/develop/docs/_static/eodag_overview.png :alt: EODAG overview :class: no-scaled-link

Installation

EODAG is available on PyPI <https://pypi.org/project/eodag/>_:

.. code-block:: bash

python -m pip install eodag

And with conda from the conda-forge channel <https://anaconda.org/conda-forge/eodag>_:

.. code-block:: bash

conda install -c conda-forge eodag

[New in v3.0.0] Please note that EODAG comes with a minimal set of dependencies. If you want more features, please install using one of the available extras <https://eodag.readthedocs.io/en/latest/getting_started_guide/install.html#optional-dependencies>_.

Usage

For downloading you will need to fill your credentials for the desired providers in your eodag user configuration file <https://eodag.readthedocs.io/en/latest/getting_started_guide/configure.html>_. The file will automatically be created with empty values on the first run.

Python API

Example usage for interacting with the api in your Python code:

.. code-block:: python

from eodag import EODataAccessGateway

dag = EODataAccessGateway()

search_results = dag.search(
    productType='S2_MSI_L1C',
    geom={'lonmin': 1, 'latmin': 43.5, 'lonmax': 2, 'latmax': 44}, # accepts WKT polygons, shapely.geometry, ...
    start='2021-01-01',
    end='2021-01-15'
)

product_paths = dag.download_all(search_results)

This will search for Sentinel 2 level-1C products on the default provider and return the found products first page and an estimated total number of products matching the search criteria. And then it will download these products. Please check the Python API User Guide <https://eodag.readthedocs.io/en/latest/api_user_guide.html>_ for more details.

[New in v3.0.0] search() <https://eodag.readthedocs.io/en/latest/notebooks/api_user_guide/4_search.html#search()>_ method now returns only a single SearchResult instead of a 2 values tuple.

STAC REST API

An eodag instance can be exposed through a STAC compliant REST api from the command line (eodag[server] needed):

.. code-block:: bash

$ eodag serve-rest --help
Usage: eodag serve-rest [OPTIONS]

  Start eodag HTTP server

  Set EODAG_CORS_ALLOWED_ORIGINS environment variable to configure Cross-
  Origin Resource Sharing allowed origins as comma-separated URLs (e.g.
  'http://somewhere,htttp://somewhere.else').

Options:
  -f, --config PATH   File path to the user configuration file with its
                      credentials, default is ~/.config/eodag/eodag.yml
  -l, --locs PATH     File path to the location shapefiles configuration file
  -d, --daemon        run in daemon mode
  -w, --world         run uvicorn using IPv4 0.0.0.0 (all network interfaces),
                      otherwise bind to 127.0.0.1 (localhost).
  -p, --port INTEGER  The port on which to listen  [default: 5000]
  --debug             Run in debug mode (for development purpose)
  --help              Show this message and exit.

# run server
$ eodag serve-rest

# list available product types for ``peps`` provider:
$ curl "http://127.0.0.1:5000/collections?provider=peps" | jq ".collections[].id"
"S1_SAR_GRD"
"S1_SAR_OCN"
"S1_SAR_SLC"
"S2_MSI_L1C"
"S2_MSI_L2A"

# search for items
$ curl "http://127.0.0.1:5000/search?collections=S2_MSI_L1C&bbox=0,43,1,44&datetime=2018-01-20/2018-01-25" \
| jq ".numberMatched"
6

# browse for items
$ curl "http://127.0.0.1:5000/catalogs/S2_MSI_L1C/country/FRA/year/2021/month/01/day/25/cloud_cover/10/items" \
| jq ".numberMatched"
9

# get download link
$ curl "http://127.0.0.1:5000/catalogs/S2_MSI_L1C/country/FRA/year/2021/month/01/day/25/cloud_cover/10/items" \
| jq ".features[0].assets.downloadLink.href"
"http://127.0.0.1:5000/catalogs/S2_MSI_L1C/country/FRA/year/2021/month/01/day/25/cloud_cover/10/items/S2A_MSIL1C_20210125T105331_N0209_R051_T31UCR_20210125T130733/download"

# download
$ wget "http://127.0.0.1:5000/catalogs/S2_MSI_L1C/country/FRA/year/2021/month/01/day/25/cloud_cover/10/items/S2A_MSIL1C_20210125T105331_N0209_R051_T31UCR_20210125T130733/download"

eodag-server is available on https://hub.docker.com/r/csspace/eodag-server <https://hub.docker.com/r/csspace/eodag-server>_:

.. code-block:: bash

docker run -p 5000:5000 --rm csspace/eodag-server:3.0.0b2

You can also browse over your STAC API server using STAC Browser <https://github.com/radiantearth/stac-browser>_. Simply run:

.. code-block:: bash

git clone https://github.com/CS-SI/eodag.git
cd eodag
docker-compose up
# or for a more verbose logging:
EODAG_LOGGING=3 docker-compose up

And browse http://127.0.0.1:5001:

.. image:: https://raw.githubusercontent.com/CS-SI/eodag/develop/docs/_static/stac_browser_example_600.png :target: https://raw.githubusercontent.com/CS-SI/eodag/develop/docs/_static/stac_browser_example.png :alt: STAC browser example :width: 600px

For more information, see STAC REST API usage <https://eodag.readthedocs.io/en/latest/stac_rest.html>_.

Command line interface

Start playing with the CLI:

Contribute

Have you spotted a typo in our documentation? Have you observed a bug while running EODAG? Do you have a suggestion for a new feature?

Don't hesitate and open an issue or submit a pull request, contributions are most welcome!

For guidance on setting up a development environment and how to make a contribution to eodag, see the contributing guidelines_.

.. _contributing guidelines: https://github.com/CS-SI/eodag/blob/develop/CONTRIBUTING.rst

License

EODAG is licensed under Apache License v2.0. See LICENSE file for details.

Authors

EODAG has been created by CS GROUP - France <https://www.csgroup.eu/>_.

Credits

EODAG is built on top of amazingly useful open source projects. See NOTICE file for details about those projects and their licenses. Thank you to all the authors of these projects!