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
platform string No Filter by platform (Sentinel-2A, Sentinel-2B, or both)
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)
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

Get Raw Band Data

Endpoint
GET /api/s2/raw-band/{geometry_id}/
Description

Get raw band data for a geometry from a specific Sentinel-2 image.

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
band string Yes Band name (B01, B02, B03, B04, B05, B06, B07, B08, B8A, B09, B11, B12)
format string No Output format (json, tiff), default is json
Headers
Name Required Description
X-API-Key Yes Your API key in UUID format
Response

Returns the raw band data in the requested format (JSON or TIFF).

Example JSON Response (200 OK)
{
  "band": "B04",
  "values": [0.1234, 0.2345, 0.3456, ...],
  "width": 100,
  "height": 100,
  "stats": {
    "min": 0.1234,
    "max": 0.9876,
    "mean": 0.5432,
    "std": 0.1234
  },
  "metadata": {
    "resolution": 10,
    "unit": "reflectance",
    "wavelength": "665nm",
    "description": "Red"
  }
}
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