USGS Python API

NOTE: This is still in early stages and in no way should be used for production pipelines

An object oriented wrapper around the USGS Earth Explorer JSON API (v1.5.x). The primary objective of this API is to provide a convenient method of requesting and downloading scenes from EE datasets, including robust metadata where available.

API Documentation

https://cast.git-pages.uark.edu/transmap-hub/usgs/usgs/

Prerequisites

• Must have an Earth Explorer account: https://earthexplorer.usgs.gov
• The EE account must have M2M accesss, requested here: https://ers.cr.usgs.gov/profile/access (you will need to wait for approval)

Installation and Setup

Installing the python package

$ pip install usgs-m2m-api

Three methods for using your username and password

1. Using a .env file

EE_USER="user_name"
EE_PASS="user_pass"

2. Set your environment variables manually

$ export EE_USER="user_name"
$ export EE_PASS="user_pass"

3. During each execution you will be prompted for your user:pass if one of the above two options are not set
4. Hard code within script (not recommended) - see below

Installation (development)

$ pipenv install
$ pipenv run python ./example.py

Basic API structure

To query a specific item, like a dataset or a scene, you need to construct a Query object from that namespace (dataset.Query, scene.Query) and pass that to the Api with either a fetch or fetchone. This will return a Model or List[Model] of that type (dataset.Model, scene.Model)

Initialize the API

from usgs_api import Api
api = Api.login()
### If you want to directly type your user:password you can use
api = Api(username="user_name", password="password")

Query a dataset by name

dataset = api.dataset(datasetName="corona2")

Start a scene cursor with a list of scenes

scene_cursor = dataset.scenes()

Collect only available scenes to queue for download

downloadable = scene_cursor.downloadable

Iterate the cursor to collect more scenes

downloadable += scene_cursor.next().downloadable

Enqueue the scenes for download from the Api

api.download(scenes)

Start the download and automate the extraction

api.start_download(extract=True)