sentinelsat
===========
.. 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
<http://www.esa.int/Our_Activities/Observing_the_Earth/Copernicus/Overview4>`_
satellite images from the
`Copernicus Open Access Hub <https://scihub.copernicus.eu/>`_ easy.
It offers an easy-to-use command line interface
.. code-block:: bash
sentinelsat -u <user> -p <password> --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', 'https://apihub.copernicus.eu/apihub')
# download single scene by known product id
api.download(<product_id>)
# 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(<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
<https://scihub.copernicus.eu/userguide/3FullTextSearch>`_.
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 <user> -p <password> -g <geojson>
Search areas are provided as GeoJSON files, which can be created with
`QGIS <http://qgis.org/en/site/>`_ or `geojson.io <http://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 <user> -p <password> -g <search_polygon.geojson> -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="<user>"
export DHUS_PASSWORD="<password>"
export DHUS_URL="https://apihub.copernicus.eu/apihub"
sentinelsat -g <search_polygon.geojson> -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=<username>
export DHUS_PASSWORD=<password>
and add ``--disable-vcr`` to ``pytest`` arguments.
To update the recordings use ``--vcr-record`` with ``once``, ``new_episodes`` or ``all``. See `vcrpy docs <https://vcrpy.readthedocs.io/en/latest/usage.html#record-modes>`_ 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 <CHANGELOG.rst>`_. You can also use GitHub's compare view to see the `changes in the main branch since last release <https://github.com/sentinelsat/sentinelsat/compare/v1.2.1...main>`_.
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 <CONTRIBUTE.rst>`_.
For a list of maintainers and contributors please see `AUTHORS.rst <AUTHORS.rst>`_ and the `contributor graph <https://github.com/sentinelsat/sentinelsat/graphs/contributors>`_.
License
=======
GPLv3+
Raw data
{
"_id": null,
"home_page": "https://github.com/sentinelsat/sentinelsat",
"name": "sentinelsat",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "copernicus,sentinel,esa,satellite,download,GIS",
"author": "Kersten Clauss",
"author_email": "sentinelsat@krstn.eu",
"download_url": "https://files.pythonhosted.org/packages/9a/a2/d8e8ccb8d8042a28ae132074a02091932499cc8f5ebc4072b1677725c179/sentinelsat-1.2.1.tar.gz",
"platform": null,
"description": "sentinelsat\n===========\n\n.. image:: https://readthedocs.org/projects/sentinelsat/badge/?version=stable\n :target: http://sentinelsat.readthedocs.io/en/stable/?badge=stable\n :alt: Documentation\n\n.. image:: https://badge.fury.io/py/sentinelsat.svg\n :target: http://badge.fury.io/py/sentinelsat\n :alt: PyPI package\n\n.. image:: https://github.com/sentinelsat/sentinelsat/actions/workflows/ci.yaml/badge.svg\n :target: https://github.com/sentinelsat/sentinelsat/actions\n :alt: GitHub Actions\n\n.. image:: https://codecov.io/gh/sentinelsat/sentinelsat/branch/main/graph/badge.svg\n :target: https://codecov.io/gh/sentinelsat/sentinelsat\n :alt: codecov.io code coverage\n\n.. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.595961.svg\n :target: https://doi.org/10.5281/zenodo.595961\n :alt: Zenodo DOI\n\nSentinelsat makes searching, downloading and retrieving the metadata of `Sentinel\n<http://www.esa.int/Our_Activities/Observing_the_Earth/Copernicus/Overview4>`_\nsatellite images from the\n`Copernicus Open Access Hub <https://scihub.copernicus.eu/>`_ easy.\n\nIt offers an easy-to-use command line interface\n\n.. code-block:: bash\n\n sentinelsat -u <user> -p <password> --location Berlin --sentinel 2 --cloud 30 --start NOW-1MONTH\n\nand a powerful Python API.\n\n.. code-block:: python\n\n from sentinelsat import SentinelAPI, read_geojson, geojson_to_wkt\n\n api = SentinelAPI('user', 'password')\n footprint = geojson_to_wkt(read_geojson('search_polygon.geojson'))\n products = api.query(footprint,\n producttype='SLC',\n orbitdirection='ASCENDING',\n limit=10)\n api.download_all(products)\n\n\n\nDocumentation is published at http://sentinelsat.readthedocs.io/.\n\nInstallation\n============\n\nInstall ``sentinelsat`` through pip:\n\n.. code-block:: bash\n\n pip install sentinelsat\n\nUsage\n=====\n\nSentinelsat provides a Python API and a command line interface to search,\ndownload and retrieve the metadata for Sentinel products.\n\nPython Library\n--------------\n\n.. code-block:: python\n\n from sentinelsat import SentinelAPI, read_geojson, geojson_to_wkt\n from datetime import date\n\n # connect to the API\n api = SentinelAPI('user', 'password', 'https://apihub.copernicus.eu/apihub')\n\n # download single scene by known product id\n api.download(<product_id>)\n\n # search by polygon, time, and Hub query keywords\n footprint = geojson_to_wkt(read_geojson('map.geojson'))\n products = api.query(footprint,\n date = ('20151219', date(2015, 12, 29)),\n platformname = 'Sentinel-2',\n cloudcoverpercentage = (0, 30))\n\n # download all results from the search\n api.download_all(products)\n\n # GeoJSON FeatureCollection containing footprints and metadata of the scenes\n api.to_geojson(products)\n\n # GeoPandas GeoDataFrame with the metadata of the scenes and the footprints as geometries\n api.to_geodataframe(products)\n\n # Get basic information about the product: its title, file size, MD5 sum, date, footprint and\n # its download url\n api.get_product_odata(<product_id>)\n\n # Get the product's full metadata available on the server\n api.get_product_odata(<product_id>, full=True)\n\nValid search query keywords can be found at the `Copernicus Open Access Hub documentation\n<https://scihub.copernicus.eu/userguide/3FullTextSearch>`_.\n\nCommand Line Interface\n----------------------\n\nA basic search query consists of a search area geometry as well as the username and\npassword to access the Copernicus Open Access Hub.\n\n.. code-block:: bash\n\n sentinelsat -u <user> -p <password> -g <geojson>\n\nSearch areas are provided as GeoJSON files, which can be created with\n`QGIS <http://qgis.org/en/site/>`_ or `geojson.io <http://geojson.io>`_.\nIf you do not specify a start and end date only products published in the last\n24 hours will be queried.\n\nExample\n^^^^^^^\n\nSearch and download all Sentinel-1 scenes of type SLC, in descending\norbit, for the year 2015.\n\n.. code-block:: bash\n\n sentinelsat -u <user> -p <password> -g <search_polygon.geojson> -s 20150101 -e 20151231 -d \\\n --producttype SLC -q \"orbitdirection=Descending\" \\\n --url \"https://apihub.copernicus.eu/apihub\"\n\nUsername, password and DHuS URL can also be set via environment variables for convenience.\n\n.. code-block:: bash\n \n # same result as query above\n export DHUS_USER=\"<user>\"\n export DHUS_PASSWORD=\"<password>\"\n export DHUS_URL=\"https://apihub.copernicus.eu/apihub\"\n\n sentinelsat -g <search_polygon.geojson> -s 20150101 -e 20151231 -d \\\n --producttype SLC -q \"orbitdirection=Descending\"\n\nOptions\n^^^^^^^\n\n.. list-table::\n\n * - -u\n - --user\n - TEXT\n - Username [required] (or environment variable DHUS_USER)\n * - -p\n - --password\n - TEXT\n - Password [required] (or environment variable DHUS_PASSWORD)\n * - \n - --url\n - TEXT\n - Define another API URL. Default URL is 'https://apihub.copernicus.eu/apihub/'.\n * - -s\n - --start\n - TEXT\n - Start date of the query in the format YYYYMMDD or an expression like NOW-1DAY.\n * - -e\n - --end\n - TEXT\n - End date of the query.\n * - -g\n - --geometry\n - PATH\n - Search area geometry as GeoJSON file.\n * - \n - --uuid\n - TEXT\n - Select a specific product UUID. Can be set more than once.\n * - \n - --name\n - TEXT\n - Select specific product(s) by filename. Supports wildcards. Can be set more than once.\n * - \n - --sentinel\n - INT\n - Limit search to a Sentinel satellite (constellation).\n * - \n - --instrument\n - TEXT\n - Limit search to a specific instrument on a Sentinel satellite.\n * - \n - --producttype\n - TEXT\n - Limit search to a Sentinel product type.\n * - -c\n - --cloud\n - INT\n - Maximum cloud cover in percent. (requires --sentinel to be 2 or 3)\n * - -o\n - --order-by\n - TEXT\n - Comma-separated list of keywords to order the result by. Prefix '-' for descending order.\n * - -l\n - --limit\n - INT\n - Maximum number of results to return. Defaults to no limit.\n * - -d\n - --download\n - \n - Download all results of the query.\n * -\n - --fail-fast\n -\n - Skip all other other downloads if one fails.\n * - \n - --path\n - PATH\n - Set the path where the files will be saved.\n * - -q\n - --query\n - TEXT\n - Extra search keywords you want to use in the query.\n Example: '-q producttype=GRD -q polarisationmode=HH'.\n Repeated keywords are interpreted as an \"or\" expression.\n * - -f\n - --footprints\n - FILENAME\n - Create a GeoJSON file at the provided path with footprints and metadata of the returned products. Set to '-' for stdout.\n * - \n - --include-pattern\n - TEXT\n - Glob pattern to filter files (within each product) to be downloaded.\n * - \n - --exclude-pattern\n - TEXT\n - Glob pattern to filter files (within each product) to be excluded from the downloaded.\n * - \n - --timeout\n - FLOAT\n - How long to wait for a DataHub response (in seconds, default 60 sec).\n * -\n - --gnss\n -\n - Query orbit products form the GNSS end-point (\"https://scihub.copernicus.eu/gnss\").\n * -\n - --fmt\n - TEXT\n - Specify a custom format to print results. The format string shall be compatible with the Python \"Format Specification Mini-Language\".\n * - \n - --info\n - \n - Display DHuS server information.\n * - \n - --version\n - \n - Show version number and exit.\n * - \n - --debug\n - \n - Print debug log messages.\n * - -h\n - --help\n - \n - Show help message and exit.\n\nTests\n=====\n\nTo run the tests on ``sentinelsat``:\n\n.. code-block:: bash\n\n git clone https://github.com/sentinelsat/sentinelsat.git\n cd sentinelsat\n pip install -e .[dev]\n pytest -v\n\nBy default, prerecorded responses to Copernicus Open Access Hub queries are used to not be affected by its downtime.\nTo allow the tests to run actual queries against the Copernicus Open Access Hub set the environment variables\n\n.. code-block:: bash\n\n export DHUS_USER=<username>\n export DHUS_PASSWORD=<password>\n\nand add ``--disable-vcr`` to ``pytest`` arguments.\nTo update the recordings use ``--vcr-record`` with ``once``, ``new_episodes`` or ``all``. See `vcrpy docs <https://vcrpy.readthedocs.io/en/latest/usage.html#record-modes>`_ for details.\n\n\nDocumentation\n=============\n\nTo build the documentation:\n\n.. code-block:: bash\n\n git clone https://github.com/sentinelsat/sentinelsat.git\n cd sentinelsat\n pip install -e .[dev]\n cd docs\n make html\n\nThe full documentation is also published at http://sentinelsat.readthedocs.io/.\n\n\nChangelog\n=========\n\nSee `CHANGELOG <CHANGELOG.rst>`_. You can also use GitHub's compare view to see the `changes in the main branch since last release <https://github.com/sentinelsat/sentinelsat/compare/v1.2.1...main>`_.\n\nContributors\n============\n\nWe 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 <CONTRIBUTE.rst>`_.\n\nFor a list of maintainers and contributors please see `AUTHORS.rst <AUTHORS.rst>`_ and the `contributor graph <https://github.com/sentinelsat/sentinelsat/graphs/contributors>`_.\n\nLicense\n=======\n\nGPLv3+\n",
"bugtrack_url": null,
"license": "GPLv3+",
"summary": "Utility to search and download Copernicus Sentinel satellite images",
"version": "1.2.1",
"split_keywords": [
"copernicus",
"sentinel",
"esa",
"satellite",
"download",
"gis"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "96e1bc5384834a34ee5410cc5f5ab9df0fbc3f4759a9895142512498ce1cf80e",
"md5": "890e1b762b08f80898899ce4ca789e03",
"sha256": "0f05dd2b75e2d056a92187e8685589f1f9b96a73c18fc0231dcc5e3fc8249760"
},
"downloads": -1,
"filename": "sentinelsat-1.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "890e1b762b08f80898899ce4ca789e03",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 48841,
"upload_time": "2023-03-10T17:51:25",
"upload_time_iso_8601": "2023-03-10T17:51:25.627821Z",
"url": "https://files.pythonhosted.org/packages/96/e1/bc5384834a34ee5410cc5f5ab9df0fbc3f4759a9895142512498ce1cf80e/sentinelsat-1.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "9aa2d8e8ccb8d8042a28ae132074a02091932499cc8f5ebc4072b1677725c179",
"md5": "86e718a4c53a2a2cb25b6f3863e80afc",
"sha256": "d38de0ae1e167d7311426973b0207380e9fa1c4a6f5353dc58bd83bf88b5db4d"
},
"downloads": -1,
"filename": "sentinelsat-1.2.1.tar.gz",
"has_sig": false,
"md5_digest": "86e718a4c53a2a2cb25b6f3863e80afc",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 65366,
"upload_time": "2023-03-10T17:51:27",
"upload_time_iso_8601": "2023-03-10T17:51:27.474997Z",
"url": "https://files.pythonhosted.org/packages/9a/a2/d8e8ccb8d8042a28ae132074a02091932499cc8f5ebc4072b1677725c179/sentinelsat-1.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-03-10 17:51:27",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "sentinelsat",
"github_project": "sentinelsat",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "sentinelsat"
}
JSON
