Leaf’s crop monitoring API delivers satellite imagery from Sentinel-2 and Planet, processed and clipped to your field boundaries. You get NDVI, NDRE, RGB compositions, and raw multiband GeoTIFFs. This tutorial walks through creating a satellite field and retrieving images.
Before you start
- A Leaf account with a valid API token.
- A field boundary (as a GeoJSON MultiPolygon). You can use coordinates from any source.
Leaf users and configurations are not required for satellite imagery. You only need authentication and a field geometry.
Step 1: Get your Leaf token
curl -X POST "https://api.withleaf.io/api/authenticate" \
-H "Content-Type: application/json" \
-d '{
"username": "your-email@example.com",
"password": "your-password"
}'
Step 2: Create a satellite field
POST a field boundary to the crop monitoring endpoint. The geometry must be a MultiPolygon.
curl -X POST "https://api.withleaf.io/services/satellite/api/fields" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"externalId": "my-field-001",
"providers": [
{
"name": "sentinel",
"startDate": "2025-01-01"
}
],
"geometry": {
"type": "MultiPolygon",
"coordinates": [[[
[-93.48821, 41.77137],
[-93.48821, 41.77088],
[-93.48738, 41.77088],
[-93.48738, 41.77137],
[-93.48821, 41.77137]
]]]
}
}'
- The
name field in providers must be exactly "sentinel" or "planet". Planet requires activation from Leaf support.
- The
startDate tells Leaf how far back to fetch historical images.
- You can request multiple providers and asset types for the same field.
After creation, Leaf begins fetching and processing images from the start date forward.
Step 3: Retrieve images
Query the images available for your satellite field:
curl "https://api.withleaf.io/services/satellite/api/fields/SATELLITE_FIELD_ID/processes" \
-H "Authorization: Bearer YOUR_TOKEN"
- Multiband GeoTIFF (the original satellite data)
- RGB composition (GeoTIFF and PNG)
- NDVI (GeoTIFF and PNG)
- NDRE (GeoTIFF and PNG)
The download URLs require authentication. Pass your Leaf token in the Authorization header when downloading.
You can filter results by date range and cloud coverage:
?startDate=2025-06-01&endDate=2025-09-01&maxCloudCoverage=50
If cloud coverage is 50% or less, the image is included but cloud shadows may still be visible. There’s no way to filter out the shadow itself.
Step 4: Set up alerts
Instead of polling for new images, set up an alert to get notified when new satellite imagery is processed:
curl -X POST "https://api.withleaf.io/services/alerts/api/alerts" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"type": "newSatelliteImage",
"url": "https://your-app.com/webhook/satellite"
}'
What you built
You created a satellite field with Leaf’s crop monitoring API and retrieved NDVI, NDRE, and RGB imagery. Leaf continuously monitors the field and processes new images as they become available from Sentinel-2 (roughly every 5 days) or Planet (daily with activation).
For the full endpoint reference, see the satellite API reference. To use satellite data in ArcGIS, see the ArcGIS integration tutorial. 
