Landsat API Documentation

The Landsat API allows you to search for, analyze, and retrieve Landsat satellite imagery for your geometries.

Authentication: All API endpoints require an API key to be passed in the X-API-Key header.

Search for Imagery

Endpoint
POST /api/landsat/search/
Description

Search for available Landsat imagery for a geometry within a date range and cloud cover threshold.

Headers
Name Required Description
X-API-Key Yes Your API key in UUID format
Content-Type Yes application/json
Request Body
Parameter Type Required Description
geometry_id UUID Yes UUID of the geometry to search for
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
collection string No Landsat collection (e.g., "landsat-8", "landsat-9"), default is all
Example Request
{
  "geometry_id": "123e4567-e89b-12d3-a456-426614174000",
  "start_date": "2023-01-01",
  "end_date": "2023-01-31",
  "cloud_cover": 10,
  "collection": "landsat-9"
}
Response

Returns a list of available Landsat images with date, cloud cover, and ID.

Example Response (200 OK)
{
  "results": [
    {
      "id": "LC09_L2SP_123045_20230105_20230112_02_T1",
      "date": "2023-01-05",
      "cloud_cover": 5.23,
      "platform": "LANDSAT_9",
      "collection": "landsat-9"
    },
    {
      "id": "LC08_L2SP_123045_20230115_20230122_02_T1",
      "date": "2023-01-15",
      "cloud_cover": 8.75,
      "platform": "LANDSAT_8",
      "collection": "landsat-8"
    }
  ],
  "count": 2
}
Error Responses
Status Code Description
400 Bad Request - Invalid parameters
401 Unauthorized - Missing API key
403 Forbidden - Invalid API key
404 Not Found - Geometry not found
500 Internal Server Error

Get Statistics

Endpoint
POST /api/landsat/stats/
Description

Get statistics for available Landsat imagery for a geometry within a date range.

Headers
Name Required Description
X-API-Key Yes Your API key in UUID format
Content-Type Yes application/json
Request Body
Parameter Type Required Description
geometry_id UUID Yes UUID of the geometry to search for
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
collection string No Landsat collection (e.g., "landsat-8", "landsat-9"), default is all
index string No Vegetation index to analyze (ndvi, evi, ndmi, ndwi)
Example Request
{
  "geometry_id": "123e4567-e89b-12d3-a456-426614174000",
  "start_date": "2023-01-01",
  "end_date": "2023-01-31",
  "cloud_cover": 10,
  "collection": "landsat-9",
  "index": "ndvi"
}
Response

Returns statistics for available Landsat images and index information.

Example Response (200 OK)
{
  "total_images": 2,
  "date_range": {
    "start": "2023-01-05",
    "end": "2023-01-15",
    "days": 10
  },
  "cloud_cover": {
    "min": 5.23,
    "max": 8.75,
    "avg": 6.99
  },
  "platforms": {
    "LANDSAT_8": 1,
    "LANDSAT_9": 1
  },
  "monthly_distribution": {
    "2023-01": 2
  },
  "index_info": {
    "name": "NDVI",
    "formula": "(NIR - Red) / (NIR + Red)",
    "description": "Normalized Difference Vegetation Index",
    "value_range": [-1, 1],
    "required_bands": ["Red", "NIR"],
    "visualization": {
      "colormap": "RdYlGn",
      "colormap_reverse": false
    }
  },
  "results": [
    {
      "id": "LC09_L2SP_123045_20230105_20230112_02_T1",
      "date": "2023-01-05",
      "cloud_cover": 5.23,
      "platform": "LANDSAT_9",
      "collection": "landsat-9",
      "min_value": 0.12,
      "max_value": 0.87,
      "mean_value": 0.65,
      "std_value": 0.15
    },
    {
      "id": "LC08_L2SP_123045_20230115_20230122_02_T1",
      "date": "2023-01-15",
      "cloud_cover": 8.75,
      "platform": "LANDSAT_8",
      "collection": "landsat-8",
      "min_value": 0.10,
      "max_value": 0.85,
      "mean_value": 0.63,
      "std_value": 0.16
    }
  ]
}
Error Responses
Status Code Description
400 Bad Request - Invalid parameters
401 Unauthorized - Missing API key
403 Forbidden - Invalid API key
404 Not Found - Geometry not found
500 Internal Server Error

Get Imagery

Endpoint
GET /api/landsat/image/{geometry_id}/
Description

Get satellite image for a geometry based on item_id, image type and indices.

Path Parameters
Parameter Type Required Description
geometry_id UUID Yes UUID of the geometry
Query Parameters
Parameter Type Required Description
item_id string Yes Item ID of the Landsat image
image_type string Yes Image format - png, jpeg or tiff
index string Yes Vegetation index to calculate (ndvi, evi, ndmi, ndwi)
colormap string No Color palette to use for visualization
min_value number No Minimum value for color scaling
max_value number No Maximum value for color scaling
Headers
Name Required Description
X-API-Key Yes Your API key in UUID format
Response

Returns the image file in the requested format (PNG, JPEG, or TIFF).

Error Responses
Status Code Description
400 Bad Request - Invalid parameters
401 Unauthorized - Missing API key
403 Forbidden - Invalid API key
404 Not Found - Geometry not found
500 Internal Server Error

Vegetation Indices

The following vegetation indices are available for analysis:

Index Name Formula Description Value Range
ndvi NDVI (NIR - Red) / (NIR + Red) Normalized Difference Vegetation Index -1 to 1
evi EVI 2.5 * ((NIR - Red) / (NIR + 6 * Red - 7.5 * Blue + 1)) Enhanced Vegetation Index -1 to 1
ndmi NDMI (NIR - SWIR1) / (NIR + SWIR1) Normalized Difference Moisture Index -1 to 1
ndwi NDWI (Green - NIR) / (Green + NIR) Normalized Difference Water Index -1 to 1