Field Operations Endpoints

About

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

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

This service has the following endpoints available:

DescriptionEndpoints
Get all operationsGET /operations
Get an operationGET /operations/{id}
Get the operation's summaryGET /operations/{id}/summary
Get the operation's standardGeojsonGET /operations/{id}/standardGeojson
Get the operation's filteredGeojsonGET /operations/{id}/filteredGeojson
Get operation's imagesGET /operations/{id}/images
Get operation's images V2GET /operations/{id}/imagesV2
Get operation's geotiff imagesGET /operations/{id}/geotiffImages
Get the operation's unitsGET /operations/{id}/units
Get the operation's machinesGET /operations/{id}/machines
Get the operation's implementsGET /operations/{id}/implements
Get the operation's operatorsGET /operations/{id}/operators
Get the operation's sessionsGET /operations/{id}/sessions
Crop operation by fieldPOST /operations/cropOperationByField
Reprocess an operationPOST /operations/{id}/reprocess
Get files from an operationGET /operations/{id}/files

For easily testing these endpoints, we recommend using our Postman collection.

Get all operations

 GET /operations

Gets a paged list of operations that belong to the current logged in user. It is possible to filter the results by passing some query parameters. They are listed below.

Parameter (to filter by)Values
leafUserIduuid of one of your users
providerCNHI, JohnDeere, Trimble, ClimateFieldView, AgLeader, Stara or Leaf
startTimeISO 8601 date. Returns operations from the startTime onward
updatedTimeISO 8601 date. Returns operations from the updatedTime onward
endTimeISO 8601 date. Returns operations until the endTime
operationTypeapplied, planted, harvested or tillage
fieldIdthe field where the operation happened

You can also pass some parameters used exclusively for paging through results. They are:

  • page, an integer specifying the page being fetched (default is 0)
  • size, an integer specifying the size of the page (max is 100)
  • sort, the sorting order of the results; can be multi-value, where the first value to be passed will have preference in ordering over the next ones; you can also specify the order as asc or desc with asc being the default. Example: id, desc
    • Valid values for sorting are: id, leafUserId, startTime, endTime, type and updatedTime.
the default value for page size is 20

If the parameters page and size are not set, the endpoint will return 20 results.

Request examples

curl -X GET \
-H 'Authorization: Bearer YOUR_TOKEN' \
'https://api.withleaf.io/services/operations/api/operations'

Response

[
{
"id": "5c8fdb34-4dc4-4b96-bfd5-53e6206ce971",
"apiOwnerUsername": "test",
"leafUserId": "7494c90e-28b8-4bb2-9ede-95c1cc894349",
"startTime": "2015-04-18T19:31:27Z",
"endTime": "2015-04-18T19:58:50Z",
"updatedTime": "2021-08-24T16:00:15.062Z",
"type": "planted",
"files": [
"a10b85c2-ac2e-4b0f-8e65-74edbd2ca53e",
"759e1b62-dc69-4332-b618-6449a37470fa"
],
"fields": [
{
"id": "0071484f-4a75-4190-9fd0-f5995d241c2c"
}
],
"providers": [
"providerName"
]
},
....
]

Get an operation

 GET /operations/{id}

Gets a single operation by its id.

Request examples

curl -X GET \
-H 'Authorization: Bearer YOUR_TOKEN' \
'https://api.withleaf.io/services/operations/api/operations/{id}'

Response

{
"id": "5c8fdb34-4dc4-4b96-bfd5-53e6206ce971",
"apiOwnerUsername": "test",
"leafUserId": "7494c90e-28b8-4bb2-9ede-95c1cc894349",
"startTime": "2015-04-18T19:31:27Z",
"endTime": "2015-04-18T19:58:50Z",
"updatedTime": "2021-08-24T16:00:15.062Z",
"type": "planted",
"files": [
"a10b85c2-ac2e-4b0f-8e65-74edbd2ca53e",
"759e1b62-dc69-4332-b618-6449a37470fa"
],
"fields": [
{
"id": "0071484f-4a75-4190-9fd0-f5995d241c2c"
}
],
"providers": [
"providerName"
]
}

Get the operation's summary

 GET /operations/{id}/summary

Gets the summary, if available, for the operation id.

Request examples

curl -X GET \
-H 'Authorization: Bearer YOUR_TOKEN' \
'https://api.withleaf.io/services/operations/api/operations/{id}/summary'

Response

Here's a link with sample responses for "planted", "applied", "harvested" and "tillage" operations.

Get the operation's standardGeojson

 GET /operations/{id}/standardGeojson

Get the standardGeojson file URL relative to the operation.

Request examples

