sentinelsat

Sentinelsat makes searching, downloading and retrieving the metadata of Sentinel satellite images from the Copernicus Open Access Hub easy.

It offers an easy-to-use command line interface

sentinel search --sentinel 2 --cloud 30 user password search_polygon.geojson

and a powerful Python API.

from sentinelsat import SentinelAPI, read_geojson, geojson_to_wkt

api = SentinelAPI('user', 'password')
footprint = geojson_to_wkt(read_geojson('search_polygon.geojson'))
products = api.query(footprint,
                     producttype='SLC',
                     orbitdirection='ASCENDING')
api.download_all(products)

Documentation is published at http://sentinelsat.readthedocs.io/.

Installation

Sentinelsat depends on homura, which depends on PycURL, so you might need to install some dependencies on your system.

Install sentinelsat through pip:

pip install sentinelsat

The documentation contains examples on how to install the dependencies for Ubuntu, Fedora and Windows.

Usage

Sentinelsat provides a Python API and a command line interface to search, download and retrieve the metadata for Sentinel products.

Python Library

# connect to the API
from sentinelsat.sentinel import SentinelAPI, read_geojson, geojson_to_wkt
api = SentinelAPI('user', 'password', 'https://scihub.copernicus.eu/dhus')

# download single scene by known product id
api.download(<product_id>)

# search by polygon, time, and SciHub query keywords
footprint = geojson_to_wkt(read_geojson('map.geojson'))
products = api.query(footprint,
                     '20151219', date(2015, 12, 29),
                     platformname = 'Sentinel-2',
                     cloudcoverpercentage = '[0 TO 30]')

# download all results from the search
api.download_all(products)

# GeoJSON FeatureCollection containing footprints and metadata of the scenes
api.to_geojson(products)

# GeoPandas GeoDataFrame with the metadata of the scenes and the footprints as geometries
api.to_geopandas(products)

# Get basic information about the product: its title, file size, MD5 sum, date, footprint and
# its download url
api.get_product_odata(<product_id>)

# Get the product's full metadata available on the server
api.get_product_odata(<product_id>, full=True)

Valid search query keywords can be found at the ESA SciHub documentation.

Command Line Interface

A basic search query consists of a search polygon as well as the username and password to access the SciHub.

sentinel search [OPTIONS] <user> <password> <geojson>

Search areas are provided as GeoJSON polygons, 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.

Example

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

sentinel search -s 20150101 -e 20151231 -d \
--producttype SLC -q "orbitdirection=Descending" \
-u "https://scihub.copernicus.eu/dhus" <user> <password> poly.geojson

Options

-s	--start	TEXT	Start date of the query in the format YYYYMMDD.
-e	--end	TEXT	End date of the query in the format YYYYMMDD.
-d	--download		Download all results of the query.
-f	--footprints		Create geojson file search_footprints.geojson with footprints of the query result.
-p	--path	PATH	Set the path where the files will be saved.
-q	--query	TEXT	Extra search keywords you want to use in the query. Separate keywords with comma. Example: 'producttype=GRD,polarisationmode=HH'.
-u	--url	TEXT	Define another API URL. Default URL is 'https://scihub.copernicus.eu/apihub/'.
	--md5		Verify the MD5 checksum and write corrupt product ids and filenames to corrupt_scenes.txt.
	--sentinel		Limit search to a Sentinel satellite (constellation).
	--instrument		Limit search to a specific instrument on a Sentinel satellite.
	--producttype		Limit search to a Sentinel product type.
-c	--cloud	INT	Maximum cloud cover in percent. (Automatically sets --sentinel2)
	--help		Show help message and exit.
	--version		Show version number and exit.

Tests

To run the tests on sentinelsat:

git clone https://github.com/ibamacsr/sentinelsat.git
cd sentinelsat
pip install -e .[test]
py.test -v -m "not homura"

By default, prerecorded responses to SciHub queries are used to not be affected by Scihub's downtime. The only exceptions are downloading tests, which can be disabled with -m "not homura". To allow the tests to run actual queries against SciHub set the environment variables

and add --vcr disable to py.test arguments. To update the recordings use --vcr record_new or --vcr reset_all.

Documentation

To build the documentation:

git clone https://github.com/ibamacsr/sentinelsat.git
cd sentinelsat
pip install -e .[docs]
cd docs
make html

The full documentation is also published at http://sentinelsat.readthedocs.io/.

Changelog

See CHANGELOG.

Contributors

• Wille Marcel
• Kersten Clauss
• Martin Valgur
• Jonas Sølvsteen
• Luca Delucchi

License

GPLv3+