Machine File Conversion Endpoints
About
All HTTP methods should be prepended by this service's endpoint:
This service has the following endpoints available:
| Description | Endpoints |
|---|---|
| Get all files | GET /files |
| Get a file | GET /files/{id} |
| Get a file summary | GET /files/{id}/summary |
| Get a file's images | GET /files/{id}/images |
| Get a file's units | GET /files/{id}/units |
| Upload a file | POST /batch |
| Get a batch | GET /batch/{id} |
| Get all batches | GET /batch |
| Retry a batch | PUT /batch/{id}/retry |
| Merge files | POST /files/merge |
| Get a file status | GET /files/{id}/status |
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 for each of the providers.
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 |
|---|---|
leafUserId | uuid of one of your users |
provider | CNHI, JohnDeere, Trimble, ClimateFieldView, AgLeader or Leaf |
status | processed, failed or processing |
origin | provider, automerged, merged or uploaded |
organizationId | the provider organizationId (only available for John Deere) |
batchId | uuid of the upload response (only available for uploaded files) |
createdTime | ISO 8601 date. Returns operations from the createdTime onward |
startTime | ISO 8601 date. Returns operations from the startTime onward |
endTime | ISO 8601 date. Returns operations until the endTime |
operationType | applied, planted or harvested |
minArea | a 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 and standard moisture available in 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
- Python
- JavaScript
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", "harvested" and "tillage" operation files.
Get a file
GET /files/{id}
Gets a single file by its id.
- cURL
- Python
- JavaScript
Response
Here's a link with sample responses for "planted", "applied", "harvested" and "tillage" operation files.
Get a file summary
GET /files/{id}/summary
Gets the summary, if available, for the file id.
- cURL
- Python
- JavaScript
Response
Here's a link with sample responses for "planted", "applied", "harvested" and "tillage" 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
- Python
- JavaScript
Returns a JSON list of the following format:
The property refers to the property extracted from files' 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 a file's units
GET /files/{id}/units
Gets the file's properties and their units.
- cURL
- Python
- JavaScript
Returns a JSON like the following:
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.
Upload a file
POST /batch
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 process, which can in turn be used to retrieve the ID's of the files being processed.
File size limit of 3 GB
Currently, our upload endpoints accepts files with the maximum size limited to 3 gigabytes.
This endpoint receives two required URL parameters, a leafUserId and provider
A provider can be set as one of the following:
If provider is set to "Other", Leaf will detect which files are present in the .zip file and process them accordingly.
Leaf will detect files present in the uploaded .zip and create file ids for the files that are detected in the uploaded .zip. These files can then be accessed individually by their file ID, batch ID, or their associated field boundary.
Expected file structures from each provider are listed below. Very often these default file structures are edited by users. In these cases Leaf attempts to automatically repair the file structure and find all necessary files within any uploaded .zip.
The following file formats from each provider are supported:
JohnDeere
| File Format | Monitor Model | Details |
|---|---|---|
| GS3 | GreenStar 3 – 2630 | /GS3_2630/profile/RCD/EIC/global.ver |
| Gen4 | Gen 4 - 4600/4630 | /JD-Data/log/user defined name/*.jdl |
| Shapefile | Exported from MyJohnDeere | Shapefile with extra metadata in a .json file |
Expected file structure
GreenStar 4 (4600+)
GreenStar 3 (2630)
Green Star 2 (2600)
Climate FieldView
| File Format | Monitor Model | Details |
|---|---|---|
| dat | All files from Climate FieldView | A zip with .dat files |
Expected file structure
20|20 SeedSense Generation 1 and Generation 2
20|20 SeedSense Generation 3
CNHI
| File Format | Monitor Model | Details |
|---|---|---|
| CN1 | CaseIH monitors or exported from CNH Connects | /file.cn1/index.vy1 |
Expected file structure
Voyager 2
AgLeader
| File Format | Monitor Model | Details |
|---|---|---|
| yld | YM2000, PFAdvantage & other OEM systems | A zip with .yld files |
| ilf | INTEGRA / Insight / Edge | A zip with .ilf files |
| agdata | INTEGRA / VERSA / COMPASS | A zip with .agdata files |
Expected file structure
AgLeader Integra (versions 3.5+), Versa
AgLeader Edge, Insight, and Integra (version 3.4)
AgLeader PF Advantage, PF 3000, PF 3000 Pro, YM2000
Trimble
| File Format | Monitor Model | Details |
|---|---|---|
| AgData | FMX and CFX monitors | /AgData/ |
| AgGPS | TMX and GFX monitors | /AgGPS/ |
Expected file structure
GFX-750, TMX-2050
CFX-750, FMX
Precision Planting (beta)
| File Format | Monitor Model | Details |
|---|---|---|
| PP2020 | 20|20 | A zip with .2020 files. |
Expected file structure
20|20 SeedSense Generation 1 and Generation 2
20|20 SeedSense Generation 3
ISOXML
Expected file structure
CLAAS
Expected file structure
Kuhn
Expected file structure
Kverneland Group
Expected file structure
Müller-Elektronik
Expected file structure
Teknomika
Expected file structure
Topcon Precision Agriculture
Expected file structure
Farmobile
| File Format | Details |
|---|---|
| GeoJSON | GeoJSON 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 Format | Details |
|---|---|
| Shapefile | Shapefiles exported from SMS. Since Shapefiles do not contain information on the units used, we assume the default units from SMS are being used. |
- cURL
- Python
- JavaScript
Response
Returns a single JSON object, as shown below:
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:
| Status | Description |
|---|---|
| RECEIVED | Is the default state for every batch created |
| PROCESSED | When all the files included in the batch were processed, and at least one file have status SUCCESS |
| FAILED | The 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.
The following status can be present on statusDetails:
| Status | Description |
|---|---|
| No valid files found | Unable to find a valid file based on supported extensions and expected file structure |
| Leaf internal error. Please contact Support | Internal error that need to be reported |
| Files found but unable to read. Please check file format before re-trying or contact Support | A valid file was found but could not be converted |
Get Batch upload
GET /batch/{batch_id}
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.
- cURL
- Python
- JavaScript
Response:
When you query a batch upload ID, you will receive a single JSON object:
Get all Batches
GET /batch
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.
- cURL
- Python
- JavaScript
Response:
When you query a batch upload ID, you will receive a JSON with list of batches:
Retry a batch
PUT /batch/{id}/retry
If a batch upload does not complete as expected, this endpoint allows you to try again. This action will reprocess the fragments of uploaded data that didn't succeed processing before, keeping existing converted files unaffected.
- cURL
- Python
- JavaScript
Response
Returns a single JSON object, similar to the upload endpoint response:
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:
- cURL
- Python
- JavaScript
Returns a single JSON object:
After a few minutes, you can consult the result of Leaf processing over this file by performing GET consults in this.
Get a file status
GET /files/{id}/status
Get status by file processing step by id.
- cURL
- Python
- JavaScript
Response
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