Sentinel-2 API Documentation

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

Search for available Sentinel-2 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
Example Request
{
  "geometry_id": "123e4567-e89b-12d3-a456-426614174000",
  "start_date": "2023-01-01",
  "end_date": "2023-01-31",
  "cloud_cover": 10
}
Response

Returns a list of available Sentinel-2 images with date, cloud cover, and ID.

Example Response (200 OK)
{
  "results": [
    {
      "id": "S2A_MSIL2A_20230105T123456_N0509_R123_T18TXM_20230105T150000",
      "date": "2023-01-05",
      "cloud_cover": 5.23,
      "platform": "Sentinel-2A"
    },
    {
      "id": "S2B_MSIL2A_20230115T123456_N0509_R123_T18TXM_20230115T150000",
      "date": "2023-01-15",
      "cloud_cover": 8.75,
      "platform": "Sentinel-2B"
    }
  ],
  "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/s2/stats/
Description

Get statistics for available Sentinel-2 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
index string No Vegetation index to analyze (ndvi, evi, lai, ndmi, ndwi)
Example Request
{
  "geometry_id": "123e4567-e89b-12d3-a456-426614174000",
  "start_date": "2023-01-01",
  "end_date": "2023-01-31",
  "cloud_cover": 10,
  "index": "ndvi"
}
Response

Returns statistics for available Sentinel-2 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": {
    "Sentinel-2A": 1,
    "Sentinel-2B": 1
  },
  "monthly_distribution": {
    "2023-01": 2
  },
  "index_info": {
    "name": "NDVI",
    "formula": "(B8 - B4) / (B8 + B4)",
    "description": "Normalized Difference Vegetation Index",
    "value_range": [-1, 1],
    "required_bands": ["B4", "B8"],
    "visualization": {
      "colormap": "RdYlGn",
      "colormap_reverse": false
    }
  },
  "results": [
    {
      "id": "S2A_MSIL2A_20230105T123456_N0509_R123_T18TXM_20230105T150000",
      "date": "2023-01-05",
      "cloud_cover": 5.23,
      "platform": "Sentinel-2A",
      "min_value": 0.12,
      "max_value": 0.87,
      "mean_value": 0.65,
      "std_value": 0.15
    },
    {
      "id": "S2B_MSIL2A_20230115T123456_N0509_R123_T18TXM_20230115T150000",
      "date": "2023-01-15",
      "cloud_cover": 8.75,
      "platform": "Sentinel-2B",
      "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/s2/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 Sentinel-2 image
image_type string Yes Image format - png, jpeg or tiff
index string Yes Vegetation index to calculate (ndvi, evi, lai, ndmi, ndwi)
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 (B8 - B4) / (B8 + B4) Normalized Difference Vegetation Index -1 to 1
evi EVI 2.5 * ((B8 - B4) / (B8 + 6 * B4 - 7.5 * B2 + 1)) Enhanced Vegetation Index -1 to 1
ndmi NDMI (B8 - B11) / (B8 + B11) Normalized Difference Moisture Index -1 to 1
ndwi NDWI (B3 - B8) / (B3 + B8) Normalized Difference Water Index -1 to 1
lai LAI 3.618 * (2.5 * (B8 - B4) / (B8 + 6.0 * B4 - 7.5 * B2 + 1.0)) Leaf Area Index 0 to 7