GitHub

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

API

LandsatExplorer.BoundingBox — Type
BoundingBox(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 a Tuple{T,T} of latitude and longitude.
  • lr: The lower-right corner of the box as a Tuple{T,T} of latitude and longitude.

Example

bb = BoundingBox((52.1, -114.4), (51.9, -114.1))
source
LandsatExplorer.Point — Type
Point(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)
source
LandsatExplorer.authenticate — Method
authenticate(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")
source
LandsatExplorer.download_scene — Function
download_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).

source
LandsatExplorer.get_entity_id — Method
get_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"
source
LandsatExplorer.search — Method
search(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 of DateTime objects.
  • clouds: The maximum allowable cloud cover as a percentage.
  • geom: A geometry specifying the region of interest. Can be a Point, BoundingBox, or any other GeoInterface 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
source