landsatxplore

To use landsatxplore, you must have Earth Explorer credentials. You can provide your username and password via command-line options (--username, --password) or by setting the following environment variables:

export LANDSATXPLORE_USERNAME=<your_username>
export LANDSATXPLORE_PASSWORD=<your_password>

You can install the landsatxplore package using pip to access the EarthExplorer interface via CLI or Python API.

pip install landsatxplore

To interact with the USGS M2M API, instantiate the API class with your USGS EarthExplorer credentials. The constructor automatically performs a login to obtain an access token.

from landsatxplore.api import API

api = API(username='your_username', password='your_password')

The API.search() method provides a high-level way to search for scenes using common parameters like dataset, latitude, longitude, start_date, end_date, and max_cloud_cover.

import json
from landsatxplore.api import API

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.")

for scene in scenes:
    print(scene['acquisition_date'].strftime('%Y-%m-%d'))
    # Example: 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()

The landsatxplore.api.API class provides a low-level interface to the Earth Explorer JSON API. You can initialize an instance with your credentials, perform arbitrary requests to endpoints, and then log out.

Workflow:

1. Initialize API(username, password).
2. Call api.request(endpoint, params={...}) to interact with the JSON API.
3. Call api.logout() to end the session.

from landsatxplore.api import API

api = API(username, password)
response = api.request(
    '<request_endpoint>',
    params={
        "param_1": value_1,
        "param_2": value_2
    }
)
api.logout()

The landsatxplore.earthexplorer.EarthExplorer class is a high-level wrapper designed specifically for downloading scenes.

from landsatxplore.earthexplorer import EarthExplorer

ee = EarthExplorer(username, password)

ee.download('LT51960471995178MPS00', output_dir='./data')

ee.logout()

The following dataset IDs are supported by the package:

The API class automatically handles certain error types and rate limits:

• Rate Limiting: If a RATE_LIMIT error is encountered, the client will automatically sleep for 3 seconds and retry the request once.
• Authentication Errors: Raises USGSAuthenticationError for invalid or unauthorized credentials (AUTH_INVALID, AUTH_UNAUTHROIZED, AUTH_KEY_INVALID).
• General Errors: Raises USGSError for other non-null error codes returned by the API.

Ensure you catch these exceptions in your application logic to handle session expiration or service outages.

Use the landsatxplore download command to download one or more scenes. If the --dataset is not provided, the package attempts to guess it from the scene identifier. For Landsat Collection 2 products, it is recommended to set the --dataset option explicitly.

Options:

• -d, --dataset: The dataset ID.
• -o, --output: The output directory path.
• -t, --timeout: Download timeout in seconds.
• --skip: Skip existing files.
• [SCENES]...: One or more scene identifiers.

# Download specific scenes to the current directory
landsatxplore download LT51960471995178MPS00 LC80390222013076EDC00 LC82150682015350LGN01

Two utility functions are provided for string transformation:

1. title_to_snake(src_string): Converts a title string to snake_case. It replaces spaces with underscores and forward slashes / with hyphens -.
2. camel_to_snake(src_string): Converts a camelCase string to snake_case by inserting underscores before uppercase letters and converting the entire string to lowercase.

from landsatxplore.util import title_to_snake, camel_to_snake

print(title_to_snake("My Title/String"))  # 'my_title-string'
print(camel_to_snake("myCamelCaseString")) # 'my_camel_case_string'