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

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


Utility pack to search and download Sentinel-1 imagery.

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

.. code-block:: console

    pip install sentinelsat

Usage
=====

Sentinelsat provides a Python Library and a Command Line Interface to search and
download Sentinel-1 products.

Command Line Interface
----------------------

Search
^^^^^^

.. code-block:: console

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

Search for Sentinel-1 products and, optionally, download all the results.
Beyond your scihub user and password, you must pass a geojson file
containing the polygon of the area that you want to search for. If you
don't especify the start and end dates, it will search in the last 24
hours.

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

Download
^^^^^^^^

.. code-block:: console

    sentinel download [OPTIONS] <user> <password> <productid>

Download a Sentinel-1 Product. It just needs your scihub user and password and
the id of the product you want to download.

Options:

-p, --path PATH  Set the path where the file will be saved.


Python Library
--------------

Connect to the API:

.. code-block:: python

    from sentinelsat.sentinel import SentinelAPI
    api = SentinelAPI('user', 'password')

If you know the id of the product you want to download, you can download it by using:

.. code-block:: python

    api.download(<product_id>)

It is possible to hide the progress report, disable resume and auto_retry, and
pass any other keyword argument understood by the underlying homura library, e.g.:

.. code-block:: python

    api.download(<product_id>, show_progress=False, max_rst_retries=2)

You can also use the id to get information about the product, including id, title, size, footprint and download url:

.. code-block:: python

    api.get_product_info(<product_id>)

You can search products by specifying the coordinates of the area and a date interval:

.. code-block:: python

    api.query('0 0,1 1,0 1,0 0', '20150531', '20150612')

You can query by using date or datetime objects too.

.. code-block:: python

    api.query('0 0,1 1,0 1,0 0', datetime(2015, 5, 31, 12, 5), date(2015, 6, 12))

If you don't specify the start and end dates, it will query in the last 24 hours.

Beyond area and date parameters, you can use any search keywords accepted by the SciHub API, for example:

.. code-block:: python

    api.query('0 0,1 1,0 1,0 0', producttype='SLC')

See the `SciHub User Guide <https://scihub.esa.int/twiki/do/view/SciHubUserGuide/3FullTextSearch#Search_Keywords>`_
for all the Search Keywords.

To download all the results of your query, use:

.. code-block:: python

    api.download_all()

The download from https://scihub.esa.int will fail if the server certificate
cannot be verified because no default CA bundle is defined, as on Windows, or
when the CA bundle is outdated. In most cases the easiest solution is to
install or update `certifi <https://pypi.python.org/pypi/certifi>`_:

.. code-block:: console

    pip install -U certifi

You can also override the the path setting to the PEM file of the CA bundle using
the ``pass_through_opts`` keyword argument when calling ``api.download()`` or
``api.download_all()``:

.. code-block:: python

    from pycurl import CAINFO
    api.download_all(pass_through_opts={CAINFO: 'path/to/my/cacert.pem'})

To get a geojson FeatureCollection containing the footprints and metadata for the search results of the query, use:

.. code-block:: python

    api.get_footprints()


Contributors
=======

* Wille Marcel
* Kersten Clauss
* Michele Citterio

License
=======

GPLv3+
