# Py Hydroweb
**py_hydroweb** is a simple library providing python facilities to search and download hydrological data from the [hydroweb.next](https://hydroweb.next.theia-land.fr) platform.
[](https://hydroweb.next.theia-land.fr)
For more information about the platform, to create an account and an API key, visit our website at https://hydroweb.next.theia-land.fr.
```python
>>> import py_hydroweb
>>> client = py_hydroweb.Client("<my_personal_hydroweb_api_key>")
>>> basket = py_hydroweb.DownloadBasket("my_download_basket")
>>> basket.add_collection("HYDROWEB_LAKES_OPE", bbox=[17.6123, 4.53676, 54.7998, 18.04142])
>>> client.submit_and_download_zip(basket)
```
After you created your account and your api key on the website, this simple piece of code will download (in your current folder) a zip file containing the collection(s) you asked for.
Products are filtered according to how you called `add_collection` (in this example with a simple bbox, but no temporal filter).
## Installing Py Hydroweb and Supported Versions
Py Hydroweb is available on PyPI and can be installed like any other Python package (also works with conda or other environment managers):
```console
$ python -m pip install py_hydroweb
```
Py Hydroweb officially supports Python 3.8+.
## API Reference and User Guide
To prepare and run a download request, follow step by step instruction below.
### 1. Create an instance of a client
```python
>>> client: py_hydroweb.Client = py_hydroweb.Client(
hydroweb_api_url="<an_hydroweb_api_endpoint>",
api_key="<my_personal_hydroweb_api_key>"
)
```
Client's constructor parameters:
- `hydroweb_api_url: str` (optional) Hydroweb API base URL. Default value is https://hydroweb.next.theia-land.fr/api and except for test purpose, there is no need to change it.
- `api_key: str = None` (optional) Hydroweb API Key that you can get from our website once you created your account
__Alternative__: if **not** passed in the above constructor, the API Key **must be** defined by setting the **HYDROWEB_API_KEY** environment variable: `export HYDROWEB_API_KEY=<my_personal_hydroweb_api_key>`
### 2. Create a new empty download basket
```python
>>> basket: py_hydroweb.DownloadBasket = py_hydroweb.DownloadBasket(download_name="my_download_basket")
```
DownloadBasket's constructor parameters:
- `download_name: str` (mandatory) Name for the download to be prepared
### 3. Add as many collections as you want to this basket
```python
>>> basket.add_collection(
collection_id="HYDROWEB_LAKES_OPE",
bbox=[17.6123, 4.53676, 54.7998, 18.04142]
)
>>> basket.add_collection(
collection_id="LIS_SNT_YEARLY",
correlation_id="LIS_SNT_YEARLY",
folder="lis/snt/",
bbox=[17.6123, 4.53676, 54.7998, 18.04142],
intersects={
"coordinates": [
[[21.282, 17.656], [21.282, 14.221], [26.797, 14.221], [26.797, 17.656], [21.282, 17.656]]
],
"type": "Polygon",
},
datetime="2022-01-01T00:00:00Z/2022-12-31T23:59:59Z",
query={
"start_datetime": {"lte": "2024-02-03T00:00:00.000Z"},
"end_datetime": {"gte": "2023-02-02T00:00:00.000Z"},
},
)
```
add_collection method parameters:
- `collection_id: str` (mandatory) Collection identifier (as specified by hydroweb.next platform, browse [here](https://radiantearth.github.io/stac-browser/#/external/hydroweb.next.theia-land.fr/api/catalog/stac) to discover available collection ids)
- `correlation_id: str = None` (optional) Correlation identifier (in case we find several time the same collection ID in the same download basket)
- `folder: str = None` (optional) Desired folder subpath in the resulting zip to be downloaded
- `bbox: List[float] = None` (optional) Geographical bounding box
- for more information see [here](https://github.com/radiantearth/stac-api-spec/blob/release/v1.0.0/item-search/README.md)
- `intersects: dict = None` (optional) Geojson geometry to search for items by performing intersection between their own geometry and this geometry
- for more information see [here](https://github.com/radiantearth/stac-api-spec/blob/release/v1.0.0/item-search/README.md)
- `datetime: str = None` (optional) Single date+time, or a range ('/' separator)
- for more information see [here](https://github.com/radiantearth/stac-api-spec/blob/release/v1.0.0/item-search/README.md)
- **warning**: this parameter refers to the **ingestion** datetime of the data in the catalog and should generally not be used. If you want to refer to product date and time, use the `query` parameter below
- `query: dict = None` (optional) Json query as specified by the query plugin of STAC API
- for more information see [here](https://github.com/stac-api-extensions/query/blob/v1.0.0/README.md)
- **warning 1**: start_datetime and end_datetime refer to the **product** datetime. They are common-metadata as defined [here](https://github.com/radiantearth/stac-api-spec/blob/v1.0.0/stac-spec/item-spec/common-metadata.md#date-and-time-range).
- **warning 2**: in case of a "reference collection" (without a temporal dimension), start_datetime and end_datetime will be ignored.
### 4. Submit your request and download your basket
#### 4.A. (Option A) Dissociated submission and download
##### Step 1: submit your download request
Once you are done adding collections to your basket, you can now submit your download request.
This will return an identifier that you will be able to use later to download your zip file.
```python
>>> download_id: str = client.submit_download(download_basket=basket)
```
submit_download method parameters:
- `download_basket: DownloadBasket` (mandatory) Download basket containing requested collections
submit_download return value:
- `download_id: str` identifier of your download request
##### Step 2: download your zip file
Once you submitted your download request, you can ask to download the resulting zip file.
This method automatically waits for your download request to be ready before it proceeds with zip download.
```python
>>> downloaded_zip_path: str = client.download_zip(
download_id=download_id, zip_filename="my_data.zip", output_folder="./output"
)
```
download_zip method parameters:
- `download_id: str` (mandatory) The identifier of the previously submitted download request
- `zip_filename: str = None` (optional) An output file name for the resulting zip - if not provided, file name will be <download_id>.zip
- `output_folder: str = None` (optional) A (relative or absolute) path to an **existing** folder - if not provided, download will happen in current folder
download_zip return value:
- `downloaded_zip_path: str` The (relative or absolute) path of the downloaded zip file
#### 4.B. (Option B) Grouped submission and download
##### Single step: submit your download request and download your zip file
Alternatively, once you are done adding collections to your basket, you can all together submit your download request, wait for it to be ready and proceed with zip download.
```python
>>> downloaded_zip_path: str = client.submit_and_download_zip(
download_basket=basket, zip_filename="my_data.zip", output_folder="./output"
)
```
submit_and_download_zip method parameters:
- `download_basket: DownloadBasket` (mandatory) Download basket containing requested collections
- `zip_filename: str = None` (optional) An output file name for the resulting zip - if not provided, file name will be <download_id>.zip
- `output_folder: str = None` (optional) A (relative or absolute) path to an **existing** folder - if not provided, download will happen in current folder
submit_and_download_zip return value:
- `downloaded_zip_path: str` The (relative or absolute) path of the downloaded zip file
### 5. Other methods provided by the Client class
#### Check the status/progress of a single download request
```python
>>> status: py_hydroweb.DownloadInfo = client.get_download_info(download_id=download_id)
```
get_download_info method parameters:
- `download_id: str` (mandatory) The identifier of the previously submitted download request
get_download_info return value:
- `status: py_hydroweb.DownloadInfo` Object containing a status (CREATED, RUNNING, COMPLETED, FAILED, ...) and a percentage of progress
#### Check the status/progress of all you download requests (paginated)
```python
>>> last_update = datetime.now() + timedelta(hours=-1)
>>> statuses: dict[str, py_hydroweb.DownloadInfo] = client.get_downloads_info(
last_update=last_update, page=0, size=20
)
```
get_downloads_info method parameters:
- `last_update: date = None` (optional) An optional date to retrieve only download requests updated after this date - if not provided, all your requests will be retrieved
- `page: int = None` (optional) Pagination parameter: index (starting at 0) of the page we want to retrieve - if neither `page` nor `size` are provided, there will be no pagination and all results will be returned at once
- `size: int = None` (optional) Pagination parameter: number of elements per page - if neither `page` nor `size` are provided, there will be no pagination and all results will be returned at once
get_downloads_info return value:
- `statuses: dict[str, py_hydroweb.DownloadInfo]` Dict where keys are download id and values are objects containing a status (CREATED, RUNNING, COMPLETED, FAILED, ...) and a percentage of progress
#### Delete a download request
The history of your download requests will automatically get cleaned after a certain amout of time.
You can also clean it manually provided that status is no longer CREATED nor RUNNING.
```python
>>> client.delete_download(download_id=download_id)
```
delete_download method parameters:
- `download_id: str` (mandatory) The identifier of the download request to be removed
Raw data
{
"_id": null,
"home_page": null,
"name": "py-hydroweb",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "\"hydroweb.next operational team\" <exp.hysope2@cnes.fr>",
"keywords": "hydroweb, water, hydrology, inland water, coastal, scientific data, search, download, catalog, cnes, dataterra, theia",
"author": null,
"author_email": "\"hydroweb.next operational team\" <exp.hysope2@cnes.fr>",
"download_url": "https://files.pythonhosted.org/packages/c5/ba/4437770e6385284073bf9ee80bb9a1fdb473766bfc7879a3374b48ea0857/py_hydroweb-1.0.2.tar.gz",
"platform": null,
"description": "# Py Hydroweb\n\n**py_hydroweb** is a simple library providing python facilities to search and download hydrological data from the [hydroweb.next](https://hydroweb.next.theia-land.fr) platform.\n\n[](https://hydroweb.next.theia-land.fr)\n\nFor more information about the platform, to create an account and an API key, visit our website at https://hydroweb.next.theia-land.fr.\n\n\n```python\n>>> import py_hydroweb\n>>> client = py_hydroweb.Client(\"<my_personal_hydroweb_api_key>\")\n>>> basket = py_hydroweb.DownloadBasket(\"my_download_basket\")\n>>> basket.add_collection(\"HYDROWEB_LAKES_OPE\", bbox=[17.6123, 4.53676, 54.7998, 18.04142])\n>>> client.submit_and_download_zip(basket)\n```\n\nAfter you created your account and your api key on the website, this simple piece of code will download (in your current folder) a zip file containing the collection(s) you asked for. \nProducts are filtered according to how you called `add_collection` (in this example with a simple bbox, but no temporal filter).\n\n## Installing Py Hydroweb and Supported Versions\n\nPy Hydroweb is available on PyPI and can be installed like any other Python package (also works with conda or other environment managers):\n\n```console\n$ python -m pip install py_hydroweb\n```\n\nPy Hydroweb officially supports Python 3.8+.\n\n## API Reference and User Guide\n\nTo prepare and run a download request, follow step by step instruction below.\n\n### 1. Create an instance of a client\n\n```python\n>>> client: py_hydroweb.Client = py_hydroweb.Client(\n hydroweb_api_url=\"<an_hydroweb_api_endpoint>\", \n api_key=\"<my_personal_hydroweb_api_key>\"\n )\n```\n\nClient's constructor parameters:\n- `hydroweb_api_url: str` (optional) Hydroweb API base URL. Default value is https://hydroweb.next.theia-land.fr/api and except for test purpose, there is no need to change it.\n- `api_key: str = None` (optional) Hydroweb API Key that you can get from our website once you created your account\n \n__Alternative__: if **not** passed in the above constructor, the API Key **must be** defined by setting the **HYDROWEB_API_KEY** environment variable: `export HYDROWEB_API_KEY=<my_personal_hydroweb_api_key>`\n\n### 2. Create a new empty download basket\n\n```python\n>>> basket: py_hydroweb.DownloadBasket = py_hydroweb.DownloadBasket(download_name=\"my_download_basket\")\n```\n\nDownloadBasket's constructor parameters:\n- `download_name: str` (mandatory) Name for the download to be prepared\n\n### 3. Add as many collections as you want to this basket\n\n```python\n>>> basket.add_collection(\n collection_id=\"HYDROWEB_LAKES_OPE\", \n bbox=[17.6123, 4.53676, 54.7998, 18.04142]\n )\n>>> basket.add_collection(\n collection_id=\"LIS_SNT_YEARLY\",\n correlation_id=\"LIS_SNT_YEARLY\",\n folder=\"lis/snt/\",\n bbox=[17.6123, 4.53676, 54.7998, 18.04142],\n intersects={\n \"coordinates\": [\n [[21.282, 17.656], [21.282, 14.221], [26.797, 14.221], [26.797, 17.656], [21.282, 17.656]]\n ],\n \"type\": \"Polygon\",\n },\n datetime=\"2022-01-01T00:00:00Z/2022-12-31T23:59:59Z\",\n query={\n \"start_datetime\": {\"lte\": \"2024-02-03T00:00:00.000Z\"},\n \"end_datetime\": {\"gte\": \"2023-02-02T00:00:00.000Z\"},\n },\n )\n```\n\nadd_collection method parameters:\n- `collection_id: str` (mandatory) Collection identifier (as specified by hydroweb.next platform, browse [here](https://radiantearth.github.io/stac-browser/#/external/hydroweb.next.theia-land.fr/api/catalog/stac) to discover available collection ids)\n- `correlation_id: str = None` (optional) Correlation identifier (in case we find several time the same collection ID in the same download basket)\n- `folder: str = None` (optional) Desired folder subpath in the resulting zip to be downloaded\n- `bbox: List[float] = None` (optional) Geographical bounding box\n - for more information see [here](https://github.com/radiantearth/stac-api-spec/blob/release/v1.0.0/item-search/README.md)\n- `intersects: dict = None` (optional) Geojson geometry to search for items by performing intersection between their own geometry and this geometry \n - for more information see [here](https://github.com/radiantearth/stac-api-spec/blob/release/v1.0.0/item-search/README.md)\n- `datetime: str = None` (optional) Single date+time, or a range ('/' separator) \n - for more information see [here](https://github.com/radiantearth/stac-api-spec/blob/release/v1.0.0/item-search/README.md)\n - **warning**: this parameter refers to the **ingestion** datetime of the data in the catalog and should generally not be used. If you want to refer to product date and time, use the `query` parameter below\n- `query: dict = None` (optional) Json query as specified by the query plugin of STAC API \n - for more information see [here](https://github.com/stac-api-extensions/query/blob/v1.0.0/README.md)\n - **warning 1**: start_datetime and end_datetime refer to the **product** datetime. They are common-metadata as defined [here](https://github.com/radiantearth/stac-api-spec/blob/v1.0.0/stac-spec/item-spec/common-metadata.md#date-and-time-range).\n - **warning 2**: in case of a \"reference collection\" (without a temporal dimension), start_datetime and end_datetime will be ignored.\n\n### 4. Submit your request and download your basket\n\n#### 4.A. (Option A) Dissociated submission and download\n\n##### Step 1: submit your download request\n\nOnce you are done adding collections to your basket, you can now submit your download request.\n\nThis will return an identifier that you will be able to use later to download your zip file.\n\n```python\n>>> download_id: str = client.submit_download(download_basket=basket)\n```\n\nsubmit_download method parameters:\n- `download_basket: DownloadBasket` (mandatory) Download basket containing requested collections\n\nsubmit_download return value:\n- `download_id: str` identifier of your download request\n\n##### Step 2: download your zip file\n\nOnce you submitted your download request, you can ask to download the resulting zip file.\n\nThis method automatically waits for your download request to be ready before it proceeds with zip download.\n\n```python\n>>> downloaded_zip_path: str = client.download_zip(\n download_id=download_id, zip_filename=\"my_data.zip\", output_folder=\"./output\"\n )\n```\n\ndownload_zip method parameters:\n- `download_id: str` (mandatory) The identifier of the previously submitted download request\n- `zip_filename: str = None` (optional) An output file name for the resulting zip - if not provided, file name will be <download_id>.zip\n- `output_folder: str = None` (optional) A (relative or absolute) path to an **existing** folder - if not provided, download will happen in current folder\n\ndownload_zip return value:\n- `downloaded_zip_path: str` The (relative or absolute) path of the downloaded zip file\n\n#### 4.B. (Option B) Grouped submission and download\n\n##### Single step: submit your download request and download your zip file\n\nAlternatively, once you are done adding collections to your basket, you can all together submit your download request, wait for it to be ready and proceed with zip download.\n\n```python\n>>> downloaded_zip_path: str = client.submit_and_download_zip(\n download_basket=basket, zip_filename=\"my_data.zip\", output_folder=\"./output\"\n )\n```\n\nsubmit_and_download_zip method parameters:\n- `download_basket: DownloadBasket` (mandatory) Download basket containing requested collections\n- `zip_filename: str = None` (optional) An output file name for the resulting zip - if not provided, file name will be <download_id>.zip\n- `output_folder: str = None` (optional) A (relative or absolute) path to an **existing** folder - if not provided, download will happen in current folder\n\nsubmit_and_download_zip return value:\n- `downloaded_zip_path: str` The (relative or absolute) path of the downloaded zip file\n\n### 5. Other methods provided by the Client class\n\n#### Check the status/progress of a single download request\n\n```python\n>>> status: py_hydroweb.DownloadInfo = client.get_download_info(download_id=download_id)\n```\n\nget_download_info method parameters:\n- `download_id: str` (mandatory) The identifier of the previously submitted download request\n\nget_download_info return value:\n- `status: py_hydroweb.DownloadInfo` Object containing a status (CREATED, RUNNING, COMPLETED, FAILED, ...) and a percentage of progress\n\n#### Check the status/progress of all you download requests (paginated)\n\n```python\n>>> last_update = datetime.now() + timedelta(hours=-1)\n>>> statuses: dict[str, py_hydroweb.DownloadInfo] = client.get_downloads_info(\n last_update=last_update, page=0, size=20\n )\n```\n\nget_downloads_info method parameters:\n- `last_update: date = None` (optional) An optional date to retrieve only download requests updated after this date - if not provided, all your requests will be retrieved\n- `page: int = None` (optional) Pagination parameter: index (starting at 0) of the page we want to retrieve - if neither `page` nor `size` are provided, there will be no pagination and all results will be returned at once\n- `size: int = None` (optional) Pagination parameter: number of elements per page - if neither `page` nor `size` are provided, there will be no pagination and all results will be returned at once\n\nget_downloads_info return value:\n- `statuses: dict[str, py_hydroweb.DownloadInfo]` Dict where keys are download id and values are objects containing a status (CREATED, RUNNING, COMPLETED, FAILED, ...) and a percentage of progress\n\n#### Delete a download request\n\nThe history of your download requests will automatically get cleaned after a certain amout of time. \nYou can also clean it manually provided that status is no longer CREATED nor RUNNING.\n\n```python\n>>> client.delete_download(download_id=download_id)\n```\n\ndelete_download method parameters:\n- `download_id: str` (mandatory) The identifier of the download request to be removed\n\n",
"bugtrack_url": null,
"license": "Apache 2.0",
"summary": "Python API to search and download hydrological data from the hydroweb.next catalog",
"version": "1.0.2",
"project_urls": {
"Home": "https://github.com/CNES/py-hydroweb",
"HydrowebNext": "https://hydroweb.next.theia-land.fr",
"Source": "https://github.com/CNES/py-hydroweb"
},
"split_keywords": [
"hydroweb",
" water",
" hydrology",
" inland water",
" coastal",
" scientific data",
" search",
" download",
" catalog",
" cnes",
" dataterra",
" theia"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "bf1f52ce824becd7cb6e11ec0630a2ca3d4d33e2e2dddf9b7822b8b6864a6616",
"md5": "62af907f8fd678112a79a522c7e323cd",
"sha256": "be017c84ed2c4837467288120cd1c39314743da9a84aafb844c7208507df6274"
},
"downloads": -1,
"filename": "py_hydroweb-1.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "62af907f8fd678112a79a522c7e323cd",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 15304,
"upload_time": "2024-12-17T15:54:27",
"upload_time_iso_8601": "2024-12-17T15:54:27.246950Z",
"url": "https://files.pythonhosted.org/packages/bf/1f/52ce824becd7cb6e11ec0630a2ca3d4d33e2e2dddf9b7822b8b6864a6616/py_hydroweb-1.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c5ba4437770e6385284073bf9ee80bb9a1fdb473766bfc7879a3374b48ea0857",
"md5": "a79a56cbc7fa08ff7d1dd0af149d1fbd",
"sha256": "44be8290a6c454788d0096a3201a033f43cae7222a3933bdc60262fa792238e3"
},
"downloads": -1,
"filename": "py_hydroweb-1.0.2.tar.gz",
"has_sig": false,
"md5_digest": "a79a56cbc7fa08ff7d1dd0af149d1fbd",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 24986,
"upload_time": "2024-12-17T15:54:32",
"upload_time_iso_8601": "2024-12-17T15:54:32.447968Z",
"url": "https://files.pythonhosted.org/packages/c5/ba/4437770e6385284073bf9ee80bb9a1fdb473766bfc7879a3374b48ea0857/py_hydroweb-1.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-17 15:54:32",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "CNES",
"github_project": "py-hydroweb",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "py-hydroweb"
}
JSON
