CLI User Guide

CLI User Guide#

Make sure you correctly followed instructions on Configure EODAG.

Then you can start playing with it:

Run eodag --help to display all the available options and commands:

$ eodag --help
Usage: eodag [OPTIONS] COMMAND1 [ARGS]... [COMMAND2 [ARGS]...]...

  Earth Observation Data Access Gateway: work on EO products from any provider

Options:
  -v, --verbose  Control the verbosity of the logs. For maximum verbosity,
                 type -vvv
  --help         Show this message and exit.

Commands:
  discover  Fetch providers to discover product types
  download  Download a list of products from a serialized search result...
  list      List supported product types
  search    Search satellite images by their product types, instrument,...
  version   Print eodag version and exit

Each command has its own help, see for instance the help of the list command with eodag list --help.
By default the command line interface of eodag is set to the minimum verbosity level. You can print more log messages by adding -v to eodag master command. The more v given (up to 3), the more verbose the tool is. This feature comes in handy when you want to inspect an error or an unexpected behaviour. 4 different verbosity levels are offered to you:

eodag list
eodag -v list
eodag -vv list
eodag -vvv list

Search#

$ eodag search --help
Usage: eodag search [OPTIONS]

  Search satellite images by their product types, instrument, platform,
  platform identifier, processing level or sensor type. It is mandatory to
  provide at least one of the previous criteria for eodag to perform a search.
  Optionally crunch the search results before storing them in a geojson file

Options:
  -f, --conf PATH                 File path to the user configuration file
                                  with its credentials, default is
                                  ~/.config/eodag/eodag.yml
  -l, --locs PATH                 File path to the user locations
                                  configuration file, default is
                                  ~/.config/eodag/locations.yml
  -b, --box <FLOAT FLOAT FLOAT FLOAT>...
                                  Search for a product on a bounding box,
                                  providing its minlon, minlat, maxlon and
                                  maxlat (in this order). NOTE: This argument
                                  is mutually exclusive with  arguments:
                                  [geom].
  -g, --geom TEXT                 Search for a product on a geometry,
                                  providing its WKT representation. NOTE: This
                                  argument is mutually exclusive with
                                  arguments: [box].
  -s, --start [%Y-%m-%d|%Y-%m-%dT%H:%M:%S|%Y-%m-%d %H:%M:%S]
                                  Start sensing time in ISO8601 format (e.g.
                                  '1990-11-26', '1990-11-26T14:30:10'). UTC is
                                  assumed
  -e, --end [%Y-%m-%d|%Y-%m-%dT%H:%M:%S|%Y-%m-%d %H:%M:%S]
                                  End sensing time in ISO8601 format (e.g.
                                  '1990-11-26', '1990-11-26T14:30:10'). UTC is
                                  assumed
  -c, --cloudCover INTEGER RANGE  Maximum cloud cover percentage needed for
                                  the product  [0<=x<=100]
  -p, --productType TEXT          The product type to search
  -i, --instrument TEXT           Search for products matching this instrument
  -P, --platform TEXT             Search for products matching this platform
  -t, --platformSerialIdentifier TEXT
                                  Search for products originating from the
                                  satellite identified by this keyword
  -L, --processingLevel TEXT      Search for products matching this processing
                                  level
  -S, --sensorType TEXT           Search for products matching this type of
                                  sensor
  --id TEXT                       Search for the product identified by this id
  --locations TEXT                Custom query-string argument(s) to select
                                  locations. Format
                                  :'key1=value1&key2=value2'. Example:
                                  --locations country=FRA&continent=Africa
  -q, --query TEXT                Custom query-string argument(s). Format
                                  :'key1=value1&key2=value2'
  --cruncher [FilterLatestByName|FilterLatestIntersect|FilterOverlap|FilterProperty|FilterDate]
                                  A cruncher to be applied to search results.
                                  Repeat option many times to apply many
                                  crunchers
  --cruncher-args <TEXT TEXT TEXT>...
                                  Named arguments acting as the parameters of
                                  a cruncher. Enter it like this: --cruncher-
                                  args <CruncherName> <arg-name> <arg-value>.
                                  Repeat option many times to give many args
                                  to a cruncher
  --storage FILE                  Path to the file where to store search
                                  results (.geojson extension will be
                                  automatically appended to the filename).
                                  DEFAULT: search_results.geojson
  --items INTEGER                 The number of items to return. Eodag is
                                  bound to whatever limitation the providers
                                  have on the number of results they return.
                                  This option allows to control how many items
                                  eodag should request [default: 20]
  --page INTEGER                  Retrieve the given page  [default: 1]
  --all                           Retrieve ALL the products that match the
                                  search criteria. It collects products by
                                  iterating over the results pages until no
                                  more products are available.At each
                                  iteration, the maximum number of items
                                  searched is either 'items' if set, or a
                                  maximum value defined internally for the
                                  requested provider, or a default maximum
                                  value equals to 50.
  --count                         Make a count request together with search
                                  (Enabling count will significantly slow down
                                  search requests for some providers, and
                                  might be unavailable for someothers).
  --help                          Show this message and exit.

To search for products and crunch the results of the search:

eodag search \
--conf my_conf.yml \
--box 1 43 2 44 \
--start 2018-01-01 --end 2018-01-31 \
--productType S2_MSI_L1C \
--all \
--storage my_search.geojson

