MODIS API Documentation

The MODIS API allows you to search for, analyze, and retrieve MODIS 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/modis/search/
Description

Search for available MODIS 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
product string No MODIS product (e.g., "MOD09GA", "MYD13Q1"), default is "MOD09GA"
Example Request
{
  "geometry_id": "123e4567-e89b-12d3-a456-426614174000",
  "start_date": "2023-01-01",
  "end_date": "2023-01-31",
  "product": "MOD09GA"
}
Response

Returns a list of available MODIS images with date and ID.

Example Response (200 OK)
{
  "results": [
    {
      "id": "MOD09GA.A2023005.h09v05.061.2023007031525",
      "date": "2023-01-05",
      "product": "MOD09GA",
      "platform": "Terra"
    },
    {
      "id": "MOD09GA.A2023015.h09v05.061.2023017031525",
      "date": "2023-01-15",
      "product": "MOD09GA",
      "platform": "Terra"
    }
  ],
  "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/modis/stats/
Description

Get statistics for available MODIS 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
product string No MODIS product (e.g., "MOD09GA", "MYD13Q1"), default is "MOD09GA"
band string No Band name to analyze (e.g., "sur_refl_b01", "sur_refl_b02")
Example Request
{
  "geometry_id": "123e4567-e89b-12d3-a456-426614174000",
  "start_date": "2023-01-01",
  "end_date": "2023-01-31",
  "product": "MOD09GA",
  "band": "sur_refl_b01"
}
Response

Returns statistics for available MODIS images and band information.

Example Response (200 OK)
{
  "total_images": 2,
  "date_range": {
    "start": "2023-01-05",
    "end": "2023-01-15",
    "days": 10
  },
  "platforms": {
    "Terra": 2
  },
  "products": {
    "MOD09GA": 2
  },
  "monthly_distribution": {
    "2023-01": 2
  },
  "band_info": {
    "name": "sur_refl_b01",
    "description": "Surface Reflectance Band 1 (620-670 nm)",
    "unit": "reflectance",
    "scale_factor": 0.0001
  },
  "results": [
    {
      "id": "MOD09GA.A2023005.h09v05.061.2023007031525",
      "date": "2023-01-05",
      "product": "MOD09GA",
      "platform": "Terra",
      "min_value": 0.12,
      "max_value": 0.87,
      "mean_value": 0.65,
      "std_value": 0.15
    },
    {
      "id": "MOD09GA.A2023015.h09v05.061.2023017031525",
      "date": "2023-01-15",
      "product": "MOD09GA",
      "platform": "Terra",
      "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 Indices

Endpoint
POST /api/modis/indices/
Description

Calculate vegetation indices from MODIS imagery for a geometry.

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
item_id string Yes Item ID of the MODIS image
index string Yes Vegetation index to calculate (ndvi, evi, lai)
Example Request
{
  "geometry_id": "123e4567-e89b-12d3-a456-426614174000",
  "item_id": "MOD09GA.A2023005.h09v05.061.2023007031525",
  "index": "ndvi"
}
Response

Returns the calculated index values and statistics.

Example Response (200 OK)
{
  "index": "ndvi",
  "index_name": "Normalized Difference Vegetation Index",
  "formula": "(NIR - Red) / (NIR + Red)",
  "item_id": "MOD09GA.A2023005.h09v05.061.2023007031525",
  "date": "2023-01-05",
  "product": "MOD09GA",
  "platform": "Terra",
  "statistics": {
    "min": -0.2,
    "max": 0.9,
    "mean": 0.65,
    "std": 0.15,
    "percentiles": {
      "25": 0.55,
      "50": 0.67,
      "75": 0.78
    }
  },
  "histogram": {
    "bins": [-0.2, 0.0, 0.2, 0.4, 0.6, 0.8, 1.0],
    "counts": [10, 25, 50, 120, 80, 15]
  }
}
Error Responses
Status Code Description
400 Bad Request - Invalid parameters
401 Unauthorized - Missing API key
403 Forbidden - Invalid API key
404 Not Found - Geometry or image not found
500 Internal Server Error

Get Imagery

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

Get MODIS image for a geometry based on item_id, image type and band or index.

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 MODIS image
image_type string Yes Image format - png, jpeg or tiff
band string No Band name (e.g., "sur_refl_b01") - required if index not provided
index string No Vegetation index (ndvi, evi, lai) - required if band not provided
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

Available MODIS Products

The following MODIS products are available:

Product Platform Description Resolution Temporal Resolution
MOD09GA Terra Surface Reflectance Daily L2G Global 1km and 500m 500m Daily
MYD09GA Aqua Surface Reflectance Daily L2G Global 1km and 500m 500m Daily
MOD13Q1 Terra Vegetation Indices 16-Day L3 Global 250m 250m 16-day
MYD13Q1 Aqua Vegetation Indices 16-Day L3 Global 250m 250m 16-day