Crop Monitoring Endpoints

PLANET

If you wish to test our Planet Imagery service, you will be required to use THIS GEOMETRY for your testing purposes. If you need to use a different geometry for testing purposes, you will be billed for this usage. Please contact our team on sales@withleaf.io to discuss your options should you require different testing geometry.

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:

Description	Endpoints
Get all satellite fields	GET /fields
Get a satellite field	GET /fields/{id}
Get images of satellite field	GET /fields/{id}/processes
Get an image of satellite field	GET /fields/{id}/processes/{id}
Create a satellite field	POST /fields
Delete a satellite field	DELETE /fields/{id}
Get subscription for Planet	GET /fields/{id}/subscription
Reprocess satelite images	POST /fields/{id}/process/{id}/reprocess

Endpoints

Get all satellite fields

 GET /fields

Returns paged results for all satellite fields registered.

• externalId: external ID used in the field's registration
• geometry: a valid MultiPolygon GeoJSON object with the geometry of the field

• cURL
• Python
• JavaScript

curl -X GET \

-H 'Authorization: Bearer YOUR_TOKEN' \

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

Response

It returns a list of JSON objects

[

{

"externalId": "your field id",

"geometry": {

"type": "MultiPolygon",

"coordinates": [...]

}

"providers": [

"sentinel", "planet"

]

},

]

Get a satellite field

 GET /fields/{id}

Fetches a field entry based on its external id.

• id: external ID used in the field's registration
• geometry: a valid MultiPolygon GeoJSON object with the geometry of the field

• cURL
• Python
• JavaScript

curl -X GET \

-H 'Authorization: Bearer YOUR_TOKEN' \

'https://api.withleaf.io/services/satellite/api/fields/{id}'

Response

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": [...]

},

"providers": [

"sentinel", "planet"

]

}

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
• Colorized NDVI as tiff and as png
• Raw NDVI as tiff
• All bands as tiff.

Check the comparison page to identify the resolution and bands available for each provider.

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

Parameter	Type	Description	Default
startDate	ISO 8601 datetime format	retrieve images taken after this day	-
endDate	ISO 8601 datetime format	retrieve images taken until this day	-
startProcessedTimestamp	ISO 8601 datetime format	retrieve images processed by Leaf after this day	-
endProcessedTimestamp	ISO 8601 datetime format	retrieve images processed by Leaf until this day	-
maxClouds	double between 0.0 and 100.0	filter processes with clouds less than or equal to this percentage	100
minCoverage	double between 0.0 and 100.0	filter processes with coverage greater than or equal to this percentage	0.0
status	string "SUCCESS", "FAILED" or "STARTED"	retrieve images with selected status	SUCCESS
page	integer	page being fetched	0
size	integer	how many processes (sets of all images) to return per page	20
provider	array of string	sentinel or/and planet	If none is defined, it will created with sentinel only

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
• Python
• JavaScript

curl -X GET \

--header 'Authorization: Bearer YOUR_TOKEN' \

'https://api.withleaf.io/services/satellite/api/fields/{id}/processes?startDate=2020-06-03&endDate=2020-06-10'

Response

[

{

"id": 0,

"date": "2020-06-03T19:03:57.882Z",

"clouds": 0,

"provider": "sentinel",

"bucketName": "sentinel-s2-l2a",

"bucketKey": "tiles/10/S/FH/2020/6/3/0",

"bucketRegion": "eu-central-1",

"status": "SUCCESS",

"coverage": 100,

"images": [

{

"url": "url.to.your.image.tif",

"type": "tif",

"resolution": 20

},

# etc...

],

"processedTimestamp": "2020-06-03T19:03:58.881731Z"

},

# etc...

]

