United States Geological Survey¤

The Machine-to-Machine (M2M) API from the United States Geological Survey (USGS) is an alternative method for searching and retrieving data from USGS/EROS data inventories. It provides the same features and functionality as the USGS EarthExplorer web application, allowing programmatic access to datasets.

Getting Access to the M2M API¤

An USGS account is required to use the M2M API. You can create an account by registering here.
After creating an account, request access to the M2M API using the API access form. Approval may take several days.
Instead of using your account password for programmatic logins, generate an application token here. Tokens can be revoked at any time, and you can generate up to 10 tokens per account.

Parametes¤

Name	Type	Description
`out_dir`	`str`	Output direcotry. If the directory already contains previously downloaded scenes, these are treated as cached and excluded from the download.
`dataset`	`str \\| Dataset`	The dataset to query. A list of all available datasets can be found here. Some common datasets are also available as enumerations in `USGS.Dataset`.
`shapefile_path`	`str`	Path to a valid shapefile. Supported formats: `.shp`, `.geojson`, `.kml`, `.gpkg`. You can find shapefiles from sources like OSM Boundaries.
`start_date`	`str`	Start date for temporal filtering. Date string muste be in format `yyyy-mm-dd`.
`end_date`	`str`	End date for temporal filtering. Date string muste be in format `yyyy-mm-dd`. Default is `None` which meants until the present.

Example¤

Python

from sipt.retrieval import USGS

dataset = USGS.Dataset.LANDSAT_8_9_L2
# Alternatively:
dataset = 'Landsat 8-9 OLI/TIRS C2 L2'

user = "..."
token = "..."

# Initialize the USGS API
usgs = USGS(user, token)
# Start the data download
usgs.retrieve("./data", dataset, "path/to/your/shapefile.geojson", '2023-07-01', '2024-08-01')