Skip to main content

Utility to search and download Copernicus Sentinel satellite images

Project description

sentinelsat

https://badge.fury.io/py/sentinelsat.svg https://travis-ci.org/sentinelsat/sentinelsat.svg https://codecov.io/gh/sentinelsat/sentinelsat/branch/master/graph/badge.svg Documentation gitter.im chat https://zenodo.org/badge/36093931.svg

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

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

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

Install sentinelsat through pip:

pip install sentinelsat

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,
                     date = ('20151219', date(2015, 12, 29)),
                     platformname = 'Sentinel-2',
                     cloudcoverpercentage = (0, 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 Copernicus Open Access Hub documentation.

Command Line Interface

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 <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.

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

Options

-u

--user

TEXT

Username [required]

-p

--password

TEXT

Password [required]

--url

TEXT

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

-s

--start

TEXT

Start date of the query in the format YYYYMMDD.

-e

--end

TEXT

End date of the query in the format YYYYMMDD.

-g

--geometry

PATH

Search area geometry as GeoJSON file.

--uuid

TEXT

Select a specific product UUID instead of a query. Multiple UUIDs can separated by commas.

--name

TEXT

Select specific product(s) by filename. Supports wildcards.

--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. (requires –sentinel to be 2 or 3)

-o

--order-by

TEXT

Comma-separated list of keywords to order the result by. Prefix ‘-’ for descending order.

-l

--limit

INT

Maximum number of results to return. Defaults to no limit.

-d

--download

Download all results of the query.

--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’.

-f

--footprints

Create geojson file search_footprints.geojson with footprints of the query result.

--md5

Verify the MD5 checksum and write corrupt product ids and filenames to corrupt_scenes.txt.

--version

Show version number and exit.

--help

Show help message and exit.

Tests

To run the tests on sentinelsat:

git clone https://github.com/sentinelsat/sentinelsat.git
cd sentinelsat
pip install -e .[test]
py.test -v

By default, prerecorded responses to Copernicus Open Access Hub queries are used to not be affected by its downtime. To allow the tests to run actual queries against the Copernicus Open Access Hub set the environment variables

export SENTINEL_USER=<username>
export SENTINEL_PASSWORD=<password>

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

Documentation

To build the documentation:

git clone https://github.com/sentinelsat/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

We invite anyone to participate by contributing code, reporting bugs, fixing bugs, writing documentation and tutorials and discussing the future of this project. Please check CONTRIBUTE.rst.

License

GPLv3+

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

sentinelsat-0.12.tar.gz (2.2 MB view hashes)

Uploaded Source

Built Distribution

sentinelsat-0.12-py2.py3-none-any.whl (23.9 kB view hashes)

Uploaded Python 2 Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page