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 filesGET /files
Get a fileGET /files/{id}
Get a file summaryGET /files/{id}/summary
Get a file's imagesGET /files/{id}/images
Get a file's unitsGET /files/{id}/units
Upload a filePOST /batch
Get a batchGET /batch/{id}
Get all batchesGET /batch
Merge filesPOST /files/merge
Get all operationsGET /operations
Get an operationGET /operations/{id}
Get an operation summaryGET /operations/{id}/summary
Get an operation's imagesGET /operations/{id}/images
Get an operation's unitsGET /operations/{id}/units

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

requires Leaf User with credentials

To have access to operation files, you will need a Leaf User with valid credentials from the provider you want to access data. If you don't have a Leaf User or you have not connected it with any provider yet, see how to create a Leaf User or how to add credentials to a Leaf User.


Get all files

 GET /files

Gets a paged list of files 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 or Leaf
statusprocessed, failed or processing
originprovider, automerged, merged or uploaded
organizationIdthe provider organizationId (only available for John Deere)
batchIduuid of the upload response (only available for uploaded files)
createdTimeISO 8601 date. Returns operations from the createdTime onward
operationStartTimeISO 8601 date. Returns operations from the operationStartTime onward
operationEndTimeISO 8601 date. Returns operations until the operationEndTime
operationTypeapplied, planted or harvested
minAreaa number (Double) representing the minimum area (square meters) of the operations to be returned

Also, for operationType: harvested we can process the yield properties related to the operation using the crop density using this table.

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)
the default value for page size is 20

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

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

Response

The response is a JSON with the key "operations" referring to a list of files. Here's a link with sample responses for "planted", "applied" and "harvested" operation files.

{
"message": "SUCCESS",
"operations": [OPERATION]
}

Get a file

 GET /files/{id}

Gets a single file by its id.

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

Response

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


Get a file summary

 GET /files/{id}/summary

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

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

Response

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


Get a file's images

 GET /files/{id}/images

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

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

Get a file's units

 GET /files/{id}/units

Gets the file's properties and their units.

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

Upload a file

 POST /batch

Posts/creates a new file in Leaf. The file must be sent as a zip.

This endpoint accepts a .zip of operation files, detects which files are in the .zip, and returns the ID of the batch, which can in turn be used to retrieve the ID's of the identified operation files.

This endpoint receives two required URL parameters, a leafUserId and provider

A provider can be set as one of the following:

Other
ClimateFieldView
CNHI
JohnDeere
Trimble

Leaf will detect files present in the uploaded .zip and convert them, returning one file id for each individual operation detected. These individual files can then be accessed individually by their ID, or via their associated field boundary.

The following file formats from each provider are supported:

JohnDeere

