usgsxplore

Python client for the USGS M2M API — search, download, and process Earth observation imagery from EarthExplorer.

Supports 100+ datasets (Landsat, Hexagon KH-9, declassified imagery, aerial photos, and more). Provides both a CLI and a Python API.

Inspired by landsatxplore, with broader dataset support and additional features.

Installation

pip install usgsxplore

# or with pipx (recommended for CLI use)
pipx install usgsxplore

Credentials

You need a USGS ERS account with M2M API access enabled.

1. Register at ers.cr.usgs.gov/register
2. Request M2M API access at ers.cr.usgs.gov/profile/access — specify the datasets you plan to use
3. Use your username and M2M token (not your password)

Set credentials as environment variables to avoid typing them every time:

export USGS_USERNAME=<your_username>
export USGS_TOKEN=<your_token>

Quick start

# Search for Landsat scenes at a location between 2010 and 2020
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, export to GeoPackage and visualize them on an HTML map
usgsxplore search declassii --filter "camera=H" --output results.gpkg
usgsxplore viz map results.gpkg --output-file map.html

# Download the first 10 results
usgsxplore search landsat_tm_c2_l1 --limit 10 --output results.txt
usgsxplore download results.txt

CLI Reference

usgsxplore [OPTIONS] COMMAND [ARGS]...

Commands:
  search           Search scenes in a dataset
  download         Download scenes from a text file of entity IDs
  download-browse  Download individual browse (preview) images from a vector file
  viz              Visualize scenes from a vector file (map, footprint, density, strip)
  info             List available datasets and metadata filters

search

Search scenes in a dataset, with optional spatial, temporal, and metadata filters.

usgsxplore search [OPTIONS] DATASET

Output formats:

Multiple outputs can be specified simultaneously:

usgsxplore search declassii --filter "camera=H" --output scenes.gpkg --output scenes.txt

download

Download scenes from a .txt file of entity IDs (produced by search).

usgsxplore download [OPTIONS] TEXTFILE

The .txt file header line #dataset=<name> is read automatically, so passing -d is optional if the file was generated by search.

download-browse

Download individual browse (preview) images from a vector file. Each scene is saved as a separate file named after its entity_id.

usgsxplore download-browse [OPTIONS] VECTOR_FILE

TIF files are georeferenced using corner coordinate columns from the vector file. JPG files are saved without georeferencing.

# Download as georeferenced GeoTIFF (default)
usgsxplore download-browse results.gpkg -o ./previews/

# Download as JPEG
usgsxplore download-browse results.gpkg -o ./previews/ --format jpg

viz

Visualize scenes from a vector file (produced by search).

usgsxplore viz COMMAND [OPTIONS] VECTOR_FILE

Options shared by every viz command:

Only one ROI option can be given. map, footprint and density take -o / --output-file; strip takes -o / --output-dir, plus:

usgsxplore viz map results.gpkg -o map.html --roi-bbox 5.5 45 6 45.5
usgsxplore viz strip results.gpkg -o ./strips/ -roi roi.geojson --no-clean

See docs/figures.md for example outputs.

info

# List all available datasets
usgsxplore info dataset

# List available metadata filters for a dataset
usgsxplore info filters DATASET

Tip: Trigger filter help directly from a search by using an invalid value:

# List all filter fields for the declassii dataset
usgsxplore search declassii -f "whatever=?"

# List all valid values for the "camera" filter
usgsxplore search declassii -f "camera=?"

Filter syntax

The --filter option accepts a human-readable expression:

"field1=value1 & field2=value2 | field3=value3"

Fields can be identified by their filter ID, label, or SQL field name. Values can be the raw value or the display label. All of the following are equivalent:

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"

Combine multiple filters:

# KH-9 scenes that are available for download
usgsxplore search declassii --filter "camera=L & DOWNLOAD_AVAILABLE=Y"

Python API

All CLI commands have equivalent Python functions in usgsxplore.core:

from usgsxplore.core import (
    search_scenes,
    download_scenes,
    download_browse_images,
    list_datasets,
    list_dataset_filters,
)

Search

# Print entity IDs to stdout
search_scenes(
    "landsat_tm_c2_l1",
    location=(5.7074, 45.1611),
    interval_date=("2010-01-01", "2020-01-01"),
)

# Save to multiple formats
search_scenes(
    "declassii",
    output_files=["results.gpkg", "results.txt"],
    filter_str="camera=H",
    limit=500,
    show_progress=True,
)

Credentials are read from USGS_USERNAME / USGS_TOKEN environment variables by default, or can be passed explicitly:

search_scenes("declassii", username="myuser", token="mytoken", ...)

Download

download_scenes(
    "results.txt",
    output_dir="./data",
    max_workers=8,
)

Browse images

# Download as georeferenced GeoTIFF (default)
download_browse_images("results.gpkg", output_dir="./previews")

# Download as JPEG
download_browse_images("results.gpkg", output_dir="./previews", fmt="jpg")

# Advanced: use BrowseDownloader directly with a custom strategy
from usgsxplore.browse import BrowseDownloader, TifSaveStrategy, JpgSaveStrategy

downloader = BrowseDownloader("./previews", TifSaveStrategy(), max_workers=8)
downloader.download("results.gpkg")

Figures

from usgsxplore.viz.html_map import generate_html_map
from usgsxplore.viz.scenes_density import generate_scenes_density
from usgsxplore.viz.scenes_footprint import generate_scenes_footprint
from usgsxplore.viz.strip_figures import generate_strip_figures

# Interactive map of scene footprints, with browse images in popups
generate_html_map("results.gpkg", "map.html")

# One image of all scene footprints, with the ROI outlined (the output directory must exist)
generate_scenes_footprint("results.gpkg", "footprint.png", roi="roi.geojson")

# The ROI can also be a GeoDataFrame or a shapely geometry in longitude/latitude
from shapely import box

generate_scenes_footprint("results.gpkg", "footprint.png", roi=box(5.5, 45, 6, 45.5))

# Scene overlap density, with a 1 km pixel size (in Web Mercator meters)
generate_scenes_density("results.gpkg", "density.png", roi="roi.geojson", resolution=1000)

# One figure per strip
generate_strip_figures("results.gpkg", "./strips", roi="roi.geojson")

Inspect datasets and filters

# List datasets
datasets = list_datasets()

# List filters for a dataset
filters = list_dataset_filters("declassii")
for f in filters:
    print(f["fieldLabel"], "→", f["searchSql"])

For a full example notebook, see examples/download.ipynb.

Contributing

See CONTRIBUTING.md.