Command Line Interface¶

Sentinelsat provides a CLI sentinelsat to query and download multiple or single images.

Quickstart¶

A basic search query consists of a search polygon as well as the username and password to access the Copernicus Open Access Hub.

sentinelsat -u <user> -p <password> -g <search_polygon.geojson>

For convenience and added security, there are two ways you can store your credentials and omit them from the command line call. You can set username, password and DHuS URL as environment variables.

export DHUS_USER="<user>"
export DHUS_PASSWORD="<password>"
export DHUS_URL="<api_url>"

Alternatively, you can add them to a file .netrc in your user home directory.

machine scihub.copernicus.eu
login <user>
password <password>

Environment variables take precedence over .netrc. The above command then becomes

sentinelsat -g <search_polygon.geojson>

Search areas (i.e. search_polygon.geojson ) are provided as GeoJSON files, which can be created with QGIS or geojson.io. If you do not specify a start and end date only products published in the last 24 hours will be queried.

Start and end dates refer to the acquisition date given by the beginPosition of the products, i.e. the start of the acquisition time.

Sentinel-1¶

Search and download all Sentinel-1 scenes of type SLC over a search polygon, in descending orbit for the year 2015.

sentinelsat -u <user> -p <password> -g <search_polygon.geojson> -s 20150101 -e 20151231 -d \
--producttype SLC -q "orbitdirection=Descending" \
--url "https://scihub.copernicus.eu/dhus"

Download a single Sentinel-1 GRDH scene covering Santa Claus Village in Finland on Christmas Eve 2015.

sentinelsat -u <user> -p <password> -d --uuid a9048d1d-fea6-4df8-bedd-7bcb212be12e

or by using its filename

sentinelsat -u <user> -p <password> -d --name S1A_EW_GRDM_1SDH_20151224T154142_20151224T154207_009186_00D3B0_C71E

Sentinel-2¶

Search and download Sentinel-2 scenes for January 2016 with a maximum cloud cover of 40%.

sentinelsat -u <user> -p <password> -g <search_polygon.geojson> -s 20160101 -e 20160131 --sentinel 2 --cloud 40 -d

Download all Sentinel-2 scenes published in the last 24 hours.

sentinelsat -u <user> -p <password> -g <search_polygon.geojson> --sentinel 2 -d

Options¶

-u <username>, --user <username>¶

Username. Required.

Can also be set via the DHUS_USER environment variable or with a .netrc file.

-p <password>, --password <password>¶

Password. Required.

Can also be set with the DHUS_PASSWORD environment variable or with a .netrc file.

--url <api_url>¶

Define another API URL. Default is ‘https://scihub.copernicus.eu/apihub/’.

Can also be set with the DHUS_URL environment variable.

-s <date>, --start <date>¶: Start date of the query in the format YYYYMMDD or one of the other formats listed here.

-e <date>, --end <date>¶: End date of the query in the format YYYYMMDD or one of the other formats listed here.

-g <file>, --geometry <file>¶: Search area geometry as GeoJSON file.

--uuid¶: Select a specific product UUID instead of a query. Multiple UUIDs can separated by commas.

--name <name>¶: Select specific product(s) by filename. Supports wildcards, such as S1A_IW*20151224* to find all Sentinel-1A scenes from 24th of December 2015 without restricting the result to a search area.

--sentinel <number>¶: Limit search to a Sentinel satellite (constellation).

--instrument <instrument name>¶: Limit search to a specific instrument on a Sentinel satellite.

--producttype <product type>¶: Limit search to a Sentinel product type. List of valid product types can be found under producttype here.

-c <percent>, --cloud <percent>¶: Maximum cloud cover in percent. (requires --sentinel to be 2 or 3)

-o <keywords>, --order-by <keywords>¶: Comma-separated list of keywords to order the result by. Prefix with ‘-’ for descending order.

-l <number>, --limit <number>¶: Maximum number of results to return. Defaults to no limit.

-d, --download¶: Download all results of the query.

--path <directory>¶: Set the directory where the files will be saved.

-q <query>, --query <query>¶

Extra search keywords you want to use in the query. Separate keywords with comma.

ESA maintains a list of valid search keywords that can be used.

Example: producttype=GRD,polarisationmode=HH.

-f, --footprints¶: Create geojson file search_footprints.geojson with footprints of the query result.

-d, --debug¶: Print debug log messages.

--include-pattern¶: Glob pattern to filter files (within each product) to be downloaded.

--exclude-pattern¶: Glob pattern to filter files (within each product) to be excluded from the downloaded.

--info¶: Display DHuS server information.

--version¶: Show version number and exit.

-h, --help¶: Show help message and exit.

The options --sentinel, --instrument and --producttype are mutually exclusive and follow a hierarchy from most specific to least specific, i.e. --producttype > --instrument > --sentinel. Only the most specific option will be included in the search when multiple ones are given.

Also the --include-pattern and --exclude-patter options are mutually exclusive. If used together the CLI program exists with an error.