| Name | dataretrieval JSON |
| Version |
1.0.11
JSON |
| download |
| home_page | None |
| Summary | Discover and retrieve water data from U.S. federal hydrologic web services. |
| upload_time | 2024-10-25 17:35:53 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | License ======= Unless otherwise noted, this project is in the public domain in the United States because it contains materials that originally came from the United States Geological Survey, an agency of the United States Department of Interior. For more information, see the official USGS copyright policy at https://www.usgs.gov/information-policies-and-instructions/copyrights-and-credits Additionally, we waive copyright and related rights in the work worldwide through the CC0 1.0 Universal public domain dedication. CC0 1.0 Universal Summary ------------------------- This is a human-readable summary of the [Legal Code (read the full text)][1]. ### No Copyright The person who associated a work with this deed has dedicated the work to the public domain by waiving all of his or her rights to the work worldwide under copyright law, including all related and neighboring rights, to the extent allowed by law. You can copy, modify, distribute and perform the work, even for commercial purposes, all without asking permission. ### Other Information In no way are the patent or trademark rights of any person affected by CC0, nor are the rights that other persons may have in the work or in how the work is used, such as publicity or privacy rights. Unless expressly stated otherwise, the person who associated a work with this deed makes no warranties about the work, and disclaims liability for all uses of the work, to the fullest extent permitted by applicable law. When using or citing the work, you should not imply endorsement by the author or the affirmer. [1]: https://creativecommons.org/publicdomain/zero/1.0/legalcode |
| keywords |
usgs
water data
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# dataretrieval: Download hydrologic data
:warning: USGS data availability and format are changing on Water Quality Portal (WQP). Since March 2024, data obtained from WQP legacy profiles will not include new USGS data or recent updates to existing data.
To view the status of changes in data availability and code functionality, visit: https://doi-usgs.github.io/dataRetrieval/articles/Status.html
:mega: **09/03/2024:** The groundwater levels service has switched endpoints, and `dataretrieval` was updated accordingly in [`v1.0.10`](https://github.com/DOI-USGS/dataretrieval-python/releases/tag/v1.0.10). Older versions using the discontinued endpoint will return 503 errors for `nwis.get_gwlevels` or the `service='gwlevels'` argument. Visit [Water Data For the Nation](https://waterdata.usgs.gov/blog/wdfn-waterservices-2024/) for more information.
## What is dataretrieval?
`dataretrieval` was created to simplify the process of loading hydrologic data into the Python environment.
Like the original R version [`dataRetrieval`](https://github.com/DOI-USGS/dataRetrieval),
it is designed to retrieve the major data types of U.S. Geological Survey (USGS) hydrology
data that are available on the Web, as well as data from the Water
Quality Portal (WQP), which currently houses water quality data from the
Environmental Protection Agency (EPA), U.S. Department of Agriculture
(USDA), and USGS. Direct USGS data is obtained from a service called the
National Water Information System (NWIS).
Note that the python version is not a direct port of the original: it attempts to reproduce the functionality of the R package,
though its organization and interface often differ.
If there's a hydrologic or environmental data portal that you'd like dataretrieval to
work with, raise it as an [issue](https://github.com/USGS-python/dataretrieval/issues).
Here's an example using `dataretrieval` to retrieve data from the National Water Information System (NWIS).
```python
# first import the functions for downloading data from NWIS
import dataretrieval.nwis as nwis
# specify the USGS site code for which we want data.
site = '03339000'
# get instantaneous values (iv)
df = nwis.get_record(sites=site, service='iv', start='2017-12-31', end='2018-01-01')
# get water quality samples (qwdata)
df2 = nwis.get_record(sites=site, service='qwdata', start='2017-12-31', end='2018-01-01')
# get basic info about the site
df3 = nwis.get_record(sites=site, service='site')
```
Services available from NWIS include:
- instantaneous values (iv)
- daily values (dv)
- statistics (stat)
- site info (site)
- discharge peaks (peaks)
- discharge measurements (measurements)
* water quality samples (qwdata)
To access the full functionality available from NWIS web services, nwis.get record appends any additional kwargs into the REST request. For example
```python
nwis.get_record(sites='03339000', service='dv', start='2017-12-31', parameterCd='00060')
```
will download daily data with the parameter code 00060 (discharge).
## Accessing the "Internal" NWIS
If you're connected to the USGS network, dataretrieval call pull from the internal (non-public) NWIS interface.
Most dataretrieval functions pass kwargs directly to NWIS's REST API, which provides simple access to internal data; simply specify "access='3'".
For example
```python
nwis.get_record(sites='05404147',service='iv', start='2021-01-01', end='2021-3-01', access='3')
```
More services and documentation to come!
## Quick start
dataretrieval can be installed using pip:
$ python3 -m pip install -U dataretrieval
or conda:
$ conda install -c conda-forge dataretrieval
More examples of use are include in [`demos`](https://github.com/USGS-python/dataretrieval/tree/main/demos).
## Issue tracker
Please report any bugs and enhancement ideas using the dataretrieval issue
tracker:
https://github.com/USGS-python/dataretrieval/issues
Feel free to also ask questions on the tracker.
## Contributing
Any help in testing, development, documentation and other tasks is welcome.
For more details, see the file [CONTRIBUTING.md](CONTRIBUTING.md).
## Package Support
The Water Mission Area of the USGS supports the development and maintenance of `dataretrieval`
and most likely further into the future.
Resources are available primarily for maintenance and responding to user questions.
Priorities on the development of new features are determined by the `dataretrieval` development team.
## Acknowledgments
This material is partially based upon work supported by the National Science Foundation (NSF) under award 1931297.
Any opinions, findings, conclusions, or recommendations expressed in this material are those of the authors and do not necessarily reflect the views of the NSF.
## Disclaimer
This software is preliminary or provisional and is subject to revision.
It is being provided to meet the need for timely best science.
The software has not received final approval by the U.S. Geological Survey (USGS).
No warranty, expressed or implied, is made by the USGS or the U.S. Government as to the functionality of the software and related material nor shall the fact of release constitute any such warranty.
The software is provided on the condition that neither the USGS nor the U.S. Government shall be held liable for any damages resulting from the authorized or unauthorized use of the software.
## Citation
Hodson, T.O., Hariharan, J.A., Black, S., and Horsburgh, J.S., 2023, dataretrieval (Python): a Python package for discovering
and retrieving water data available from U.S. federal hydrologic web services:
U.S. Geological Survey software release,
https://doi.org/10.5066/P94I5TX3.
Raw data
{
"_id": null,
"home_page": null,
"name": "dataretrieval",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Elise Hinman <ehinman@usgs.gov>",
"keywords": "USGS, water data",
"author": null,
"author_email": "Timothy Hodson <thodson@usgs.gov>",
"download_url": "https://files.pythonhosted.org/packages/d5/44/f4af4d30a2a33072589f05a7e2062ef9ee0f783c6825fec9a044a1821ad2/dataretrieval-1.0.11.tar.gz",
"platform": null,
"description": "# dataretrieval: Download hydrologic data\n\n\n\n\n\n:warning: USGS data availability and format are changing on Water Quality Portal (WQP). Since March 2024, data obtained from WQP legacy profiles will not include new USGS data or recent updates to existing data. \nTo view the status of changes in data availability and code functionality, visit: https://doi-usgs.github.io/dataRetrieval/articles/Status.html\n\n:mega: **09/03/2024:** The groundwater levels service has switched endpoints, and `dataretrieval` was updated accordingly in [`v1.0.10`](https://github.com/DOI-USGS/dataretrieval-python/releases/tag/v1.0.10). Older versions using the discontinued endpoint will return 503 errors for `nwis.get_gwlevels` or the `service='gwlevels'` argument. Visit [Water Data For the Nation](https://waterdata.usgs.gov/blog/wdfn-waterservices-2024/) for more information.\n\n## What is dataretrieval?\n`dataretrieval` was created to simplify the process of loading hydrologic data into the Python environment.\nLike the original R version [`dataRetrieval`](https://github.com/DOI-USGS/dataRetrieval),\nit is designed to retrieve the major data types of U.S. Geological Survey (USGS) hydrology\ndata that are available on the Web, as well as data from the Water\nQuality Portal (WQP), which currently houses water quality data from the\nEnvironmental Protection Agency (EPA), U.S. Department of Agriculture\n(USDA), and USGS. Direct USGS data is obtained from a service called the\nNational Water Information System (NWIS).\n\nNote that the python version is not a direct port of the original: it attempts to reproduce the functionality of the R package,\nthough its organization and interface often differ.\n\nIf there's a hydrologic or environmental data portal that you'd like dataretrieval to \nwork with, raise it as an [issue](https://github.com/USGS-python/dataretrieval/issues).\n\nHere's an example using `dataretrieval` to retrieve data from the National Water Information System (NWIS).\n\n```python\n# first import the functions for downloading data from NWIS\nimport dataretrieval.nwis as nwis\n\n# specify the USGS site code for which we want data.\nsite = '03339000'\n\n\n# get instantaneous values (iv)\ndf = nwis.get_record(sites=site, service='iv', start='2017-12-31', end='2018-01-01')\n\n# get water quality samples (qwdata)\ndf2 = nwis.get_record(sites=site, service='qwdata', start='2017-12-31', end='2018-01-01')\n\n# get basic info about the site\ndf3 = nwis.get_record(sites=site, service='site')\n```\nServices available from NWIS include:\n- instantaneous values (iv)\n- daily values (dv)\n- statistics (stat)\n- site info (site)\n- discharge peaks (peaks)\n- discharge measurements (measurements)\n* water quality samples (qwdata)\n\nTo access the full functionality available from NWIS web services, nwis.get record appends any additional kwargs into the REST request. For example\n```python\nnwis.get_record(sites='03339000', service='dv', start='2017-12-31', parameterCd='00060')\n```\nwill download daily data with the parameter code 00060 (discharge).\n\n## Accessing the \"Internal\" NWIS\nIf you're connected to the USGS network, dataretrieval call pull from the internal (non-public) NWIS interface.\nMost dataretrieval functions pass kwargs directly to NWIS's REST API, which provides simple access to internal data; simply specify \"access='3'\".\nFor example\n```python\nnwis.get_record(sites='05404147',service='iv', start='2021-01-01', end='2021-3-01', access='3')\n```\n\nMore services and documentation to come!\n\n## Quick start\n\ndataretrieval can be installed using pip:\n\t\n $ python3 -m pip install -U dataretrieval\n\nor conda:\n\n $ conda install -c conda-forge dataretrieval\n\nMore examples of use are include in [`demos`](https://github.com/USGS-python/dataretrieval/tree/main/demos).\n\n## Issue tracker\n\nPlease report any bugs and enhancement ideas using the dataretrieval issue\ntracker:\n\n https://github.com/USGS-python/dataretrieval/issues\n\nFeel free to also ask questions on the tracker.\n\n\n## Contributing\n\nAny help in testing, development, documentation and other tasks is welcome.\nFor more details, see the file [CONTRIBUTING.md](CONTRIBUTING.md).\n\n\n## Package Support\nThe Water Mission Area of the USGS supports the development and maintenance of `dataretrieval`\nand most likely further into the future.\nResources are available primarily for maintenance and responding to user questions.\nPriorities on the development of new features are determined by the `dataretrieval` development team.\n\n\n## Acknowledgments\nThis material is partially based upon work supported by the National Science Foundation (NSF) under award 1931297.\nAny opinions, findings, conclusions, or recommendations expressed in this material are those of the authors and do not necessarily reflect the views of the NSF.\n\n## Disclaimer\n\nThis software is preliminary or provisional and is subject to revision. \nIt is being provided to meet the need for timely best science.\nThe software has not received final approval by the U.S. Geological Survey (USGS).\nNo warranty, expressed or implied, is made by the USGS or the U.S. Government as to the functionality of the software and related material nor shall the fact of release constitute any such warranty. \nThe software is provided on the condition that neither the USGS nor the U.S. Government shall be held liable for any damages resulting from the authorized or unauthorized use of the software.\n\n## Citation\n\nHodson, T.O., Hariharan, J.A., Black, S., and Horsburgh, J.S., 2023, dataretrieval (Python): a Python package for discovering\nand retrieving water data available from U.S. federal hydrologic web services:\nU.S. Geological Survey software release,\nhttps://doi.org/10.5066/P94I5TX3.\n",
"bugtrack_url": null,
"license": "License ======= Unless otherwise noted, this project is in the public domain in the United States because it contains materials that originally came from the United States Geological Survey, an agency of the United States Department of Interior. For more information, see the official USGS copyright policy at https://www.usgs.gov/information-policies-and-instructions/copyrights-and-credits Additionally, we waive copyright and related rights in the work worldwide through the CC0 1.0 Universal public domain dedication. CC0 1.0 Universal Summary ------------------------- This is a human-readable summary of the [Legal Code (read the full text)][1]. ### No Copyright The person who associated a work with this deed has dedicated the work to the public domain by waiving all of his or her rights to the work worldwide under copyright law, including all related and neighboring rights, to the extent allowed by law. You can copy, modify, distribute and perform the work, even for commercial purposes, all without asking permission. ### Other Information In no way are the patent or trademark rights of any person affected by CC0, nor are the rights that other persons may have in the work or in how the work is used, such as publicity or privacy rights. Unless expressly stated otherwise, the person who associated a work with this deed makes no warranties about the work, and disclaims liability for all uses of the work, to the fullest extent permitted by applicable law. When using or citing the work, you should not imply endorsement by the author or the affirmer. [1]: https://creativecommons.org/publicdomain/zero/1.0/legalcode ",
"summary": "Discover and retrieve water data from U.S. federal hydrologic web services.",
"version": "1.0.11",
"project_urls": {
"documentation": "https://doi-usgs.github.io/dataretrieval-python/",
"homepage": "https://github.com/DOI-USGS/dataretrieval-python",
"repository": "https://github.com/DOI-USGS/dataretrieval-python.git"
},
"split_keywords": [
"usgs",
" water data"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b6679a8c35f321bdd96016c7360d8cfd0312be7f79f98a69152a08cced2012c5",
"md5": "dab2d06fc1aa9a6fee3158f3595f046b",
"sha256": "ba97a0a4926a2f6158f3577344b94d448d543eb646639812dcfa4306309738de"
},
"downloads": -1,
"filename": "dataretrieval-1.0.11-py3-none-any.whl",
"has_sig": false,
"md5_digest": "dab2d06fc1aa9a6fee3158f3595f046b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 33962,
"upload_time": "2024-10-25T17:35:51",
"upload_time_iso_8601": "2024-10-25T17:35:51.749272Z",
"url": "https://files.pythonhosted.org/packages/b6/67/9a8c35f321bdd96016c7360d8cfd0312be7f79f98a69152a08cced2012c5/dataretrieval-1.0.11-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d544f4af4d30a2a33072589f05a7e2062ef9ee0f783c6825fec9a044a1821ad2",
"md5": "e814ea4dee727097d974b445db3b9318",
"sha256": "b6a8c0336c98572047b366f01ddb1870ed5a0ea2a41e8cb4c6e18174bacf3939"
},
"downloads": -1,
"filename": "dataretrieval-1.0.11.tar.gz",
"has_sig": false,
"md5_digest": "e814ea4dee727097d974b445db3b9318",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 4578598,
"upload_time": "2024-10-25T17:35:53",
"upload_time_iso_8601": "2024-10-25T17:35:53.884324Z",
"url": "https://files.pythonhosted.org/packages/d5/44/f4af4d30a2a33072589f05a7e2062ef9ee0f783c6825fec9a044a1821ad2/dataretrieval-1.0.11.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-25 17:35:53",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "DOI-USGS",
"github_project": "dataretrieval-python",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "dataretrieval"
}
