sentinelsat

Makes searching, downloading and retrieving the metadata of Sentinel satellite images from the Copernicus Open Access Hub easy.
https://github.com/sentinelsat/sentinelsat

Category: Sustainable Development
Sub Category: Environmental Satellites

Keywords

copernicus esa geographic-data hacktoberfest open-data remote-sensing satellite-imagery sentinel

Keywords from Contributors

earth-observation sar cython gdal geospatial-data research qgis-processing radar closember geospatial-analysis

Last synced: about 1 hour ago
JSON representation

Repository metadata

Search and download Copernicus Sentinel satellite images

README.rst

          sentinelsat
===========

⚠️ Sentinelsat is currently not functional for downloading from the CDSE ⚠️
=================================================================================

The `Copernicus Open Access Hub (aka SciHub) `_, that Sentinelsat was primarily built for, is permanently closed.

.. image:: readme-note-scihub-closed.png

The official successor data distribution system, the `Copernicus Data Space Ecosystem (CDSE) `_,
uses different API logic that Sentinelsat does not (yet?) support. Contributions are welcome to change that, please check issues and discussions
for ongoing efforts or alternatives.

Sentinelsat can still be used against `other data hubs `_ powered by the `DHuS software `_.


Legacy project documentation
============================

Please note that examples referencing the old Copernicus Open Access Hub are not working anymore. 

.. image:: https://readthedocs.org/projects/sentinelsat/badge/?version=stable
    :target: http://sentinelsat.readthedocs.io/en/stable/?badge=stable
    :alt: Documentation

.. image:: https://badge.fury.io/py/sentinelsat.svg
    :target: http://badge.fury.io/py/sentinelsat
    :alt: PyPI package

.. image:: https://github.com/sentinelsat/sentinelsat/actions/workflows/ci.yaml/badge.svg
    :target: https://github.com/sentinelsat/sentinelsat/actions
    :alt: GitHub Actions

.. image:: https://codecov.io/gh/sentinelsat/sentinelsat/branch/main/graph/badge.svg
    :target: https://codecov.io/gh/sentinelsat/sentinelsat
    :alt: codecov.io code coverage

.. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.595961.svg
   :target: https://doi.org/10.5281/zenodo.595961
   :alt: Zenodo DOI

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

.. code-block:: bash

  sentinelsat -u  -p  --location Berlin --sentinel 2 --cloud 30 --start NOW-1MONTH

and a powerful Python API.

.. code-block:: python

  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',
                       limit=10)
  api.download_all(products)



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

Installation
============

Install ``sentinelsat`` through pip:

.. code-block:: bash

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

