Skip to content

Working with GEDI Data

GEDI is a spaceborne lidar sensor onboard the International Space Station. It provides global measurements of forest structure using a large-footprint waveform lidar.

GEDI conceptual diagram

These data are cool and useful, but really hard to work with. So we've built some tools to work with it.

from lazer import gedi

Data discovery

GEDI data is hosted via NASA's Earthdata platform. Create a free Earthdata account here.

You'll need your account information to search for and download data.

session = gedi.EarthdataSession(username, password)

If you don't pass the user/password, it will prompt you to securely enter each. Alternatively, you can set EARTHDATA_USER and EARTHDATA_PASS environment variables to handle authentication.

Searching for data

The Earthdata API allows you to query GEDI products based on spatial bounding box extents. These should be lat/lon values, in [xmin, ymin, xmax, ymax] order.

Datasets are organized under product groups, which you'll use in your search:

  • 'GEDI01_B' - L1B - Geolcated waveforms
  • 'GEDI02_A' - L2A - Elevation, Canopy Height, Relative Height metrics
  • 'GEDI02_B' - L2B - Canopy Cover, Leaf Area Index, Vertical Profile
# random 1x1 degree cell in California
bounds = [-120, 38, -119, 39]

# L2A product
product = 'GEDI02_A'

file_list = gedi.search_bounds(session, product, bounds)
file_list[:3]

Which returns:

['https://e4ftl01.cr.usgs.gov/GEDI/GEDI02_A.001/2020.08.11/GEDI02_A_2020224234603_O09435_T00710_02_001_01.h5',
 'https://e4ftl01.cr.usgs.gov/GEDI/GEDI02_A.001/2020.08.04/GEDI02_A_2020217025308_O09313_T03556_02_001_01.h5',
 'https://e4ftl01.cr.usgs.gov/GEDI/GEDI02_A.001/2020.07.27/GEDI02_A_2020209060051_O09191_T02133_02_001_01.h5']

Filtering by date

There's no easy way to filter API requests by date. So we can handle this on the user side.

first_year = gedi.filter_urls_by_date(file_list, '2019-1-1', '2019-12-31')
first_year.sort()
first_year[:3]

['https://e4ftl01.cr.usgs.gov/GEDI/GEDI02_A.001/2019.04.21/GEDI02_A_2019111145043_O02015_T00201_02_001_01.h5',
 'https://e4ftl01.cr.usgs.gov/GEDI/GEDI02_A.001/2019.04.28/GEDI02_A_2019118120814_O02122_T01471_02_001_01.h5',
 'https://e4ftl01.cr.usgs.gov/GEDI/GEDI02_A.001/2019.05.01/GEDI02_A_2019121172232_O02172_T03449_02_001_01.h5']

Downloading data

You can download a list of URLs by passing your session and an output directory for writing each file.

output_directory = '/external/laserdots'
gedi.download_urls(session, first_year, output_directory)

GEDI02_A_2019111145043_O02015_T00201_02_001_01.h5:   0%|          | 5/1000 [00:04<15:10,  1.09it/s]

Warnings and caveats

Unfortunately, it appears that the spatial filtering does not clip the data to the extent of the bounds you pass. I think the query just finds any ISS overpass that intersects with the extent of the area you want to download.

This means that each file download contains the full set of global measurments from that date. You'll have to download the full file - which is usually around 6gb - then use other tools to spatially subset the data.

We'll build some of those tools next.

Back to top