curl -X GET \
-H 'Authorization: Bearer YOUR_TOKEN' \
'https://api.withleaf.io/services/operations/api/operations/{id}/standardGeojson'

Response

{
"standardGeojson": "URL",
"downloadStandardGeojson": "URL"
}

Get the operation's filteredGeojson

 GET /operations/{id}/filteredGeojson

Get the filteredGeojson file URL relative to the operation.

tip

To use this option, the operationsFilteredGeojson configuration must be enabled.

Request examples

curl -X GET \
-H 'Authorization: Bearer YOUR_TOKEN' \
'https://api.withleaf.io/services/operations/api/operations/{id}/filteredGeojson'

Response

{
"filteredGeojson": "URL",
"downloadFilteredGeojson": "URL"
}

Get operation's images

 GET /operations/{id}/images

Gets a list of PNG images generated from the operation's properties.

Request examples

curl -X GET \
-H 'Authorization: Bearer YOUR_TOKEN' \
'https://api.withleaf.io/services/operations/api/operations/{id}/images'

Response

[
{
"property": "elevation",
"ramp": {
"0%": [200, 0, 0],
"35%": [255, 40, 0],
"45%": [255, 150, 0],
"55%": [255, 240, 0],
"65%": [ 0, 230, 0],
"75%": [ 0, 190, 0],
"100%": [ 0, 130, 0],
"nv": [ 0, 0, 0, 0]
},
"url": "URL",
"downloadUrl": "URL"
},
....
]

The property refers to the property extracted from operations' data to generate the image. In the example above, the image would represent the elevation.

The ramp is the color ramp used to generate the image. The percentages correspond to the minimum (0%) and maximum (100%) values in the image. The listed values correspond to RGB values used. The nv refers to no value. It is used internally to make the image transparent on places without data. Currently, this ramp is the same in all images processed.

We also generate an auxiliary xml with geographic information to handle this image on GIS environments. You just need to append the ".aux.xml" string to the png url.

Get operation's images V2

 GET /operations/{id}/imagesV2

Gets a list of PNG images generated from the operation's properties with improvements in the generation process. These images are based on the filteredGeojson.

Request examples

curl -X GET \
-H 'Authorization: Bearer YOUR_TOKEN' \
'https://api.withleaf.io/services/operations/api/operations/{id}/imagesV2'

Response

[
{
"property": "string",
"legend": {
"ranges": [
{
"colorCode": "#C80000",
"max": 20,
"min": 0
},
{
"colorCode": "#FF2800",
"max": 50,
"min": 20
},
{
"colorCode": "#FF9600",
"max": 100,
"min": 50
},
{
"colorCode": "#FFF000",
"max": 250,
"min": 100
},
{
"colorCode": "#00E600",
"max": 340,
"min": 250
},
{
"colorCode": "#00BE00",
"max": 480,
"min": 340
},
{
"colorCode": "#008200",
"max": 570,
"min": 480
}
]
},
"extent": {
"xmin": 0,
"xmax": 0,
"ymin": 0,
"ymax": 0
},
"url": "URL",
"downloadUrl": "URL"
}
]

The property refers to the property extracted from operations' data to generate the image.

The legend represents the values distributed in 7 classes, classified by the quantile and symbolized by the standard color ramp.

The extent is the coordinates of the image, mainly used for plotting images in map applications.

More information here.

Get operation's geotiff images

 GET /operations/{id}/geotiffImages

Gets a list of TIFF images generated from the operation's properties with improvements in the generation process. These images are based on the filteredGeojson.

Request examples

curl -X GET \
-H 'Authorization: Bearer YOUR_TOKEN' \
'https://api.withleaf.io/services/operations/api/operations/{id}/geotiffImages'

Response

[
{
"property": "distance",
"url": "URL",
"downloadUrl": "URL"
},
{
"property": "wetVolumePerArea",
"url": "URL",
"downloadUrl": "URL"
},
{
"property": "dryMassPerArea",
"url": "URL",
"downloadUrl": "URL"
},
{
"property": "dryVolumePerArea",
"url": "URL",
"downloadUrl": "URL"
}
]

Get the operation's units

 GET /operations/{id}/units

Gets the operations's properties and their units.

Request examples

curl -X GET \
-H 'Authorization: Bearer YOUR_TOKEN' \
'https://api.withleaf.io/services/operations/api/operations/{id}/units'

Response

Here's a link with sample responses for "planted", "applied", "harvested" and "tillage" operations.

These properties vary depending on the operationType, but you can expect the same, standardized keys, across different providers.

Units usually don't change for the same Leaf User, since the providers units configuration is based on their location. But keep in mind that it's best to always take the units into consideration, just to be sure.

