[](https://github.com/adehecq/usgs_explorer/actions/workflows/python-tests.yml)
# Description
The **usgsxplore** Python package provides an interface to the [USGS M2M API](https://m2m.cr.usgs.gov/) to search and download data available from the [Earth Explorer](https://earthexplorer.usgs.gov/) platform.
This package is highly inspired by [landsatxplore](https://github.com/yannforget/landsatxplore) but it supports more datasets and adds new functionalities.
# Quick start
Searching for Landsat scenes over the location (5.7074, 45.1611) acquired between 2010-2020.
```bash
usgsxplore search landsat_tm_c2_l1 --location 5.7074 45.1611 --interval-date 2010-01-01 2020-01-01
```
Search for Hexagon KH-9 scenes. Save the result into a geopackage
```bash
usgsxplore search declassii --filter "camera=H" --output results.gpkg
```
Downloading the 10 first images from landsat_tm_c2_l1
```bash
usgsxplore search landsat_tm_c2_l1 --limit 10 --output results.txt
usgsxplore download results.txt
```
# Installation
The package can be installed using pip.
```bash
pip install usgsxplore
# or with pipx
pipx install usgsxplore
```
# Usage
**usgsxplore** can be used both through its command-line interface and as a python module.
## Command-line interface
```bash
usgsxplore --help
```
```
Usage: usgsxplore [OPTIONS] COMMAND [ARGS]...
Command line interface of the usgsxplore. Documentation :
https://github.com/adehecq/usgs_explorer
Options:
--help Show this message and exit.
Commands:
download Download scenes with their entity ids provided in the textfile.
download-browse Download browse images of a vector data file localy.
info Display information on available datasets and filters.
search Search scenes in a dataset with filters.
```
### Credentials
Credentials for the Earth Explorer portal can be obtained [here](https://ers.cr.usgs.gov/register/). Note that you need to specify specifically all datasets you plan to access through the API.
Either one of the password or token must be provided.
`--username` and `--token` or `--password` can be provided as command-line options or as environment variables:
``` shell
export USGS_USERNAME=<your_username>
export USGS_TOKEN=<your_token>
export USGS_PASSWORD=<your_password>
```
### Searching
```bash
usgsxplore search --help
```
```
Usage: usgsxplore search [OPTIONS] DATASET
Search scenes in a dataset with filters.
Options:
-u, --username TEXT EarthExplorer username. [required]
-p, --password TEXT EarthExplorer password.
-t, --token TEXT EarthExplorer token.
-o, --output PATH Output file : (txt, json, gpkg, shp, geojson)
-l, --location FLOAT... Point of interest (longitude, latitude).
-b, --bbox FLOAT... Bounding box (xmin, ymin, xmax, ymax).
-c, --clouds INTEGER Max. cloud cover (1-100).
-i, --interval-date TEXT... Date interval (start, end), (YYYY-MM-DD, YYYY-
MM-DD).
-f, --filter TEXT String representation of metadata filter
-m, --limit INTEGER Max. results returned. Return all by default
--pbar Display a progress bar
--help Show this message and exit.
```
If the `--output` is not provided, the command will print the entity ids of scenes found. Else if `--output` is provided it will save the results in the given file. Five formats are currently supported for the output:
- **text file (.txt)** : Each line is an entity id and the first line contain the dataset ex: `#dataset=landsat_tm_c2_l1`. This file can then be used to download the images.
- **json file (.json)** : json file containing the results of the search.
- **vector data (.gpkg, .shp, .geojson)** : save the results in a vector file, useful to visualise the geographic location of the results in a GIS.
The search command works with multiple scene-search so there is no limit of results, but you can fixe one with `--limit`.
If you provide a wrong dataset, a list of 50 datasets with high string similarity will be printed.
The `--filter` works like this "`field1=value1 & field2=value2 | field3=value3`". For the field you can put either the filter id, the filter label, or the sql filter. For the value you can put either value or value label. Exemples:
```bash
# select scenes from the Hexagon KH-9 satellite
# all of those 4 command will give the same results
usgsxplore search declassii --filter "camera=L"
usgsxplore search declassii --filter "Camera Type=L"
usgsxplore search declassii --filter "5e839ff8cfa94807=L"
usgsxplore search declassii --filter "camera=KH-9 Lower Resolution Mapping Camera"
# select scenes from the Hexagon KH-9 satellites if they are downloadable
usgsxplore search declassii --filter "camera=L & DOWNLOAD_AVAILABLE=Y"
```
**Note**: To know which filters are available, check the command `usgsxplore info` below.
### Downloading
```bash
usgsxplore download --help
```
```
Usage: usgsxplore download [OPTIONS] TEXTFILE
Download scenes with their entity ids provided in the textfile. The dataset
can also be provide in the first line of the textfile : #dataset=declassii
Options:
-u, --username TEXT EarthExplorer username.
-p, --password TEXT EarthExplorer password.
-t, --token TEXT EarthExplorer token.
-d, --dataset TEXT Dataset
-o, --output-dir PATH Output directory
-b, --pbar INTEGER RANGE Type of progression displaying (0,1,2) [0<=x<=2]
-m, --max-thread INTEGER Max thread number (default: 5)
--overwrite Overwrite existing files
--help Show this message and exit.
```
This command download scenes from their entity ids in the `TEXTFILE` and save the results in `--output-dir`. It can display different type of progression depends on `--pbar` value:
- **0** : display nothing.
- **1** : display one progress bar for all scenes downloading.
- **2** : display a progress bar for each scenes downloading, with state information.
### Downloading browse
```bash
usgsxplore download-browse --help
```
```
Usage: usgsxplore download-browse [OPTIONS] VECTOR_FILE
Download browse images of a vector data file localy.
Options:
-o, --output-dir PATH Output directory
--pbar Display a progress bar.
--help Show this message and exit.
```
### Info: datasets and filters
Information on available datasets and filters can be printed on screen with the command `usgsxplore info`
```bash
usgsxplore info --help
```
```
Usage: usgsxplore info [OPTIONS] COMMAND [ARGS]...
Display information on available datasets and filters.
Options:
--help Show this message and exit.
Commands:
dataset Display the list of available datasets in the API.
filters Display a list of available filter fields for a dataset.
```
**Hints**: When using `usgsxplore search`, filters will be printed to screen when typing any (wrong) value. For example,
```bash
usgsxplore search declassii -f "whatever=?"
```
will print all metadata filters that can be used for the "declassii" dataset.
<img width="439" alt="image" src="https://github.com/user-attachments/assets/e3fc1fdc-9ee2-4ddb-a9a4-863c5884a1d3">
```bash
usgsxplore search declassii -f "camera=?"
```
will print all possible values for the filter "camera".
<img width="391" alt="image" src="https://github.com/user-attachments/assets/bcdedad7-39b0-44de-bf8c-fc7e4ca5f1ee">
Raw data
{
"_id": null,
"home_page": "https://github.com/adehecq/usgs_explorer",
"name": "usgsxplore",
"maintainer": "Amaury Dehecq",
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": "this-is-not-an-email@a.com",
"keywords": "earth observation, remote sesing, GIS, satellite imagery, USGS, M2M",
"author": "Godin Luc",
"author_email": "godin.luc2002@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/a2/0c/8bb377a33c24686bd3bb2f0a39767270de8208354e00a5b9e6227338f74c/usgsxplore-1.0.1.tar.gz",
"platform": null,
"description": "[](https://github.com/adehecq/usgs_explorer/actions/workflows/python-tests.yml)\n\n\n# Description\n\nThe **usgsxplore** Python package provides an interface to the [USGS M2M API](https://m2m.cr.usgs.gov/) to search and download data available from the [Earth Explorer](https://earthexplorer.usgs.gov/) platform.\n\nThis package is highly inspired by [landsatxplore](https://github.com/yannforget/landsatxplore) but it supports more datasets and adds new functionalities.\n\n# Quick start\n\nSearching for Landsat scenes over the location (5.7074, 45.1611) acquired between 2010-2020.\n\n```bash\nusgsxplore search landsat_tm_c2_l1 --location 5.7074 45.1611 --interval-date 2010-01-01 2020-01-01\n```\n\nSearch for Hexagon KH-9 scenes. Save the result into a geopackage\n\n```bash\nusgsxplore search declassii --filter \"camera=H\" --output results.gpkg\n```\n\nDownloading the 10 first images from landsat_tm_c2_l1\n```bash\nusgsxplore search landsat_tm_c2_l1 --limit 10 --output results.txt\nusgsxplore download results.txt\n```\n\n# Installation\n\nThe package can be installed using pip.\n\n```bash\npip install usgsxplore\n\n# or with pipx\npipx install usgsxplore\n```\n\n# Usage\n\n**usgsxplore** can be used both through its command-line interface and as a python module.\n\n## Command-line interface\n\n```bash\nusgsxplore --help\n```\n\n```\nUsage: usgsxplore [OPTIONS] COMMAND [ARGS]...\n\n Command line interface of the usgsxplore. Documentation :\n https://github.com/adehecq/usgs_explorer\n\nOptions:\n --help Show this message and exit.\n\nCommands:\n download Download scenes with their entity ids provided in the textfile.\n download-browse Download browse images of a vector data file localy.\n info Display information on available datasets and filters.\n search Search scenes in a dataset with filters.\n```\n\n### Credentials\n\nCredentials for the Earth Explorer portal can be obtained [here](https://ers.cr.usgs.gov/register/). Note that you need to specify specifically all datasets you plan to access through the API.\n\nEither one of the password or token must be provided.\n\n`--username` and `--token` or `--password` can be provided as command-line options or as environment variables:\n\n``` shell\nexport USGS_USERNAME=<your_username>\nexport USGS_TOKEN=<your_token>\nexport USGS_PASSWORD=<your_password>\n```\n\n### Searching\n\n```bash\nusgsxplore search --help\n```\n\n```\nUsage: usgsxplore search [OPTIONS] DATASET\n\n Search scenes in a dataset with filters.\n\nOptions:\n -u, --username TEXT EarthExplorer username. [required]\n -p, --password TEXT EarthExplorer password.\n -t, --token TEXT EarthExplorer token.\n -o, --output PATH Output file : (txt, json, gpkg, shp, geojson)\n -l, --location FLOAT... Point of interest (longitude, latitude).\n -b, --bbox FLOAT... Bounding box (xmin, ymin, xmax, ymax).\n -c, --clouds INTEGER Max. cloud cover (1-100).\n -i, --interval-date TEXT... Date interval (start, end), (YYYY-MM-DD, YYYY-\n MM-DD).\n -f, --filter TEXT String representation of metadata filter\n -m, --limit INTEGER Max. results returned. Return all by default\n --pbar Display a progress bar\n --help Show this message and exit.\n```\n\nIf the `--output` is not provided, the command will print the entity ids of scenes found. Else if `--output` is provided it will save the results in the given file. Five formats are currently supported for the output:\n- **text file (.txt)** : Each line is an entity id and the first line contain the dataset ex: `#dataset=landsat_tm_c2_l1`. This file can then be used to download the images.\n- **json file (.json)** : json file containing the results of the search.\n- **vector data (.gpkg, .shp, .geojson)** : save the results in a vector file, useful to visualise the geographic location of the results in a GIS.\n\nThe search command works with multiple scene-search so there is no limit of results, but you can fixe one with `--limit`.\n\nIf you provide a wrong dataset, a list of 50 datasets with high string similarity will be printed.\n\nThe `--filter` works like this \"`field1=value1 & field2=value2 | field3=value3`\". For the field you can put either the filter id, the filter label, or the sql filter. For the value you can put either value or value label. Exemples:\n```bash\n# select scenes from the Hexagon KH-9 satellite\n# all of those 4 command will give the same results\nusgsxplore search declassii --filter \"camera=L\"\nusgsxplore search declassii --filter \"Camera Type=L\"\nusgsxplore search declassii --filter \"5e839ff8cfa94807=L\"\nusgsxplore search declassii --filter \"camera=KH-9 Lower Resolution Mapping Camera\"\n\n# select scenes from the Hexagon KH-9 satellites if they are downloadable\nusgsxplore search declassii --filter \"camera=L & DOWNLOAD_AVAILABLE=Y\"\n```\n**Note**: To know which filters are available, check the command `usgsxplore info` below.\n\n### Downloading\n\n```bash\nusgsxplore download --help\n```\n```\nUsage: usgsxplore download [OPTIONS] TEXTFILE\n\n Download scenes with their entity ids provided in the textfile. The dataset\n can also be provide in the first line of the textfile : #dataset=declassii\n\nOptions:\n -u, --username TEXT EarthExplorer username.\n -p, --password TEXT EarthExplorer password.\n -t, --token TEXT EarthExplorer token.\n -d, --dataset TEXT Dataset\n -o, --output-dir PATH Output directory\n -b, --pbar INTEGER RANGE Type of progression displaying (0,1,2) [0<=x<=2]\n -m, --max-thread INTEGER Max thread number (default: 5)\n --overwrite Overwrite existing files\n --help Show this message and exit.\n```\nThis command download scenes from their entity ids in the `TEXTFILE` and save the results in `--output-dir`. It can display different type of progression depends on `--pbar` value:\n- **0** : display nothing.\n- **1** : display one progress bar for all scenes downloading.\n- **2** : display a progress bar for each scenes downloading, with state information.\n\n### Downloading browse\n\n```bash\nusgsxplore download-browse --help\n```\n```\nUsage: usgsxplore download-browse [OPTIONS] VECTOR_FILE\n\n Download browse images of a vector data file localy.\n\nOptions:\n -o, --output-dir PATH Output directory\n --pbar Display a progress bar.\n --help Show this message and exit.\n```\n\n### Info: datasets and filters\n\nInformation on available datasets and filters can be printed on screen with the command `usgsxplore info`\n```bash\nusgsxplore info --help\n```\n```\nUsage: usgsxplore info [OPTIONS] COMMAND [ARGS]...\n\n Display information on available datasets and filters.\n\nOptions:\n --help Show this message and exit.\n\nCommands:\n dataset Display the list of available datasets in the API.\n filters Display a list of available filter fields for a dataset.\n```\n\n**Hints**: When using `usgsxplore search`, filters will be printed to screen when typing any (wrong) value. For example,\n```bash\nusgsxplore search declassii -f \"whatever=?\"\n```\nwill print all metadata filters that can be used for the \"declassii\" dataset.\n\n<img width=\"439\" alt=\"image\" src=\"https://github.com/user-attachments/assets/e3fc1fdc-9ee2-4ddb-a9a4-863c5884a1d3\">\n\n```bash\nusgsxplore search declassii -f \"camera=?\"\n```\nwill print all possible values for the filter \"camera\".\n\n<img width=\"391\" alt=\"image\" src=\"https://github.com/user-attachments/assets/bcdedad7-39b0-44de-bf8c-fc7e4ca5f1ee\">\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Search and download data or scenes from USGS API",
"version": "1.0.1",
"project_urls": {
"Documentation": "https://github.com/adehecq/usgs_explorer",
"Homepage": "https://github.com/adehecq/usgs_explorer",
"Repository": "https://github.com/adehecq/usgs_explorer"
},
"split_keywords": [
"earth observation",
" remote sesing",
" gis",
" satellite imagery",
" usgs",
" m2m"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "984d2ffb2378d1be9afc0442f475ae33863d578cc7370d2b52597ec18aa3d41f",
"md5": "3dff0dc0b856283069fbdecf3b2b45cf",
"sha256": "198902ea08a11e9f065453ed679fe6bbade34572c788195e9f770ae9073688c5"
},
"downloads": -1,
"filename": "usgsxplore-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3dff0dc0b856283069fbdecf3b2b45cf",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 23456,
"upload_time": "2024-09-11T09:12:35",
"upload_time_iso_8601": "2024-09-11T09:12:35.782335Z",
"url": "https://files.pythonhosted.org/packages/98/4d/2ffb2378d1be9afc0442f475ae33863d578cc7370d2b52597ec18aa3d41f/usgsxplore-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a20c8bb377a33c24686bd3bb2f0a39767270de8208354e00a5b9e6227338f74c",
"md5": "5460d9c6ed3221c3397a8827e8e777ad",
"sha256": "31db81d69936e06d8bb09d851baf9f44c4c1be57a2c4e1c0ed68ae2d6b9b3264"
},
"downloads": -1,
"filename": "usgsxplore-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "5460d9c6ed3221c3397a8827e8e777ad",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 22264,
"upload_time": "2024-09-11T09:12:36",
"upload_time_iso_8601": "2024-09-11T09:12:36.829497Z",
"url": "https://files.pythonhosted.org/packages/a2/0c/8bb377a33c24686bd3bb2f0a39767270de8208354e00a5b9e6227338f74c/usgsxplore-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-11 09:12:36",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "adehecq",
"github_project": "usgs_explorer",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "usgsxplore"
}
JSON
