[](https://github.com/yannforget/landsatxplore/actions/workflows/python-publish.yml)
[](https://github.com/yannforget/landsatxplore/actions/workflows/run-tests.yml)
[](https://codecov.io/gh/yannforget/landsatxplore)
[](https://zenodo.org/record/4543601)
# Description
The **landsatxplore** Python package provides an interface to the [EarthExplorer](http://earthexplorer.usgs.gov/) portal to search and download [Landsat Collections](https://landsat.usgs.gov/landsat-collections) scenes through a command-line interface or a Python API.
The following datasets are supported:
| Dataset Name | Dataset ID |
|-|-|
| Landsat 5 TM Collection 2 Level 1 | `landsat_tm_c2_l1` |
| Landsat 5 TM Collection 2 Level 2 | `landsat_tm_c2_l2` |
| Landsat 7 ETM+ Collection 2 Level 1 | `landsat_etm_c2_l1` |
| Landsat 7 ETM+ Collection 2 Level 2 | `landsat_etm_c2_l2` |
| Landsat 8 Collection 2 Level 1 | `landsat_ot_c2_l1` |
| Landsat 8 Collection 2 Level 2 | `landsat_ot_c2_l2` |
| Landsat 9 Collection 2 Level 1 | `landsat_ot_c2_l1` |
| Landsat 9 Collection 2 Level 2 | `landsat_ot_c2_l2` |
# Quick start
Searching for Landsat 5 TM scenes that contains the location (12.53, -1.53) acquired during the year 1995.
```
landsatxplore search --dataset landsat_tm_c2_l1 --location 12.53 -1.53 \
--start 1995-01-01 --end 1995-12-31
```
Search for Landsat 7 ETM scenes in Brussels with less than 5% of clouds. Save the returned results in a `.csv` file.
```
landsatxplore search --dataset landsat_tm_c2_l2 \
--location 50.83 4.38 --clouds 5 > results.csv
```
Downloading three Landsat scenes from different datasets in the current directory.
```
landsatxplore download LT51960471995178MPS00 LC80390222013076EDC00 LC82150682015350LGN01
```
To use the package, Earth Explorer credentials are required ([registration](https://ers.cr.usgs.gov/register)).
# Installation
The package can be installed using pip.
```
pip install landsatxplore
```
# Usage
**landsatxplore** can be used both through its command-line interface and as a Python module.
## Command-line interface
```
landsatxplore --help
```
```
Usage: landsatxplore [OPTIONS] COMMAND [ARGS]...
Options:
--help Show this message and exit.
Commands:
download Download one or several Landsat scenes.
search Search for Landsat scenes.
```
### Credentials
Credentials for the Earth Explorer portal can be obtained [here](https://ers.cr.usgs.gov/register/).
`--username` and `--password` can be provided as command-line options or as environment variables:
``` shell
export LANDSATXPLORE_USERNAME=<your_username>
export LANDSATXPLORE_PASSWORD=<your_password>
```
### Searching
```
landsatxplore search --help
```
```
Usage: landsatxplore search [OPTIONS]
Search for Landsat scenes.
Options:
-u, --username TEXT EarthExplorer username.
-p, --password TEXT EarthExplorer password.
-d, --dataset [landsat_tm_c1|landsat_etm_c1|landsat_8_c1|landsat_tm_c2_l1|landsat_tm_c2_l2|landsat_etm_c2_l1|landsat_etm_c2_l2|landsat_ot_c2_l1|landsat_ot_c2_l2|sentinel_2a]
Landsat data set.
-l, --location FLOAT... Point of interest (latitude, longitude).
-b, --bbox FLOAT... Bounding box (xmin, ymin, xmax, ymax).
-c, --clouds INTEGER Max. cloud cover (1-100).
-s, --start TEXT Start date (YYYY-MM-DD).
-e, --end TEXT End date (YYYY-MM-DD).
-o, --output [entity_id|display_id|json|csv]
Output format.
-m, --limit INTEGER Max. results returned.
--help Show this message and exit.
```
### Downloading
```
landsatxplore download --help
```
```
Usage: landsatxplore download [OPTIONS] [SCENES]...
Download one or several Landsat scenes.
Options:
-u, --username TEXT EarthExplorer username.
-p, --password TEXT EarthExplorer password.
-d, --dataset TEXT Dataset.
-o, --output PATH Output directory.
-t, --timeout INTEGER Download timeout in seconds.
--skip
--help Show this message and exit.
```
If the `--dataset` is not provided, the dataset is automatically guessed from the scene identifier. Note that only the newer Landsat Product Identifiers contain information related to collection number and processing level. To download Landsat Collection 2 products, use Product IDs or set the `--dataset` option correctly.
## API
### EarthExplorer API
**landsatxplore** provides an interface to the Earth Explorer JSON API. Please refer to the official ([documentation](https://earthexplorer.usgs.gov/inventory/documentation/json-api)) for possible request codes and parameters.
#### Basic usage
``` python
from landsatxplore.api import API
# Initialize a new API instance and get an access key
api = API(username, password)
# Perform a request. Results are returned in a dictionnary
response = api.request(
'<request_endpoint>',
params={
"param_1": value_1,
"param_2": value_2
}
)
# Log out
api.logout()
```
Please refer to the official [JSON API Reference](https://m2m.cr.usgs.gov/api/docs/json/) for a list of all available requests.
#### Searching for scenes
``` python
import json
from landsatxplore.api import API
# Initialize a new API instance and get an access key
api = API(username, password)
# Search for Landsat TM scenes
scenes = api.search(
dataset='landsat_tm_c2_l1',
latitude=50.85,
longitude=-4.35,
start_date='1995-01-01',
end_date='1995-10-01',
max_cloud_cover=10
)
print(f"{len(scenes)} scenes found.")
# Process the result
for scene in scenes:
print(scene['acquisition_date'].strftime('%Y-%m-%d'))
# Write scene footprints to disk
fname = f"{scene['landsat_product_id']}.geojson"
with open(fname, "w") as f:
json.dump(scene['spatial_coverage'].__geo_interface__, f)
api.logout()
```
Output:
```
4 scenes found.
1995-09-23
1995-08-22
1995-08-15
1995-06-28
```
#### Downloading scenes
``` python
from landsatxplore.earthexplorer import EarthExplorer
ee = EarthExplorer(username, password)
ee.download('LT51960471995178MPS00', output_dir='./data')
ee.logout()
```
Raw data
{
"_id": null,
"home_page": "https://github.com/yannforget/landsatxplore",
"name": "landsatxplore",
"maintainer": "Yann Forget",
"docs_url": null,
"requires_python": ">=3.7,<4.0",
"maintainer_email": "yannforget@mailbox.org",
"keywords": "earth observation,remote sesing,GIS,satellite imagery,landsat,sentinel,usgs",
"author": "Yann Forget",
"author_email": "yannforget@mailbox.org",
"download_url": "https://files.pythonhosted.org/packages/12/b3/fb5d1b714a1e5073f4f5c145456a4ac343ba4bc3a1a1757e58761dfbfac8/landsatxplore-0.15.0.tar.gz",
"platform": null,
"description": "[](https://github.com/yannforget/landsatxplore/actions/workflows/python-publish.yml)\n[](https://github.com/yannforget/landsatxplore/actions/workflows/run-tests.yml)\n[](https://codecov.io/gh/yannforget/landsatxplore)\n[](https://zenodo.org/record/4543601)\n\n# Description\n\n\n\nThe **landsatxplore** Python package provides an interface to the [EarthExplorer](http://earthexplorer.usgs.gov/) portal to search and download [Landsat Collections](https://landsat.usgs.gov/landsat-collections) scenes through a command-line interface or a Python API.\n\nThe following datasets are supported:\n\n\n| Dataset Name | Dataset ID |\n|-|-|\n| Landsat 5 TM Collection 2 Level 1 | `landsat_tm_c2_l1` |\n| Landsat 5 TM Collection 2 Level 2 | `landsat_tm_c2_l2` |\n| Landsat 7 ETM+ Collection 2 Level 1 | `landsat_etm_c2_l1` |\n| Landsat 7 ETM+ Collection 2 Level 2 | `landsat_etm_c2_l2` |\n| Landsat 8 Collection 2 Level 1 | `landsat_ot_c2_l1` |\n| Landsat 8 Collection 2 Level 2 | `landsat_ot_c2_l2` |\n| Landsat 9 Collection 2 Level 1 | `landsat_ot_c2_l1` |\n| Landsat 9 Collection 2 Level 2 | `landsat_ot_c2_l2` |\n\n# Quick start\n\nSearching for Landsat 5 TM scenes that contains the location (12.53, -1.53) acquired during the year 1995.\n\n```\nlandsatxplore search --dataset landsat_tm_c2_l1 --location 12.53 -1.53 \\\n --start 1995-01-01 --end 1995-12-31\n```\n\nSearch for Landsat 7 ETM scenes in Brussels with less than 5% of clouds. Save the returned results in a `.csv` file.\n\n```\nlandsatxplore search --dataset landsat_tm_c2_l2 \\\n --location 50.83 4.38 --clouds 5 > results.csv\n```\n\nDownloading three Landsat scenes from different datasets in the current directory.\n\n```\nlandsatxplore download LT51960471995178MPS00 LC80390222013076EDC00 LC82150682015350LGN01\n```\n\nTo use the package, Earth Explorer credentials are required ([registration](https://ers.cr.usgs.gov/register)).\n\n# Installation\n\nThe package can be installed using pip.\n\n```\npip install landsatxplore\n```\n\n# Usage\n\n**landsatxplore** can be used both through its command-line interface and as a Python module.\n\n## Command-line interface\n\n```\nlandsatxplore --help\n```\n\n```\nUsage: landsatxplore [OPTIONS] COMMAND [ARGS]...\n\nOptions:\n --help Show this message and exit.\n\nCommands:\n download Download one or several Landsat scenes.\n search Search for Landsat scenes.\n```\n\n### Credentials\n\nCredentials for the Earth Explorer portal can be obtained [here](https://ers.cr.usgs.gov/register/).\n\n`--username` and `--password` can be provided as command-line options or as environment variables:\n\n``` shell\nexport LANDSATXPLORE_USERNAME=<your_username>\nexport LANDSATXPLORE_PASSWORD=<your_password>\n```\n\n### Searching\n\n```\nlandsatxplore search --help\n```\n\n```\nUsage: landsatxplore search [OPTIONS]\n\n Search for Landsat scenes.\n\nOptions:\n -u, --username TEXT EarthExplorer username.\n -p, --password TEXT EarthExplorer password.\n -d, --dataset [landsat_tm_c1|landsat_etm_c1|landsat_8_c1|landsat_tm_c2_l1|landsat_tm_c2_l2|landsat_etm_c2_l1|landsat_etm_c2_l2|landsat_ot_c2_l1|landsat_ot_c2_l2|sentinel_2a]\n Landsat data set.\n -l, --location FLOAT... Point of interest (latitude, longitude).\n -b, --bbox FLOAT... Bounding box (xmin, ymin, xmax, ymax).\n -c, --clouds INTEGER Max. cloud cover (1-100).\n -s, --start TEXT Start date (YYYY-MM-DD).\n -e, --end TEXT End date (YYYY-MM-DD).\n -o, --output [entity_id|display_id|json|csv]\n Output format.\n -m, --limit INTEGER Max. results returned.\n --help Show this message and exit.\n```\n\n### Downloading\n\n```\nlandsatxplore download --help\n```\n\n```\nUsage: landsatxplore download [OPTIONS] [SCENES]...\n\n Download one or several Landsat scenes.\n\nOptions:\n -u, --username TEXT EarthExplorer username.\n -p, --password TEXT EarthExplorer password.\n -d, --dataset TEXT Dataset.\n -o, --output PATH Output directory.\n -t, --timeout INTEGER Download timeout in seconds.\n --skip\n --help Show this message and exit.\n```\n\nIf the `--dataset` is not provided, the dataset is automatically guessed from the scene identifier. Note that only the newer Landsat Product Identifiers contain information related to collection number and processing level. To download Landsat Collection 2 products, use Product IDs or set the `--dataset` option correctly.\n\n\n## API\n\n### EarthExplorer API\n\n**landsatxplore** provides an interface to the Earth Explorer JSON API. Please refer to the official ([documentation](https://earthexplorer.usgs.gov/inventory/documentation/json-api)) for possible request codes and parameters.\n\n#### Basic usage\n\n``` python\nfrom landsatxplore.api import API\n\n# Initialize a new API instance and get an access key\napi = API(username, password)\n\n# Perform a request. Results are returned in a dictionnary\nresponse = api.request(\n '<request_endpoint>',\n params={\n \"param_1\": value_1,\n \"param_2\": value_2\n }\n)\n\n#\u00a0Log out\napi.logout()\n```\n\nPlease refer to the official [JSON API Reference](https://m2m.cr.usgs.gov/api/docs/json/) for a list of all available requests.\n\n#### Searching for scenes\n\n``` python\nimport json\nfrom landsatxplore.api import API\n\n# Initialize a new API instance and get an access key\napi = API(username, password)\n\n# Search for Landsat TM scenes\nscenes = api.search(\n dataset='landsat_tm_c2_l1',\n latitude=50.85,\n longitude=-4.35,\n start_date='1995-01-01',\n end_date='1995-10-01',\n max_cloud_cover=10\n)\n\nprint(f\"{len(scenes)} scenes found.\")\n\n# Process the result\nfor scene in scenes:\n print(scene['acquisition_date'].strftime('%Y-%m-%d'))\n # Write scene footprints to disk\n fname = f\"{scene['landsat_product_id']}.geojson\"\n with open(fname, \"w\") as f:\n json.dump(scene['spatial_coverage'].__geo_interface__, f)\n\napi.logout()\n```\n\nOutput:\n\n```\n4 scenes found.\n1995-09-23\n1995-08-22\n1995-08-15\n1995-06-28\n```\n\n#### Downloading scenes\n\n``` python\nfrom landsatxplore.earthexplorer import EarthExplorer\n\nee = EarthExplorer(username, password)\n\nee.download('LT51960471995178MPS00', output_dir='./data')\n\nee.logout()\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Search and download Landsat scenes from EarthExplorer",
"version": "0.15.0",
"split_keywords": [
"earth observation",
"remote sesing",
"gis",
"satellite imagery",
"landsat",
"sentinel",
"usgs"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "fe743e17fccba42cb33dc5320aa2803d66c171c22dbe8f17d1a77354cd6b08dc",
"md5": "78c02070461d443b57ba0112350d7a60",
"sha256": "826733853386cb1f5d622ecfd6eaa643f22dfdf5162cfc85a97a58b7ca0c95f8"
},
"downloads": -1,
"filename": "landsatxplore-0.15.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "78c02070461d443b57ba0112350d7a60",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7,<4.0",
"size": 15438,
"upload_time": "2023-04-11T19:12:12",
"upload_time_iso_8601": "2023-04-11T19:12:12.707068Z",
"url": "https://files.pythonhosted.org/packages/fe/74/3e17fccba42cb33dc5320aa2803d66c171c22dbe8f17d1a77354cd6b08dc/landsatxplore-0.15.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "12b3fb5d1b714a1e5073f4f5c145456a4ac343ba4bc3a1a1757e58761dfbfac8",
"md5": "9fe4c61d2fa2852aa59e1f0affb28796",
"sha256": "69031ac376d5fc5dcf5826a7217712529c16fb041524bbb7d68d24435eddf67e"
},
"downloads": -1,
"filename": "landsatxplore-0.15.0.tar.gz",
"has_sig": false,
"md5_digest": "9fe4c61d2fa2852aa59e1f0affb28796",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7,<4.0",
"size": 14847,
"upload_time": "2023-04-11T19:12:14",
"upload_time_iso_8601": "2023-04-11T19:12:14.529380Z",
"url": "https://files.pythonhosted.org/packages/12/b3/fb5d1b714a1e5073f4f5c145456a4ac343ba4bc3a1a1757e58761dfbfac8/landsatxplore-0.15.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-04-11 19:12:14",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "yannforget",
"github_project": "landsatxplore",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "landsatxplore"
}
JSON
