# callusgs
[](https://callusgs.readthedocs.io/en/latest/?badge=latest)
`callusgs` aims to be a complete and (mostly) typed implementation of USGS's machine-to-machine API (v1.5.0).
In addition, `callusgs` provides a suite of command line tools that can be used to query and download scenes,
use the geocoding service provided by the USGSS and convert WRS 1/2 *coordinates* to geographic coordinates.
## Features
`callusgs` is both a Python package and a suite of command line tools that allows
1. Downloading of select products (see table below)
1. Access to the USGS *geocoding* API
1. Conversion between the WRS1 and WRS2 grids to geographic coordinates and
1. clean up of download order queues (mainly as utility functionality)
Currently supported products for download are:
| **Product string** | **Prodcut Name** |
|:----------------------:|:------------------------------------:|
| `landsat_em_c2_l1` | Landsat 4/5 Collection 2 Level 1 |
| `landsat_em_c2_l2` | Landsat 4/5 Collection 2 Level 1 |
| `landsat_etm_c2_l1` | Landsat 7 Collection 2 Level 1 |
| `landsat_etm_c2_l2` | Landsat 7 Collection 2 Level 2 |
| `landsat_ot_c2_l1` | Landsat 8/9 Collection 2 Level 1 |
| `landsat_ot_c2_l2` | Landsat 8/9 Collection 2 Level 2 |
| `landsat_ba_tile_c2` | Landsat Burned Area Product |
| `landsat_dswe_tile_c2` | Landsat Dynamic Surface Water Extent |
| `landsat_fsca_tile_c2` | Landsat Fractional Snow Covered Area |
| `gmted2010` | GMTED 2010 DEM |
## Installation
Install the package together with the respective command line applications from pip.
```bash
pip install callusgs
```
Alternatively, if you're only interested in the CLI functionality of this tool the best choice is probably to use [pipx](https://github.com/pypa/pipx) for installation.
```bash
pipx install callusgs
```
## Usage
For more detailed usage instructions and/or examples, please refer to the [documentation](https://callusgs.readthedocs.io) or see the section below.
### Prerequisites
To fully use the package's/the API's functionality you need (1) an account at USGS and (2) access to M2M MACHINE role.
While the first one is mandatory, the functionality without access to the M2M MACHINE role is restricted.
The account credentials need to be passed to the command line tools via CLI arguments or by setting the environment variables
`USGS_USERNAME` and `USGS_AUTH`.
| **Feature/Functionality** | **Usable** | **Note** |
|:--------------------------------------------------:|:----------:|:--------------------------------------------------------------------------------:|
| Searching for scenes | Yes | |
| Creating scene lists out of search results | Yes | |
| Generate orders from scene searches or scene lists | No | Downloading orders from list, when order was placed via webinterface is possible |
| Geocoding | Yes | |
| WRS1/WRS2 to coordinate transformation | Yes | |
### Command Line Tool Examples
#### Download
The snippet below queries the EarthExplorer catalogue for Landsat 8/9 Collection 2 Level 2 scenes between June 1st, 2020 and
July 25th, 2024 for a small part of the southwest of Berlin, Germany. Additionally, only scenes for August and September are
returned and they must have a cloudcover of no more than 15%. Results are stored in a directory called `download`. The user
set the logging level to `INFO` with the `-v` flag.
```bash
callusgs -v download --product landsat_etm_c2_l2 \
--date 2020-06-01 2024-07-25 --month aug sep \
--cloudcover 0 15 --aoi-coordinates 52.5 13.4 52.5 13.2 52.7 13.2 52.5 13.4 -- download
```
The snippet below queries the EarthExplorer catalogue for Landsat 7 Collection 2 Level 1 scenes between January 1st, 2005 and
January 1st, 2020 for Lima, Peru, and its surrounding region. For the given polygon, the minimum bound recatangle is build and used for the query.
No further restrictions regarding the obervation months or cloudcouver are posed. Results **would be** stored in a directory called `download`,
but as a dry run is requested, only the number of available scenes and their download size is reported. The user requested extended debug output with
the `-vv` flag.
```bash
callusgs -vv --dry-run download --product landsat_etm_c2_l1 \
--date 2005-01-01 2020-01-01 --aoi-type Mbr \
--aoi-coordinates -11.99 -77.13 -11.97 -77.00 -12.01 -76.88 -12.07 -76.88 -12.13 -76.89 -12.07 -77.16 -11.99 -77.13 -- \
download
```
#### Geocode
The USGS supplies a simplistic geocoding/POI-search endpoint which can be queries using the `geocode` sub-program.
The snippet below queries all U.S. features whos placename attribute matches "New York".
> Right now, the `placename` endpoint, which is called under the hood, does not return any results for features of type "world"!
```bash
callusgs geocode --feature-type US "New York"
```
#### Grid2ll
Get either centroids or polygons of the WRS2 or WRS2 coordinate system based on geographic coordinates in WGS84 (EPSG:4326) inputs.
The snipped below queries the centroid coordinates for three points in the WRS2 system.
```bash
callusgs grid2ll --response-shape point 52,11 32,5 89,69
```
#### Clean
The `clean` subprogram is used to delete dangeling product/scene orders.
```bash
callusgs -v clean
```
## Known Limitations
- The download program will only start the download of orders once all scenes are available. Thus, your order might not get downloaded
immediately if only one scene is still being processed.
- The geocoding/place search endpoint of USGS's API currently does not seem to work with non-US features. This may be a bug in the program.
## Documentation
See the docs folder for raw documentation or visit [callusgs.readthedocs.io](https://callusgs.readthedocs.io).
## License
- `callusgs` is licensed under the [GPL-v2](LICENSE)
## Citation
If you use this software, please use the bibtex entry below or refer to [the citation file](CITATION.cff).
```tex
@software{Katerndahl2024,
author = {Katerndahl, Florian},
title = {callusgs},
url = {https://github.com/Florian-Katerndahl/callusgs}
}
```
## Acknowledgments
- Most of the docstrings were provided by the USGS in their API documentation.
- The download application took initial inspiration from [the example script provided by the USGS](https://m2m.cr.usgs.gov/api/docs/example/download_data-py).
Raw data
{
"_id": null,
"home_page": "https://github.com/Florian-Katerndahl/callusgs",
"name": "callusgs",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.9",
"maintainer_email": null,
"keywords": "USGS, API, machine-to-machine, Landsat, CLI, geodata, GIS, EROS, download, EarthExplorer",
"author": "Florian-Katerndahl",
"author_email": "florian@katerndahl.com",
"download_url": "https://files.pythonhosted.org/packages/f8/38/e0c64ba91201b4dbbf6c4b03e202676dcc74359bad23249a9e32fa968dc4/callusgs-0.1.2.tar.gz",
"platform": null,
"description": "# callusgs\n\n[](https://callusgs.readthedocs.io/en/latest/?badge=latest)\n\n`callusgs` aims to be a complete and (mostly) typed implementation of USGS's machine-to-machine API (v1.5.0).\nIn addition, `callusgs` provides a suite of command line tools that can be used to query and download scenes, \nuse the geocoding service provided by the USGSS and convert WRS 1/2 *coordinates* to geographic coordinates.\n\n## Features\n\n`callusgs` is both a Python package and a suite of command line tools that allows\n\n1. Downloading of select products (see table below)\n1. Access to the USGS *geocoding* API\n1. Conversion between the WRS1 and WRS2 grids to geographic coordinates and\n1. clean up of download order queues (mainly as utility functionality)\n\nCurrently supported products for download are:\n\n| **Product string** | **Prodcut Name** |\n|:----------------------:|:------------------------------------:|\n| `landsat_em_c2_l1` | Landsat 4/5 Collection 2 Level 1 |\n| `landsat_em_c2_l2` | Landsat 4/5 Collection 2 Level 1 |\n| `landsat_etm_c2_l1` | Landsat 7 Collection 2 Level 1 |\n| `landsat_etm_c2_l2` | Landsat 7 Collection 2 Level 2 |\n| `landsat_ot_c2_l1` | Landsat 8/9 Collection 2 Level 1 |\n| `landsat_ot_c2_l2` | Landsat 8/9 Collection 2 Level 2 |\n| `landsat_ba_tile_c2` | Landsat Burned Area Product |\n| `landsat_dswe_tile_c2` | Landsat Dynamic Surface Water Extent |\n| `landsat_fsca_tile_c2` | Landsat Fractional Snow Covered Area |\n| `gmted2010` | GMTED 2010 DEM |\n\n## Installation\n\nInstall the package together with the respective command line applications from pip.\n\n```bash\npip install callusgs\n```\n\nAlternatively, if you're only interested in the CLI functionality of this tool the best choice is probably to use [pipx](https://github.com/pypa/pipx) for installation.\n\n```bash\npipx install callusgs\n```\n\n## Usage\n\nFor more detailed usage instructions and/or examples, please refer to the [documentation](https://callusgs.readthedocs.io) or see the section below.\n\n### Prerequisites\n\nTo fully use the package's/the API's functionality you need (1) an account at USGS and (2) access to M2M MACHINE role.\nWhile the first one is mandatory, the functionality without access to the M2M MACHINE role is restricted.\nThe account credentials need to be passed to the command line tools via CLI arguments or by setting the environment variables\n`USGS_USERNAME` and `USGS_AUTH`.\n\n| **Feature/Functionality** | **Usable** | **Note** |\n|:--------------------------------------------------:|:----------:|:--------------------------------------------------------------------------------:|\n| Searching for scenes | Yes | |\n| Creating scene lists out of search results | Yes | |\n| Generate orders from scene searches or scene lists | No | Downloading orders from list, when order was placed via webinterface is possible |\n| Geocoding | Yes | |\n| WRS1/WRS2 to coordinate transformation | Yes | |\n\n### Command Line Tool Examples\n\n#### Download\n\nThe snippet below queries the EarthExplorer catalogue for Landsat 8/9 Collection 2 Level 2 scenes between June 1st, 2020 and\nJuly 25th, 2024 for a small part of the southwest of Berlin, Germany. Additionally, only scenes for August and September are \nreturned and they must have a cloudcover of no more than 15%. Results are stored in a directory called `download`. The user \nset the logging level to `INFO` with the `-v` flag.\n\n```bash\ncallusgs -v download --product landsat_etm_c2_l2 \\\n --date 2020-06-01 2024-07-25 --month aug sep \\\n --cloudcover 0 15 --aoi-coordinates 52.5 13.4 52.5 13.2 52.7 13.2 52.5 13.4 -- download\n```\n\nThe snippet below queries the EarthExplorer catalogue for Landsat 7 Collection 2 Level 1 scenes between January 1st, 2005 and\nJanuary 1st, 2020 for Lima, Peru, and its surrounding region. For the given polygon, the minimum bound recatangle is build and used for the query.\nNo further restrictions regarding the obervation months or cloudcouver are posed. Results **would be** stored in a directory called `download`,\nbut as a dry run is requested, only the number of available scenes and their download size is reported. The user requested extended debug output with\nthe `-vv` flag.\n\n```bash\ncallusgs -vv --dry-run download --product landsat_etm_c2_l1 \\\n --date 2005-01-01 2020-01-01 --aoi-type Mbr \\\n --aoi-coordinates -11.99 -77.13 -11.97 -77.00 -12.01 -76.88 -12.07 -76.88 -12.13 -76.89 -12.07 -77.16 -11.99 -77.13 -- \\\n download\n```\n\n#### Geocode\n\nThe USGS supplies a simplistic geocoding/POI-search endpoint which can be queries using the `geocode` sub-program.\nThe snippet below queries all U.S. features whos placename attribute matches \"New York\".\n\n> Right now, the `placename` endpoint, which is called under the hood, does not return any results for features of type \"world\"!\n\n```bash\ncallusgs geocode --feature-type US \"New York\"\n```\n\n#### Grid2ll\n\nGet either centroids or polygons of the WRS2 or WRS2 coordinate system based on geographic coordinates in WGS84 (EPSG:4326) inputs.\nThe snipped below queries the centroid coordinates for three points in the WRS2 system.\n\n```bash\ncallusgs grid2ll --response-shape point 52,11 32,5 89,69\n```\n\n#### Clean\n\nThe `clean` subprogram is used to delete dangeling product/scene orders.\n\n```bash\ncallusgs -v clean\n```\n\n## Known Limitations\n\n- The download program will only start the download of orders once all scenes are available. Thus, your order might not get downloaded\nimmediately if only one scene is still being processed.\n- The geocoding/place search endpoint of USGS's API currently does not seem to work with non-US features. This may be a bug in the program.\n\n## Documentation\n\nSee the docs folder for raw documentation or visit [callusgs.readthedocs.io](https://callusgs.readthedocs.io).\n\n## License\n\n- `callusgs` is licensed under the [GPL-v2](LICENSE)\n\n## Citation\n\nIf you use this software, please use the bibtex entry below or refer to [the citation file](CITATION.cff).\n\n```tex\n@software{Katerndahl2024,\nauthor = {Katerndahl, Florian},\ntitle = {callusgs},\nurl = {https://github.com/Florian-Katerndahl/callusgs}\n}\n```\n\n## Acknowledgments\n\n- Most of the docstrings were provided by the USGS in their API documentation. \n- The download application took initial inspiration from [the example script provided by the USGS](https://m2m.cr.usgs.gov/api/docs/example/download_data-py).\n",
"bugtrack_url": null,
"license": "GPL-2.0-only",
"summary": "Implementation of USGS's machine-to-machine API (v1.5.0)",
"version": "0.1.2",
"project_urls": {
"Bug Tracker": "https://github.com/Florian-Katerndahl/callusgs/issues",
"Documentation": "https://callusgs.readthedocs.io/",
"Homepage": "https://github.com/Florian-Katerndahl/callusgs",
"Repository": "https://github.com/Florian-Katerndahl/callusgs"
},
"split_keywords": [
"usgs",
" api",
" machine-to-machine",
" landsat",
" cli",
" geodata",
" gis",
" eros",
" download",
" earthexplorer"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "958f84a41e6d6819bb5e10192d217149986eaf0c2abb41b494c930ad73733c57",
"md5": "a31a238dd9cb73a37eb3aef7d0e16cc8",
"sha256": "04e0f49cc44a1f7dbb9917b791d9d4090e2b3f27c9826dbb6d7a7f8dbf8fe574"
},
"downloads": -1,
"filename": "callusgs-0.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a31a238dd9cb73a37eb3aef7d0e16cc8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 48523,
"upload_time": "2024-08-14T10:05:56",
"upload_time_iso_8601": "2024-08-14T10:05:56.397755Z",
"url": "https://files.pythonhosted.org/packages/95/8f/84a41e6d6819bb5e10192d217149986eaf0c2abb41b494c930ad73733c57/callusgs-0.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f838e0c64ba91201b4dbbf6c4b03e202676dcc74359bad23249a9e32fa968dc4",
"md5": "9d252e79c478eadbdc354dd9f989b8b9",
"sha256": "40c5fe719c0ac8800f3276356a3ae91c49d8bd9a77b1833793ca3293962c2098"
},
"downloads": -1,
"filename": "callusgs-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "9d252e79c478eadbdc354dd9f989b8b9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9",
"size": 48386,
"upload_time": "2024-08-14T10:05:58",
"upload_time_iso_8601": "2024-08-14T10:05:58.122577Z",
"url": "https://files.pythonhosted.org/packages/f8/38/e0c64ba91201b4dbbf6c4b03e202676dcc74359bad23249a9e32fa968dc4/callusgs-0.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-14 10:05:58",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Florian-Katerndahl",
"github_project": "callusgs",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "callusgs"
}
JSON
