LandsatExplorer
LandsatExplorer is a pure Julia package for querying and downloading Landsat data from the USGS Earth Explorer ecosystem.
Installation
To install this package, start the Julia REPL and open the package manager by typing ]
. You can then install LandsatExplorer
from the official Julia repository like so:
(@v1.9) pkg> add LandsatExplorer
Authentication
LandsatExplorer
needs access to your USGS Earth Explorer credentials in order to query and download data. These are passed in via the environment variables LANDSAT_EXPLORER_USER
and LANDSAT_EXPLORER_PASS
. You can set them manually each time you run your program by calling authenticate("my_username", "my_password")
, or you can set them once in your startup.jl
configuration.
Quick Start
using LandsatExplorer, GeoDataFrames, Dates
# Only Necessary if `LANDSAT_EXPLORER_USER` and `LANDSAT_EXPLORER_PASS` are not Already Set
authenticate("my_username", "my_password")
# Load Region of Interest From External GeoJSON or Shapefile
roi = GeoDataFrames.read("data/roi.geojson").geometry |> first
# Define Region of Interest as a Bounding Box
bb = BoundingBox((52.1, -114.4), (51.9, -114.1))
# Define Region of Interest Centered on a Point
p = Point(52.0, -114.25)
# Search For Level-2 Landsat 8 Imagery Intersecting our ROI Between August 1 2020 and September 1 2020
dates = (DateTime(2020, 8, 1), DateTime(2020, 9, 1))
results_1 = search("LANDSAT_8", 2, dates=dates, geom=roi)
# Limit Search to Scenes with no More Than 10% Clouds
results_2 = search("LANDSAT_8", 2, dates=dates, geom=roi, clouds=10)
# Retrieve Result with Lowest Cloud Cover
scene = sort(results_2, :CloudCover) |> first
# Download Scene
download_scene(scene.Name; unpack=true)
Index
LandsatExplorer.BoundingBox
LandsatExplorer.Point
LandsatExplorer.authenticate
LandsatExplorer.download_scene
LandsatExplorer.get_entity_id
LandsatExplorer.logout
LandsatExplorer.search
API
LandsatExplorer.BoundingBox
— TypeBoundingBox(ul, lr)
Construct a bounding box defined by the corners ul
and lr
.
All coordinates should be provided in latitude and longitude.
Parameters
ul
: The upper-left corner of the box as aTuple{T,T}
of latitude and longitude.lr
: The lower-right corner of the box as aTuple{T,T}
of latitude and longitude.
Example
bb = BoundingBox((52.1, -114.4), (51.9, -114.1))
LandsatExplorer.Point
— TypePoint(lat, lon)
Construct a point located at the provided latitude and longitude.
Parameters
lat
: The latitude of the point.lon
: The longitude of the point.
Example
p = Point(52.0, -114.25)
LandsatExplorer.authenticate
— Methodauthenticate(username, password)
Authenticate with your USGS Earth Explorer credentials.
Sets the environment variables LANDSAT_EXPLORER_USER
and LANDSAT_EXPLORER_PASS
, which will be used to authenticate future requests.
Parameters
username
: Your USGS Earth Explorer username.password
: Your USGS Earth Explorer password.
Example
authenticate("my_username", "my_password")
LandsatExplorer.download_scene
— Functiondownload_scene(scene, dir=pwd(); log_progress=true, unpack=false)
Download a Landsat scene and save to the given directory.
Parameters
scene
: The display name or entity ID of the scene to be downloaded.dir
: The directory in which to save the downloaded scene.
Keywords
unpack
: If true, unpacks and deletes the downloaded tar file (default = false).log_progress
: If true, logs the download progress at 1-second intervals (default = true).
Returns
The path to the downloaded file(s).
LandsatExplorer.get_entity_id
— Methodget_entity_id(scene)
Lookup the entity ID for the given Landsat scene.
Example
julia> get_entity_id("LC08_L2SP_043024_20200802_20200914_02_T1")
"LC80430242020215LGN00"
LandsatExplorer.logout
— Methodlogout()
Logout of Earth Explorer.
LandsatExplorer.search
— Methodsearch(satellite, level; dates=nothing, clouds=nothing, geom=nothing, max_results=100)
Search for Landsat scenes belonging to the given satellite and processing level.
Parameters
satellite
: One of"LANDSAT_5"
,"LANDSAT_7"
, or "LANDSAT_8"
, or "LANDSAT_9"
.level
: The processing level; either 1 or 2.
Keywords
dates
: The date range for image acquisition. Should be a tuple ofDateTime
objects.clouds
: The maximum allowable cloud cover as a percentage.geom
: A geometry specifying the region of interest. Can be aPoint
,BoundingBox
, or any otherGeoInterface
compatible geometry.max_results
: The maximum number of results to return (default = 100).
Returns
A DataFrame
with the columns :Name
, :AcquisitionDate
, :PublicationDate
, :CloudCover
, and :Id
.
Example
julia> p = Point(52.0, -114.2);
julia> dates = (DateTime(2020, 8, 1), DateTime(2020, 9, 1));
julia> search("LANDSAT_8", 2, dates=dates, geom=p, clouds=21)
3×5 DataFrame
Row │ Name AcquisitionDate Pub ⋯
│ String String Str ⋯
─────┼──────────────────────────────────────────────────────────────
1 │ LC08_L2SP_043024_20200818_202008… 2020-08-18 00:00:00 202 ⋯
2 │ LC08_L2SP_042024_20200811_202009… 2020-08-11 00:00:00 202
3 │ LC08_L2SP_043024_20200802_202009… 2020-08-02 00:00:00 202
3 columns omitted