The request above searches for S2_MSI_L1C product types in a given bounding box, in January 2018. The command fetches internally all the products that match these criteria. Without --all, it would only fetch the products found on the first result page. It finally saves the results in a GeoJSON file.

You can pass arguments to a cruncher on the command line by doing this (example with using FilterOverlap cruncher which takes minimum_overlap as argument):

eodag search -f my_conf.yml -b 1 43 2 44 -s 2018-01-01 -e 2018-01-31 -p S2_MSI_L1C --all \
             --cruncher FilterOverlap \
             --cruncher-args FilterOverlap minimum_overlap 10

The request above means : “Give me all the products of type S2_MSI_L1C, use FilterOverlap to keep only those products that are contained in the bbox I gave you, or whose spatial extent overlaps at least 10% (minimum_overlap) of the surface of this bbox”.

You can use eaodag search with custom query parameters. Custom query parameters will be used as is in the query string search sent to the provider. For instance, if you want to add foo=1 and bar=2 to the previous query:

eodag search -f my_conf.yml -b 1 43 2 44 -s 2018-01-01 -e 2018-01-31 -p S2_MSI_L1C \
             --cruncher FilterOverlap \
             --cruncher-args FilterOverlap minimum_overlap 10 \
             --query "foo=1&bar=2"

If the product type is not known, it can also be guessed by EODAG during the search based on parameters in the search request. The possible parameters are:
- instrument (e.g. MSI)
- platform (e.g. SENTINEL2)
- platformSerialIdentifier (e.g. S2A)
- processingLevel (e.g. L1)
- sensorType (e.g. OPTICAL)
- keywords (e.g. SENTINEL2 L1C SAFE), which is case insensitive and ignores - or _ characters

For example, the following search request will first search for a product type for platform SENTINEL2 and processingLevel L1 (there are several product types matching these criteria, e.g., S2_MSI_L1C) and then use this product type to execute the actual search.

eodag search \
--platform SENTINEL2 \
--processingLevel L1 \
--box 1 43 2 44 \
--start 2021-03-01 --end 2021-03-31

Download#

$ eodag download --help
Usage: eodag download [OPTIONS]

  Download a list of products from a serialized search result or STAC items
  URLs/paths

  Examples:

    eodag download --search-results /path/to/search_results.geojson

    eodag download --stac-item https://example.com/stac/item1.json --stac-item
    /path/to/item2.json

Options:
  --search-results FILE   Path to a serialized search result
  --stac-item TEXT        URL/path of a STAC item to download (multiple values
                          accepted)
  -f, --conf PATH         File path to the user configuration file with its
                          credentials, default is ~/.config/eodag/eodag.yml
  --quicklooks            Download only quicklooks of products instead full
                          set of files
  --output-dir DIRECTORY  Products or quicklooks download directory (Default:
                          local temporary directory)
  --help                  Show this message and exit.

To download the result of a previous call to search:

eodag download --conf my_conf.yml --search-results my_search.geojson

To download STAC items from their URL or path:

eodag download --stac-item https://foo/collections/bar/items/item-1-id --stac-item /path/to/item2.json

Using commands chaining, download can also directly be executed after a search in a single command:

eodag search --productType S2_MSI_L1C --bbox 1 43 2 44 --start 2025-03-01 download

Product Types#

$ eodag list --help
Usage: eodag list [OPTIONS]

  List supported product types

Options:
  -p, --provider TEXT             List product types supported by this
                                  provider
  -i, --instrument TEXT           List product types originating from this
                                  instrument
  -P, --platform TEXT             List product types originating from this
                                  platform
  -t, --platformSerialIdentifier TEXT
                                  List product types originating from the
                                  satellite identified by this keyword
  -L, --processingLevel TEXT      List product types of processing level
  -S, --sensorType TEXT           List product types originating from this
                                  type of sensor
  --no-fetch                      Do not fetch providers for new product types
  --help                          Show this message and exit.

To list all available product types and supported providers:

eodag list

To list available product types on a specified supported provider:

eodag list -p creodias

By default, list command will also fetch for new product types, which may be slow depending on the network status. To skip fetching, use the following option:

eodag list --no-fetch

EODAG can fetch providers (all or only a given one) to discover available product types, using the following command. It will store result in a JSON file (defaults to ext_product_types.json):

$ eodag discover --help
Usage: eodag discover [OPTIONS]

  Fetch providers to discover product types

Options:
  -p, --provider TEXT  Fetch only the given provider
  --storage FILE       Path to the file where to store external product types
                       configuration (.json extension will be automatically
                       appended to the filename). DEFAULT:
                       ext_product_types.json
  --help               Show this message and exit.

Examples:

eodag discover
eodag discover -p planetary_computer
eodag discover -p planetary_computer --storage my_product_types_conf.json

This file can then be used in EODAG using the environment variable EODAG_EXT_PRODUCT_TYPES_CFG_FILE.

Please note that if you did not customize EODAG with new providers settings, this command should not be useful. For more information on the product types discovery mechanism, please see Python API User Guide / Providers and products / Product types discovery.

CLI User Guide

Contents

CLI User Guide#

Search#

Download#

Product Types#