.. code-block:: python

  from sentinelsat import SentinelAPI, read_geojson, geojson_to_wkt
  from datetime import date

  # connect to the API
  api = SentinelAPI('user', 'password', 'dhus-hub-url')

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

  # search by polygon, time, and Hub 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_geodataframe(products)

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

  # Get the product's full metadata available on the server
  api.get_product_odata(, 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 area geometry as well as the username and
password to access the Copernicus Open Access Hub.

.. code-block:: bash

  sentinelsat -u  -p  -g 

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

Example
^^^^^^^

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

.. code-block:: bash

  sentinelsat -u  -p  -g  -s 20150101 -e 20151231 -d \
  --producttype SLC -q "orbitdirection=Descending" \
  --url "https://apihub.copernicus.eu/apihub"

Username, password and DHuS URL can also be set via environment variables for convenience.

.. code-block:: bash
 
  # same result as query above
  export DHUS_USER=""
  export DHUS_PASSWORD=""
  export DHUS_URL="https://apihub.copernicus.eu/apihub"

  sentinelsat -g  -s 20150101 -e 20151231 -d \
  --producttype SLC -q "orbitdirection=Descending"

Options
^^^^^^^

.. list-table::

   * - -u
     - --user
     - TEXT
     - Username [required] (or environment variable DHUS_USER)
   * - -p
     - --password
     - TEXT
     - Password [required] (or environment variable DHUS_PASSWORD)
   * - 
     - --url
     - TEXT
     - Define another API URL. Default URL is 'https://apihub.copernicus.eu/apihub/'.
   * - -s
     - --start
     - TEXT
     - Start date of the query in the format YYYYMMDD or an expression like NOW-1DAY.
   * - -e
     - --end
     - TEXT
     - End date of the query.
   * - -g
     - --geometry
     - PATH
     - Search area geometry as GeoJSON file.
   * -  
     - --uuid
     - TEXT
     - Select a specific product UUID. Can be set more than once.
   * -  
     - --name
     - TEXT
     - Select specific product(s) by filename. Supports wildcards. Can be set more than once.
   * -  
     - --sentinel
     - INT
     - Limit search to a Sentinel satellite (constellation).
   * -  
     - --instrument
     - TEXT
     - Limit search to a specific instrument on a Sentinel satellite.
   * -  
     - --producttype
     - TEXT
     - 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.
   * -
     - --fail-fast
     -
     - Skip all other other downloads if one fails.
   * -  
     - --path
     - PATH
     - Set the path where the files will be saved.
   * - -q
     - --query
     - TEXT
     - Extra search keywords you want to use in the query.
       Example: '-q producttype=GRD -q polarisationmode=HH'.
       Repeated keywords are interpreted as an "or" expression.
   * - -f
     - --footprints
     - FILENAME
     - Create a GeoJSON file at the provided path with footprints and metadata of the returned products. Set to '-' for stdout.
   * - 
     - --include-pattern
     - TEXT
     - Glob pattern to filter files (within each product) to be downloaded.
   * - 
     - --exclude-pattern
     - TEXT
     - Glob pattern to filter files (within each product) to be excluded from the downloaded.
   * -  
     - --timeout
     - FLOAT
     - How long to wait for a DataHub response (in seconds, default 60 sec).
   * -
     - --gnss
     -
     - Query orbit products form the GNSS end-point ("https://scihub.copernicus.eu/gnss").
   * -
     - --fmt
     - TEXT
     - Specify a custom format to print results. The format string shall be compatible with the Python "Format Specification Mini-Language".
   * -  
     - --info
     -  
     - Display DHuS server information.
   * -  
     - --version
     -  
     - Show version number and exit.
   * - 
     - --debug
     -  
     - Print debug log messages.
   * - -h
     - --help
     -  
     - Show help message and exit.

Tests
=====

To run the tests on ``sentinelsat``:

.. code-block:: bash

    git clone https://github.com/sentinelsat/sentinelsat.git
    cd sentinelsat
    pip install -e .[dev]
    pytest -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

.. code-block:: bash

    export DHUS_USER=
    export DHUS_PASSWORD=

and add ``--disable-vcr`` to ``pytest`` arguments.
To update the recordings use ``--vcr-record`` with ``once``, ``new_episodes`` or ``all``. See `vcrpy docs `_ for details.


Documentation
=============

To build the documentation:

.. code-block:: bash

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

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


Changelog
=========

See `CHANGELOG `_. You can also use GitHub's compare view to see the `changes in the main branch since last release `_.

Contributors
============

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

For a list of maintainers and contributors please see `AUTHORS.rst `_ and the `contributor graph `_.

License
=======

GPLv3+

        

Owner metadata


GitHub Events

Total
Last Year

Committers metadata

Last synced: 1 day ago

Total Commits: 910
Total Committers: 42
Avg Commits per committer: 21.667
Development Distribution Score (DDS): 0.532

Commits in past year: 20
Committers in past year: 5
Avg Commits per committer in past year: 4.0
Development Distribution Score (DDS) in past year: 0.5

Name Email Commits
Martin Valgur m****r@g****m 426
Fernerkundung k****s@g****m 155
thomasyoung-audet t****t@g****m 53
Wille Marcel w****e@w****r 52
Antonio Valentino a****o@t****t 43
j08lue j****e@g****m 40
Gerald Baier g****r@r****p 23
Luca Delucchi l****e@g****m 18
Antonio Valentino A****o@e****t 17
Fernerkundung 1****g 14
Michele Citterio m****e@c****t 6
valpamp 5****p 6
Malte Krupa m****a@n****e 4
Viktor Bahr v****r@c****e 4
Viktor Bahr v****r@p****t 4
github-actions $****} 4
sdf94 s****4@u****u 4
Florian f****r@g****m 4
Daniel W. S. Almeida d****a@g****m 2
Imran Ibrahimli 3****i 2
Leonard Kinyanjui l****k@g****m 2
Marcus Ackland m****d@k****e 2
Scott Staniewicz s****e@g****m 2
joooeey l****r@g****t 2
unnic n****b@h****m 2
RISHABH BUDHIRAJA r****a@g****m 2
Kersten k****s@p****e 2
Gerald Baier g****r@t****e 1
Martin Bernardi (Laptop) m****i@o****g 1
Schlump s****p@v****e 1
and 12 more...

Committer domains:


Issue and Pull Request metadata

Last synced: 1 day ago

Total issues: 371
Total pull requests: 249
Average time to close issues: 4 months
Average time to close pull requests: about 1 month
Total issue authors: 213
Total pull request authors: 44
Average comments per issue: 4.47
Average comments per pull request: 2.96
Merged pull request: 216
Bot issues: 11
Bot pull requests: 0

Past year issues: 1
Past year pull requests: 3
Past year average time to close issues: N/A
Past year average time to close pull requests: 4 minutes
Past year issue authors: 1
Past year pull request authors: 3
Past year average comments per issue: 0.0
Past year average comments per pull request: 1.33
Past year merged pull request: 1
Past year bot issues: 0
Past year bot pull requests: 0

More stats: https://issues.ecosyste.ms/repositories/lookup?url=https://github.com/sentinelsat/sentinelsat

