Endpoints

All HTTP methods should be prepended by this service's endpoint:

https://api.withleaf.io/services/satellite/api

This service has the following endpoints available:

DescriptionEndpoints
Get all satellite fieldsGET /fields
Get a satellite fieldGET /fields/{id}
Get images of satellite fieldGET /fields/{id}/processes
Create a satellite fieldPOST /fields
Delete a satellite fieldDELETE /fields/{id}

Endpoints

Get all satellite fields

 GET /fields

Returns paged results for all fields registered.

It returns a list of JSON objects like so:

[
{
"externalId": "your field id",
"geometry": {
"type": "MultiPolygon",
"coordinates": [...]
}
},
# etc...
]
  • externalId: external ID used in the field's registration
  • geometry: a valid MultiPolygon GeoJSON object with the geometry of the field
curl -X GET \
-H 'Authorization: Bearer YOUR_TOKEN' \
'https://api.withleaf.io/services/satellite/api/fields'

Get a satellite field

 GET /fields/{id}

Fetches a field entry based on its external id.

It returns a single JSON object with the following entries (like each item from GET /fields results):

{
"externalId": "your field id",
"geometry": {
"type": "MultiPolygon",
"coordinates": [...]
}
}
  • id: external ID used in the field's registration
  • geometry: a valid MultiPolygon GeoJSON object with the geometry of the field
curl -X GET \
-H 'Authorization: Bearer YOUR_TOKEN' \
'https://api.withleaf.io/services/satellite/api/fields/YOUR_ID'

Get images of satellite field

 GET /fields/{id}/processes

Returns images for a given field id.

We return the following images, (tifs are EPSG:4326, pngs are EPSG:3857):

  • RGB as tiff and as png (10m resolution)
  • Colorized NDVI as tiff and as png (10m resolution)
  • Raw NDVI as tiff (10m resolution)
  • all 12 Sentinel-2 bands as tiff.

It is possible to filter the results by a number of different parameters:

ParameterTypeDescriptionDefault
startDateISO 8601 datetime formatretrieve images taken after this day-
endDateISO 8601 datetime formatretrieve images taken until this day-
startProcessedTimestampISO 8601 datetime formatretrieve images processed by Leaf after this day-
endProcessedTimestampISO 8601 datetime formatretrieve images processed by Leaf until this day-
maxCloudsdouble between 0.0 and 100.0filter processes with less than or equal to this percentage100
statusstring "SUCCESS", "FAILED" or "STARTED"retrieve images with selected statusSUCCESS
pageintegerpage being fetched0
sizeintegerhow many processes (sets of all images) to return per page20
Important

Default page is page 0 and default size is 20. So, to see more images, you can either increase the size or the page number.

curl -X GET \
--header 'Authorization: Bearer YOUR_TOKEN' \
'https://api.withleaf.io/services/satellite/api/fields/YOUR_ID/processes?startDate=2020-06-03&endDate=2020-06-10'

Create a satellite field

 POST /fields

Creates a new field

It will be continuously monitored forever, and new images will arrive every ~5 days (time it takes for the satellite to go over the same field when orbiting the Earth). If you don't need the field anymore, you can delete the field.

Note

By default, Leaf will return images for your field from the last 30 days (from the moment you create the field).

You can change that by including a "startDate" or a "daysBefore" to the body

There are two ways you can do that:

  1. set a startDate (ISO, "yyyy-mm-dd") meaning Leaf will return all images for your field since this date.
  2. set how many daysBefore (an integer greater than or equal to 0) you want to get images from.

Note that they are both optional, but you can not specify both.

Now let's see the Payload

Payload

The payload of this object should be like the following:

{
"externalId": "your field id",
"startDate": "2019-01-01"
"geometry": {
"type": "MultiPolygon",
"coordinates": [...]
}
}
  • externalId: external ID used in the field's registration
  • geometry: a valid MultiPolygon GeoJSON object with the geometry of the field
curl -X POST \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer YOUR_TOKEN' \
-d '{ your payload }' \
'https://api.withleaf.io/services/satellite/api/fields'
field size limit
  • the field cannot be larger than 50k hectares (123k acres) and
  • cannot have a perimeter bigger than 300km (180 miles).

Delete a satellite field

 DELETE /fields/{id}

Deletes the field from our database.

warning

Note that the field deletion is irreversible and all images will be lost.

(But you can always create a new field and get images from the past, as far as you want).

curl -X DELETE \
-H 'Authorization: Bearer YOUR_TOKEN' \
'https://api.withleaf.io/services/satellite/api/fields/YOUR_ID'