Get the operation's machines

 GET /operations/{id}/machines

Gets the machines used in the given operation. The IDs returned can be used to fetch more information about the machine in the Get a machine endpoint.

Request examples

curl -X GET \
-H 'Authorization: Bearer YOUR_TOKEN' \
'https://api.withleaf.io/services/operations/api/operations/{id}/machines'

Response

{
"machines": [
"77385069-7666-4867-8d72-72c2584e2b4e",
"baad537c-69e3-4d86-a99b-92d5b716b574"
]
}

Get the operation's implements

 GET /operations/{id}/implements

Gets the implements used in the given operation. The IDs returned can be used to fetch more information about the implement in the Get an implement endpoint.

Request examples

curl -X GET \
-H 'Authorization: Bearer YOUR_TOKEN' \
'https://api.withleaf.io/services/operations/api/operations/{id}/implements'

Response

{
"implements": [
"1190bc0d-e94c-407a-8aba-ac4c6a1cd29b"
]
}

Get the operation's operators

 GET /operations/{id}/operators

Gets the operators that performed the given operation. The IDs returned can be used to fetch more information about the operator in the Get an operator endpoint.

Request examples

curl -X GET \
-H 'Authorization: Bearer YOUR_TOKEN' \
'https://api.withleaf.io/services/operations/api/operations/{id}/operators'

Response

{
"operators": [
"f2f4723a-2bfe-472b-b6f7-7874c8500208"
]
}

Get the operation's sessions

 GET /operations/{id}/sessions

Get compiled machine, implement and operator data for a management view with total area covered and working hours.

Important

It requires the enableOperationsSession configuration enabled to create this data. Currently, this information is only available for John Deere operations.

Request examples

curl -X GET \
-H 'Authorization: Bearer YOUR_TOKEN' \
'https://api.withleaf.io/services/operations/api/operations/{id}/sessions'

Response

[
{
"machineId": "uuid",
"serialNumber": "SERIALNUMBER001",
"sessions": [
{
"id": "sessionId",
"startTime": "2023-11-29T11:03:42.000Z",
"endTime": "2023-11-29T20:58:36.000Z",
"operator": {
"id": "operatorId",
"name": "SIDINEY BATISTA"
},
"area": {
"value": 18.215,
"unit": "ha"
}
}
]
},
{
"machineId": "uuid",
"serialNumber": "SERIALNUMBER002",
"sessions": [
{
"id": "sessionId",
"startTime": "2010-10-10T10:10:10.000000000Z",
"endTime": "2010-10-10T10:10:10.000000000Z",
"operator": {
"id": "uuid",
"name": "Operator A"
},
"area": {
"value": 26.019,
"unit": "ha"
}
}
]
},
{
"machineId": "machineId",
"serialNumber": "1RW9640DKNA075787",
"sessions": [
{
"id": "sessionId",
"startTime": "2010-10-10T10:10:10.000000000Z",
"endTime": "2010-10-10T10:10:10.000000000Z",
"operator": {
"id": "uuid",
"name": "Operator A"
},
"implement": {
"id": "uuid",
"name": "Implement 1"
},
"area": {
"value": 39.410,
"unit": "ha"
}
}
]
}
]

Crop operation by field

 POST /operations/cropOperationByField

This endpoint can be used to remove points from the operation standardGeojson that are outside of the field geometry.

Request examples

curl -X POST \
-H 'Authorization: Bearer YOUR_TOKEN' \
-d '{ "id": "operationId"}' \
'https://api.withleaf.io/services/operations/api/operations/cropOperationByField'

Response

{
"id": "1162a1c6-9872-4d7f-9833-5d48add8eed4",
"message": "Sent operation to be processed.",
"leafFileId": "33020f03-5889-4c0f-b465-7a7e2c03a91d"
}

You could monitor the processing status using the leafFileId by our Alerts Service.

Get files from an operation

 GET /operations/{id}/files

Allow the user to fetch all files resources that were aggregated to generate an Field Operation.

Request examples

curl -X GET \
-H 'Authorization: Bearer YOUR_TOKEN' \
'https://api.withleaf.io/services/operations/api/operations/{id}/files'

Response

Check our sample response to have complete represention on the expected output.

Reprocess an operation

 POST /operations/{id}/reprocess

Allows reprocessing an operation already created, starting from the merge step. The standardGeoJSON, filteredGeoJSON, summary and images will be updated.

Request examples

curl -X POST \
-H 'Authorization: Bearer YOUR_TOKEN' \
'https://api.withleaf.io/services/operations/api/operations/{id}/reprocess'

You could monitor the processing status by our Alerts Service.

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 Operations Events

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