Manual File Upload 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
Upload a filePOST /batch
Get a batchGET /batch/{id}
Get all batchesGET /batch
Retry a batchPUT /batch/{id}/retry
Get Batch Files StatusGET /batch/{id}/status

To easily test these endpoints, we recommend using our Postman collection.

requires Leaf User

You will need a Leaf User to manually upload files. If you don't have a Leaf User, see the Leaf user overview

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:

Other
Leaf
ClimateFieldView
CNHI
JohnDeere
Trimble
AgLeader
Farmobile
PrecisionPlanting

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 FormatMonitor ModelDetails
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
Expected file structure

GreenStar 4 (4600+)

jd-data
└── log
└── *.jdl

GreenStar 3 (2630)

GS3_2630
└── RCD
└── EIC
└── global.ver
└── documentation
└── ...
β”œβ”€β”€ *.fdd
└── *.fdl

Green Star 2 (2600)

...
└── RCD
β”œβ”€β”€ *.fdd
└── *.fdl

Climate FieldView

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

20|20 SeedSense Generation 1 and Generation 2

...
β”œβ”€β”€ harvest_*.dat – Harvest data
β”œβ”€β”€ field_map_*.dat – Planting data
└── liquid_map_*.dat - AsApplied spraying data

20|20 SeedSense Generation 3

...
└── *.2020

CNHI

File FormatMonitor ModelDetails
CN1Case IH Pro 700, equivalent to New Holland IntelliView IV/file.cn1/index.vy1
ISOXMLCase IH Pro 1200, equivalent to New Holland IntelliView 12/TASKDATA.XML
Expected file structure

Voyager 2

*.cn1
└── ...
└── *.vy1

ISOXML

TASKDATA
β”œβ”€β”€ TASKDATA.XML
└── *.bin

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
Expected file structure

AgLeader Integra (versions 3.5+), Versa

...
β”œβ”€β”€ *.agdata
└── *.agsetup

AgLeader Edge, Insight, and Integra (version 3.4)

...
└── *.ilf

AgLeader PF Advantage, PF 3000, PF 3000 Pro, YM2000

...
└── *.yld

Trimble

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

GFX-750, TMX-2050

Agdata
β”œβ”€β”€ Fields
└── *.agf
β”œβ”€β”€ implements
└── *.agi
β”œβ”€β”€ prescriptions
└── *.agm
β”œβ”€β”€ Tasks
└── *.agt
β”œβ”€β”€ Users
└── *.agu
└── vehicles
└── *.agv

CFX-750, FMX

AgGPS
└── Data
└── "Grower"
└── Farm
└── field
└── "Task"
β”œβ”€β”€ *.cpg
β”œβ”€β”€ *.dbf
β”œβ”€β”€ *.shp
└── *.shx

Precision Planting (beta)

File FormatMonitor ModelDetails
PP202020|20A zip with .2020 files.
Expected file structure

20|20 SeedSense Generation 1 and Generation 2

...
β”œβ”€β”€ harvest_*.dat – Harvest data
β”œβ”€β”€ field_map_*.dat – Planting data
└── liquid_map_*.dat - AsApplied spraying data

20|20 SeedSense Generation 3

...
└── *.2020

ISOXML

Expected file structure
TASKDATA
β”œβ”€β”€ *.XML
└── *.bin

CLAAS

Expected file structure
TASKDATA
β”œβ”€β”€ *.XML
└── *.bin

Kuhn

Expected file structure
TASKDATA
β”œβ”€β”€ *.XML
└── *.bin

Kverneland Group

Expected file structure
TASKDATA
β”œβ”€β”€ *.XML
└── *.bin

MΓΌller-Elektronik

Expected file structure
TASKDATA
β”œβ”€β”€ *.XML
└── *.bin

Teknomika

Expected file structure
TASKDATA
β”œβ”€β”€ *.XML
└── *.bin

Topcon Precision Agriculture

Expected file structure
TASKDATA
β”œβ”€β”€ *.XML
└── *.bin

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, Raven Slingshot, and Topcon. Since Shapefiles do not contain information on the units used, we assume the default units from the provider will be used.

Request examples

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

{
"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`` is just informative and should not be used programatically.

{
"id": "c21e6495-3e39-4c5f-b35c-d33fa06c25d8",
"leafUserId": "fc7c52ad-d228-4332-9e18-de979a293457",
"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
No valid files foundUnable to find a valid file based on supported extensions and expected file structure
Leaf internal error. Please contact SupportInternal error that need to be reported
Files found but unable to read. Please check file format before re-trying or contact SupportA 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.

Request examples

import requests
TOKEN = 'YOUR_TOKEN'
endpoint = 'https://api.withleaf.io/services/operations/api/batch/{batch_id}'
headers = {'Authorization': f'Bearer {TOKEN}'}
response = requests.get(endpoint, headers=headers)
print(response.json())

Response

{
"id": "9b561906-efac-43a3-9378-641e3698da5d",
"leafUserId": "1481bc9b-cdc7-45c1-9f0e-592da6306dfe",
"provider": "Other",
"status": "PROCESSED",
"leafFiles": [
"f14203df-4144-43b7-a383-2ed321f395ce",
"810b1475-cb49-437b-8658-d29038ce2fa4"
]
}

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.

Request examples

import requests
TOKEN = 'YOUR_TOKEN'
endpoint = 'https://api.withleaf.io/services/operations/api/batch'
headers = {'Authorization': f'Bearer {TOKEN}'}
response = requests.put(endpoint, headers=headers)
print(response.json())

Response

[
{
"id": "9e47ae29-6a84-4a9c-9e5f-01802f6dceea",
"leafUserId": "5ded9409-c99f-4379-9173-c01b1631f274",
"provider": "Other",
"status": "PROCESSED",
"leafFiles": [
"74d5aeb6-9a0e-43c6-986c-a5f17eecbddc",
"475fcad3-b534-409d-8c8b-cec4dabd1b8b"
]
}
]

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.

Request examples

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

Response

{
"id": "36d8551f-409d-41f2-94b4-04c9fe16289b",
"leafUserId": "089bb77b-2415-43df-a246-6c0a5937c774",
"fileName": "filename.zip",
"size": 8652951,
"provider": "Other",
"status": "RECEIVED",
"uploadTimestamp": "2021-03-12T19:50:55.567755Z"
}

Batch Files Status

Β GET /batch/{id}/status

After your batch generate the list of Leaf Files, this enpoint can be used to verify the status of each resource complied on the same response.

Request examples

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

Response

{
"converted": {
"leafFiles": [
"06512392-8d69-4033-8127-4cc62b7176b9",
"075fd0f6-af1a-433d-ad7a-e3e979179244"
]
},
"processing": {
"leafFiles": [
"9d22cbca-03ff-47e8-ac66-f6d463d206f4"
]
},
"failed": {
"standardGeojson": {
"leafFiles": [
"0abca517-09f2-4d1d-9627-9cd3147e9ec3"
],
"status": "failed",
"message": "no points passed the filter"
}
}
}

The most common failed messages are listed here.

Please note

Once you have finished setting up manual file upload, refer to machine file conversion next