Working with Landsat Imagery

Learn how to access and analyze Landsat imagery, the longest-running satellite imagery program with data going back to the 1980s.

Prerequisites: Before starting this tutorial, make sure you have:
  • An ObservEarth API key
  • Created at least one Area of Interest (AOI)
If you haven't done these steps yet, check out our Authentication and Areas of Interest tutorials first.

Introduction to Landsat

The Landsat program is the longest-running enterprise for acquisition of satellite imagery of Earth. It has been providing continuous global coverage since 1972.

Key Features:
  • Historical data: Archive dating back to the 1970s
  • Spatial resolution: 15-30m (depending on band and satellite)
  • Temporal resolution: 16-day revisit time
  • Spectral resolution: Multiple bands from visible to thermal infrared
  • Coverage: Global land areas

Searching for Landsat Imagery

Search for Available Imagery

To find Landsat imagery for your area of interest, use the search endpoint:

API Type
POST
Endpoint
https://observearth.com/api/landsat/search/
undefined
Request Parameters
Parameter Type Required Description
geometry_id UUID Yes UUID of your Area of Interest
start_date string Yes Start date in YYYY-MM-DD format
end_date string Yes End date in YYYY-MM-DD format
cloud_cover number No Maximum cloud cover percentage (0-100), default 20
Code Example
import requests
import json

api_key = "your_api_key_here"
url = "https://observearth.com/api/landsat/search/"

payload = {
    "geometry_id": "123e4567-e89b-12d3-a456-426614174000",
    "start_date": "2023-01-01",
    "end_date": "2023-01-31",
    "cloud_cover": 10
}

headers = {
    "X-API-Key": api_key,
    "Content-Type": "application/json"
}

response = requests.post(url, headers=headers, data=json.dumps(payload))
data = response.json()

print(f"Found {len(data['results'])} images")
for image in data['results']:
    print(f"ID: {image['id']}, Date: {image['date']}, Cloud Cover: {image['cloud_cover']}%, Platform: {image['platform']}")
tent-Type": "application/json" } response = requests.post(url, headers=headers, data=json.dumps(payload)) data = response.json() print(f"Found {data['count']} images") for image in data['results']: print(f"ID: {image['id']}, Date: {image['date']}, Cloud Cover: {image['cloud_cover']}%")

Getting Statistics for Landsat Imagery

Calculate Statistics for Imagery

Once you've found available images, you can calculate statistics for vegetation indices over your area of interest.

API Type
POST
Endpoint
https://observearth.com/api/landsat/stats/
Request Parameters
Parameter Type Required Description
geometry_id UUID Yes UUID of your Area of Interest
start_date string Yes Start date in YYYY-MM-DD format
end_date string Yes End date in YYYY-MM-DD format
cloud_cover number No Maximum cloud cover percentage (0-100), default 20
index string Yes Vegetation index to analyze (ndvi, evi, ndmi, ndwi)
Code Example
import requests
import json

api_key = "your_api_key_here"
url = "https://observearth.com/api/landsat/stats/"

payload = {
    "geometry_id": "123e4567-e89b-12d3-a456-426614174000",
    "start_date": "2023-01-01",
    "end_date": "2023-01-31",
    "cloud_cover": 10,
    "index": "ndvi"
}

headers = {
    "X-API-Key": api_key,
    "Content-Type": "application/json"
}

response = requests.post(url, headers=headers, data=json.dumps(payload))
data = response.json()

# Print the statistics
if 'index_info' in data:
    print(f"Index: {data['index_info']['name']}")
    print(f"Description: {data['index_info']['description']}")
    
# Print results
for result in data.get('results', []):
    print(f"Date: {result['date']}, Mean NDVI: {result['mean']:.2f}, Min: {result['min']:.2f}, Max: {result['max']:.2f}")

Retrieving Landsat Imagery

Get Imagery for Visualization

Once you've identified the images you want, you can retrieve them for visualization or analysis.

API Type
GET
Endpoint
https://observearth.com/api/landsat/image/{geometry_id}/
Path Parameters
Parameter Type Description
geometry_id UUID UUID of your Area of Interest
Query Parameters
Parameter Type Required Description
item_id string Yes ID of the Landsat image
image_type string Yes Image format (png, jpeg, or tif)
index string Yes Vegetation index (ndvi, evi, ndmi, ndwi)
Code Example
import requests

api_key = "your_api_key_here"
geometry_id = "123e4567-e89b-12d3-a456-426614174000"
item_id = "LC09_L2SP_042034_20230115_20230116_02_T1"

url = f"https://observearth.com/api/landsat/image/{geometry_id}/"

params = {
    "item_id": item_id,
    "image_type": "png",
    "index": "ndvi"
}

headers = {
    "X-API-Key": api_key
}

response = requests.get(url, headers=headers, params=params)

if response.status_code == 200:
    # Save the image
    with open("landsat_ndvi.png", "wb") as f:
        f.write(response.content)
    print("Image saved as landsat_ndvi.png")
else:
    print(f"Error: {response.status_code}")
    print(response.text)

Get Raw Band Data

You can also retrieve raw Landsat band data without any processing or index calculation.

API Type
GET
Endpoint
https://observearth.com/api/landsat/raw/{geometry_id}/
Path Parameters
Parameter Type Description
geometry_id UUID UUID of your Area of Interest
Query Parameters
Parameter Type Required Description
item_id string Yes ID of the Landsat image
band string Yes Band to download (blue, green, red, nir08, swir16, swir22)
Code Example
import requests

api_key = "your_api_key_here"
geometry_id = "123e4567-e89b-12d3-a456-426614174000"
item_id = "LC09_L2SP_042034_20230115_20230116_02_T1"

url = f"https://observearth.com/api/landsat/raw/{geometry_id}/"

params = {
    "item_id": item_id,
    "band": "nir08"
}

headers = {
    "X-API-Key": api_key
}

response = requests.get(url, headers=headers, params=params)

if response.status_code == 200:
    # Save the raw band data
    with open("landsat_nir_band.tif", "wb") as f:
        f.write(response.content)
    print("Raw band data saved successfully")
else:
    print(f"Error: {response.status_code}")
    print(response.text)

Common Vegetation Indices

Landsat imagery can be used to calculate various vegetation indices. Here are the most common ones:

Index Name Description Value Range
ndvi Normalized Difference Vegetation Index Measures vegetation health and density. Higher values indicate denser vegetation. 0 to 1
evi Enhanced Vegetation Index Improved vegetation index that corrects for atmospheric conditions and soil background. -1 to 1
ndmi Normalized Difference Moisture Index Measures moisture content in vegetation. Higher values indicate more water content. -1 to 1
ndwi Normalized Difference Water Index Highlights open water features. Positive values indicate water bodies. -1 to 1

Next Steps

Now that you understand how to work with Landsat imagery, you can: