STAC REST API#

EODAG as STAC server

EODAG has a STAC compliant REST API. It can serve configured providers data through this STAC API. To run the server, do:

eodag serve-rest

Below is the content of the help message of this command (eodag serve-rest –help):

Usage: eodag serve-rest [OPTIONS]

  Start eodag HTTP server

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

Searching#

After you have launched the server, navigate to its home page. For example, for a local development server launched with eodag serve-rest -f <config> --debug, go to http://127.0.0.1:5000/service-doc. You will see a documentation of the interface.

Available operations are:

  • List product types as collections:

    # All supported product types
http://127.0.0.1:5000/collections

# <provider> only supported product types
http://127.0.0.1:5000/collections/?provider=<provider>

  • Search product:

    http://127.0.0.1:5000/search/?param=value

The supported request parameters are (from STAC API):

  • collections: the product type

  • bbox: the search bounding box defined by: min_lon,min_lat,max_lon,max_lat.

  • datetime: RFC 3339 format datetime. Single, or as interval start/stop.

  • limit: items returned per page

EODAG additional query parameters:

  • provider: preferred provider

  • customParameter: any custom querry parameter supported by the provider

Example URL:

Browsing#

EODAG provides additional catalogs that extend browsing/filtering capabilities:

  • country -> filters items on a specific area defined by selected country

  • year
    • month

      • day -> filters items using specified time interval

  • cloud_cover -> filters items with specified maximum cloud cover

Example URLs:

Browsing over catalogs can be experienced connecting EODAG STAC API to STAC-Browser. Simply run:

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

(EODAG_LOGGING environment variable definition will increase eodag logging level, and accepts values: 1, 2, or 3 for maximum level)

And browse http://127.0.0.1:5001:

STAC browser example

Example#

# 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"
"S3_EFR"
"S3_ERR"
"S3_LAN"
"S3_OLCI_L2LFR"
"S3_OLCI_L2LRR"
"S3_SLSTR_L1RBT"
"S3_SLSTR_L2LST"

# 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 ".context.matched"
6

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

# get download link
$ curl "http://127.0.0.1:5000/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/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/S2_MSI_L1C/country/FRA/year/2021/month/01/day/25/cloud_cover/10/items/S2A_MSIL1C_20210125T105331_N0209_R051_T31UCR_20210125T130733/download"