File FormatMonitor ModelDetails
GS2GreenStar 2 – 1800/2600/RCD/global.ver
GS3GreenStar 3 – 2630/GS3_2630/profile/RCD/EIC/global.ver
Gen4Gen 4 - 4600/4630/JD-Data/log/user defined name/*.jdl
ShapefileExported from MyJohnDeereShapefile with extra metadata in a .json file

Climate FieldView

File FormatMonitor ModelDetails
datAll files from Climate FieldViewA zip with .dat files

CNHI

File FormatMonitor ModelDetails
CN1CaseIH monitors or exported from CNH Connects/file.cn1/index.vy1

AgLeader

File FormatMonitor ModelDetails
yldYM2000, PFAdvantage & other OEM systemsA zip with .yld files
ilfINTEGRA / Insight / EdgeA zip with .ilf files
agdataINTEGRA / VERSA / COMPASSA zip with .agdata files

Trimble

File FormatMonitor ModelDetails
AgDataFMX and CFX monitors/AgData/
AgGPSTMX and GFX monitors/AgGPS/

Farmobile

File FormatDetails
GeoJSONGeoJSON files exported from Farmobile. Since GeoJSON files do not contain information on the units used, we assume the default units from Farmobile are being used.

Other

File FormatDetails
ShapefileShapefiles exported from SMS. Since Shapefiles do not contain information on the units used, we assume the default units from SMS are being used.
curl -X POST \
-H 'Authorization: Bearer YOUR_TOKEN' \
-F 'file=shapefile.zip' \
'https://api.withleaf.io/services/operations/api/batch?' \
'provider=JohnDeere&leafUserId=id'
Response

Returns a single JSON object, as shown below:

{
"id": "996aea67-52bc-4d4b-9b77-028756dc0ee9",
"leafUserId": "ede8f781-1d55-4b2d-83a1-6785ddab6e1d",
"fileName": "Climate.zip",
"size": 8652951,
"provider": "Other",
"status": "RECEIVED",
"uploadTimestamp": "2021-03-12T19:50:55.567755Z"
}

This id can then be queried to retrieve on Get batch to get the individual file ID's. Then you can query each of the files individually with Get a File or all of them, filtering by batchId, on Get all Files.

Batch status

The status key will evolve accordingly to the following states:

StatusDescription
RECEIVEDIs the default state for every batch created
PROCESSEDWhen all the files included in the batch were processed, and at least one file have status SUCCESS
FAILEDThe batch did not generated any leaf files with status SUCCESS

The messages with FAILED status have the key statusDetails. The statusDetails are just informative and should not be used programatically.

{
"id": "996aea67-52bc-4d4b-9b77-028756dc0ee9",
"leafUserId": "ede8f781-1d55-4b2d-83a1-6785ddab6e1d",
"fileName": "Climate.zip",
"size": 8652951,
"provider": "Other",
"status": "FAILED",
"statusDetails": "No operation found. Check file format before re-trying or contact support. Check file format before re-trying or contact support",
"uploadTimestamp": "2021-03-12T19:50:55.567755Z"
}

The following status can be present on statusDetails:

StatusDescription
Failed to open Zip fileIt means that the file uploaded is not a valid zip
No operation foundWe could not identify any valid machinery file inside the zip uploaded
No operation discoveredWhen we can't find any machinery file inside the batch
Error extracting files from batchWhen an error internal to our API happened

Get Batch upload

Once you've uploaded files, you can then query these files individually, merge the files, or query for them via Get all Files. You can also query the batch upload ID to see a list of files generated in the upload and a status of the upload with this endpoint.

import requests
url = "https://api.withleaf.io/services/operations/api/batch/{batch_id}/"
headers = {'Authorization': 'Bearer YOUR_LEAF_TOKEN'}
response = requests.request("GET", url, headers=headers)
print(response.text)
Response:

When you query a batch upload ID, you will receive a single JSON object:

{
"id": "f893c921-0f38-4f39-9f3e-be765ac61df0",
"leafUserId": "bdf5f624-fb9b-4294-949c-29e979f0ce5a",
"provider": "Other",
"status": "PROCESSED",
"leafFiles": [
"8334f4bb-48de-44e2-903b-6dedd6db6683",
"81778f58-8eed-41cc-a025-e653ea85b01e",
"0f606bef-b529-4899-854c-9b698cd08762",
"84fec273-b458-4be7-8feb-44204502f126",
"92b7367b-2ffd-4a82-ba9b-5a40e8b68714",
"90e7e130-8f33-4752-b8f4-3a132246f047",
"cb97857e-61b0-4fbe-a5c1-1083cfa6738f",
"0cded205-7734-40fb-8906-b82d36e35845",
"dc24d491-983c-4ebe-b961-8c749943529f",
"67af8697-47bc-4886-935f-5880d1eba31d",
"8b7d8b7b-e682-4c3e-aee2-3b7713cc81a4",
"e5067ed3-8463-43b9-a8a5-3b3c1eee44bc",
"b9d30d3a-0207-410f-81da-afb31a1b36cb",
"eace9b90-a520-4c4c-af89-4c3fd5da68fa",
"6ea55c68-203f-448b-9e7f-dcd014c31cc3"
]
}

Get all Batches

Once you've uploaded files, you can then query these files individually, merge the files, or query for them via Get all Files. You can also query the batch upload ID to see a list of files generated in the upload and a status of the upload with this endpoint.

import requests
url = "https://api.withleaf.io/services/operations/api/batch"
headers = {'Authorization': 'Bearer YOUR_LEAF_TOKEN'}
response = requests.request("GET", url, headers=headers)
print(response.text)
Response:

When you query a batch upload ID, you will receive a JSON with list of batches:

[
{
"id": "f893c921-0f38-4f39-9f3e-be765ac61df0",
"leafUserId": "bdf5f624-fb9b-4294-949c-29e979f0ce5a",
"provider": "Other",
"status": "PROCESSED",
"leafFiles": [
"8334f4bb-48de-44e2-903b-6dedd6db6683",
"81778f58-8eed-41cc-a025-e653ea85b01e",
"0f606bef-b529-4899-854c-9b698cd08762",
"84fec273-b458-4be7-8feb-44204502f126",
"92b7367b-2ffd-4a82-ba9b-5a40e8b68714",
"90e7e130-8f33-4752-b8f4-3a132246f047",
"cb97857e-61b0-4fbe-a5c1-1083cfa6738f",
"0cded205-7734-40fb-8906-b82d36e35845",
"dc24d491-983c-4ebe-b961-8c749943529f",
"67af8697-47bc-4886-935f-5880d1eba31d",
"8b7d8b7b-e682-4c3e-aee2-3b7713cc81a4",
"e5067ed3-8463-43b9-a8a5-3b3c1eee44bc",
"b9d30d3a-0207-410f-81da-afb31a1b36cb",
"eace9b90-a520-4c4c-af89-4c3fd5da68fa",
"6ea55c68-203f-448b-9e7f-dcd014c31cc3"
]
}
]

Merge files

 POST /files/merge

Posts a merge operation to our server.

A merge operation is performed asynchronously. This call will return immediately with the newly created file entry, but at this point, the file is not already processed and available. You will need to make a new GET /files request for the new id and check the status. A status value of processed means the file is done merging.

A merge process has some validations, the files passed must belong to the same leafUserId, be of the same operation type and have the status as processed. If any of those filters fail, the endpoint will result in HTTP 400 error.

It receives a single JSON object with the ids entry. Example:

{
"ids": [ "id1", "id2", "so on" ]
}
curl -X POST \
-H 'Authorization: Bearer YOUR_TOKEN' \
-d '{ "ids": [ "id1", "id2" ] }'
'https://api.withleaf.io/services/operations/api/files/merge'

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

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)
the default value for page size is 20

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

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

Response

[
{
"id": "1aa1ce7b-8bb9-4b2d-9421-d7a662cc1bb1",
"apiOwnerUsername": "leaf",
"leafUserId": "97770d44-62c4-48c3-8187-6be80f6de3d2",
"startTime": "2015-04-18T19:31:27Z",
"endTime": "2015-04-18T19:58:50Z",
"updatedTime": "2021-08-24T16:00:15.062Z",
"type": "planted",
"files": [
"8334f4bb-48de-44e2-903b-6dedd6db6683",
"81778f58-8eed-41cc-a025-e653ea85b01e",
"0f606bef-b529-4899-854c-9b698cd08762",
"84fec273-b458-4be7-8feb-44204502f126",
"92b7367b-2ffd-4a82-ba9b-5a40e8b68714"
],
"fields": [
{
"id": "3a90d11a-70d0-4f62-b6d4-32006b1dcb6a"
}
]
}
]

Get a operation

 GET /operations/{id}

Gets a single operation by its id.

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

Response

{
"id": "1aa1ce7b-8bb9-4b2d-9421-d7a662cc1bb1",
"apiOwnerUsername": "leaf",
"leafUserId": "97770d44-62c4-48c3-8187-6be80f6de3d2",
"startTime": "2015-04-18T19:31:27Z",
"endTime": "2015-04-18T19:58:50Z",
"updatedTime": "2021-08-24T16:00:15.062Z",
"type": "planted",
"files": [
"8334f4bb-48de-44e2-903b-6dedd6db6683",
"81778f58-8eed-41cc-a025-e653ea85b01e",
"0f606bef-b529-4899-854c-9b698cd08762",
"84fec273-b458-4be7-8feb-44204502f126",
"92b7367b-2ffd-4a82-ba9b-5a40e8b68714"
],
"fields": [
{
"id": "3a90d11a-70d0-4f62-b6d4-32006b1dcb6a"
}
]
}

Get an operation summary

 GET /operations/{id}/summary

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

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" and "harvested" operations.


Get an operation's images

 GET /operations/{id}/images

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

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

Get an operation's units

 GET /operations/{id}/units

Gets the operations's properties and their units.

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

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