Top Issue Authors

  • kr-stn (42)
  • j08lue (29)
  • valgur (17)
  • github-actions[bot] (11)
  • Opadera (8)
  • daniel-j-h (7)
  • PhML (4)
  • diogocaribe (4)
  • ghost (4)
  • rohitsharma0201 (4)
  • craigmillernz (4)
  • Kay0777 (3)
  • fpl (3)
  • MrChebur (3)
  • elmerehbi (3)

Top Pull Request Authors

  • valgur (92)
  • kr-stn (58)
  • j08lue (22)
  • avalentino (12)
  • gbaier (8)
  • lucadelu (4)
  • thomasyoung-audet (3)
  • ghost (3)
  • NiklasKeck (2)
  • yepremyana (2)
  • lenniezelk (2)
  • IpsumCapra (2)
  • rbrishabh (2)
  • viktorbahr (2)
  • Andrey-Raspopov (2)

Top Issue Labels

  • question (92)
  • bug (54)
  • enhancement (36)
  • discussion (22)
  • good first issue (22)
  • scihub-issue (21)
  • docs (15)
  • hacktoberfest (12)
  • ci (11)
  • duplicate (7)
  • scihub-replacement (6)
  • invalid (4)
  • stale (4)
  • maintenance (4)
  • curl (3)
  • wontfix (3)

Top Pull Request Labels

  • hacktoberfest-accepted (3)
  • stale (2)
  • docs (2)
  • enhancement (1)
  • bug (1)
  • maintenance (1)
  • ci (1)

Package metadata

pypi.org: sentinelsat

Utility to search and download Copernicus Sentinel satellite images

  • Homepage: https://github.com/sentinelsat/sentinelsat
  • Documentation: https://sentinelsat.readthedocs.io/
  • Licenses: GPLv3+
  • Latest release: 1.2.1 (published about 2 years ago)
  • Last Synced: 2025-04-29T15:37:27.327Z (1 day ago)
  • Versions: 41
  • Dependent Packages: 11
  • Dependent Repositories: 156
  • Downloads: 19,663 Last month
  • Docker Downloads: 1,422
  • Rankings:
    • Dependent packages count: 1.068%
    • Dependent repos count: 1.216%
    • Docker downloads count: 1.661%
    • Average: 1.955%
    • Stargazers count: 2.077%
    • Downloads: 2.325%
    • Forks count: 3.38%
  • Maintainers (2)
proxy.golang.org: github.com/sentinelsat/sentinelsat

pypi.org: frx08-sentinelsat

Utility to search and download Copernicus Sentinel satellite images

  • Homepage: https://github.com/sentinelsat/sentinelsat
  • Documentation: https://frx08-sentinelsat.readthedocs.io/
  • Licenses: GPLv3+
  • Latest release: 1.2.2 (published almost 2 years ago)
  • Last Synced: 2025-04-29T15:37:28.322Z (1 day ago)
  • Versions: 2
  • Dependent Packages: 0
  • Dependent Repositories: 0
  • Downloads: 118 Last month
  • Rankings:
    • Stargazers count: 2.061%
    • Forks count: 3.312%
    • Dependent packages count: 7.253%
    • Average: 13.49%
    • Dependent repos count: 41.333%
  • Maintainers (1)
conda-forge.org: 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 and a powerful Python API.

  • Homepage: https://github.com/sentinelsat/sentinelsat
  • Licenses: GPL-3.0-or-later
  • Latest release: 1.1.1 (published over 3 years ago)
  • Last Synced: 2025-04-29T15:37:31.842Z (1 day ago)
  • Versions: 5
  • Dependent Packages: 2
  • Dependent Repositories: 8
  • Rankings:
    • Forks count: 11.605%
    • Dependent repos count: 12.064%
    • Stargazers count: 13.606%
    • Average: 14.209%
    • Dependent packages count: 19.561%

Dependencies

docs/readthedocs-requirements.txt pypi
  • sphinx >=1.3
requirements.txt pypi
  • click >=7.1
  • geojson >=2
  • geomet *
  • html2text *
  • requests *
  • tqdm >=4.58
.github/workflows/autoblack.yml actions
  • actions/checkout v2 composite
  • actions/setup-python v1 composite
.github/workflows/ci.yaml actions
  • actions/checkout v2 composite
  • actions/setup-python v2 composite
  • codecov/codecov-action v1 composite
  • s-weigand/setup-conda v1 composite
.github/workflows/live-testing.yaml actions
  • actions/checkout v2 composite
  • actions/setup-python v2 composite
  • actions/upload-artifact v2 composite
.github/workflows/publish.yml actions
  • actions/checkout v2 composite
  • actions/setup-python v2 composite
  • pypa/gh-action-pypi-publish release/v1 composite
pyproject.toml pypi
setup.py pypi

Score: 20.618195199269902