• date: the date of the satellite image
• clouds: cloud coverage percentage of the field, from 0 to 100
• provider: the satellite provider (sentinel or planet) from where this process was created.
• bucketName: name of satellite image bucket where the original tile is. Usually sentinel-s2-l2a or leaf-planet-images-prd
• bucketRegion: AWS region of original image's bucket. Usually eu-central-1
• bucketKey: base path of original satellite image
• status: status of the process. It will be either SUCCESS or FAILURE
• coverage: data coverage percentage of the field, from 0 to 100
• images: each image in this list will have the following data:
  • url: URL of the image
  • type: the type of the image. One of tif, ndvi, png and tif_colorized
  • resolution: resolution, in meters, of the image. See table below
• processedTimestamp: the timestamp of when the process was processed

Get an image of satellite field

 GET /fields/{id}/processes/{id}

Returns a single process for the field.

• cURL
• Python
• JavaScript

curl -X GET \

--header 'Authorization: Bearer YOUR_TOKEN' \

'https://api.withleaf.io/services/satellite/api/fields/{id}/processes/{id}'

Response

{

"id": 0,

"date": "2020-06-03T19:03:57.882Z",

"clouds": 0,

"provider": "sentinel",

"bucketName": "sentinel-s2-l2a",

"bucketKey": "tiles/10/S/FH/2020/6/3/0",

"bucketRegion": "eu-central-1",

"status": "SUCCESS",

"coverage": 100,

"images": [

{

"url": "url.to.your.image.tif",

"type": "tif",

"resolution": 20

},

# etc...

],

"processedTimestamp": "2020-06-03T19:03:58.881731Z"

}

Create a satellite field

 POST /fields

Creates a new field.

It will be continuously monitored forever, and new images will arrive based on the provider selected, because each one of them has a different temporal resolution (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",

"providers": [

"planet"

],

"assetTypes": [

"ortho_analytic_8b_sr",

"ortho_analytic_8b",

"ortho_analytic_8b_xml",

"ortho_udm2"

],

"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.
• providers: Specify the satellite imagery source, if none is specified, Sentinel images will be retrived by default.
• assetTypes: If the providers property contains planet you can select which assetType will be retrived, which can be more than one. Default value is analytic_sr.

• cURL
• Python
• JavaScript

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).

Sample geometry

If you are looking for a geometry for testing purposes you can use this one.

{

"geometry": {

"type": "MultiPolygon",

"coordinates": [

[[[ -48.95275447, -22.49608],

[ -48.95379286, -22.49675703],

[ -48.9591836, -22.50310243],

[ -48.96225525, -22.5067235],

[ -48.94852019, -22.50648371],

[ -48.94780839, -22.49693998],

[ -48.95275447, -22.49608]

]]]

}

}

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
• Python
• JavaScript

curl -X DELETE \

-H 'Authorization: Bearer YOUR_TOKEN' \

'https://api.withleaf.io/services/satellite/api/fields/{id}'

Get subscription for Planet

  GET /fields/{id}/subscription

Get the subscription from Planet. It returns the assetTypes, itemTypes and startDate for a field.

• cURL
• Python
• JavaScript

curl -X GET \

--header 'Authorization: Bearer YOUR_TOKEN' \

'https://api.withleaf.io/services/satellite/api/fields/{id}/subscription'

Response

{

"planetAssetTypes": [

"ortho_analytic_8b_sr",

"ortho_analytic_8b",

"ortho_analytic_8b_xml",

"ortho_udm2"

],

"planetItemTypes": [

"PSScene"

],

"startDate": "2023-04-09T00:00:00Z"

}

Reprocess satellite images

 POST /fields/{id}/process/{id}/reprocess

Allows reprocessing the satellite images based on a processId.

• cURL
• Python
• JavaScript

curl -X POST \

-H 'Authorization: Bearer YOUR_TOKEN' \

'https://api.withleaf.io/services/operations/api/fields/{id}/process/{id}/reprocess'

Alerts

With Alerts you can be notified when something happens or changes instead of needing to repeatedly query for changes. Leaf Alerts support events that happen within Leaf and events that happen within supported 3rd party software.

List of Crop Monitoring Events

Leaf Crop Monitoring Service can Alert you on these events: list of Crop Monitoring Events