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:

Description	Endpoints
Upload a file	POST `/batch`
Get a batch	GET `/batch/{id}`
Get all batches	GET `/batch`
Retry a batch	PUT `/batch/{id}/retry`
Get Batch Files Status	GET `/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 Format	Monitor Model	Details
GS2	GreenStar 2 – 2600	`/RCD/.fdd, .fdl`
GS3	GreenStar 3 – 2630	`/GS3_2630/profile/RCD/EIC/global.ver`
Gen4	Gen 4 - 4600/4630	`/JD-Data/log/*.jdl`
Shapefile	Exported from MyJohnDeere	Shapefile with extra metadata in a `.json` file

Climate FieldView

File Format	Monitor Model	Details
dat	20\|20 SeedSense Gen 1 and Gen 2	A zip with `.dat` files
2020	20\|20 SeedSense Gen 3	A zip with `.2020` files

CNHI

File Format	Monitor Model	Details
CN1	Case IH Pro 700 / New Holland IntelliView IV	`<name>.cn1/index.vy1`
ISOXML	Case IH Pro 1200 / New Holland IntelliView 12	`/TASKDATA/TASKDATA.XML`

AgLeader

File Format	Monitor Model	Details
yld	YM2000, PF Advantage & 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` and `.agsetup` files

Trimble

File Format	Monitor Model	Details
AgData	FMX and CFX monitors	`/AgData/`
AgGPS	TMX and GFX monitors	`/AgGPS/` (shapefile-based)

Precision Planting

File Format	Monitor Model	Details
dat	20\|20 SeedSense Gen 1 and Gen 2	A zip with `.dat` files
PP2020	20\|20 SeedSense Gen 3	A zip with `.2020` files

Raven Slingshot

File Format	Monitor Model	Details
FMIS	Raven FMIS	A zip with `.xml` and `.tab` files
JDP	Raven JDP	A zip with `.jdp` files

ISOXML

File Format	Supported Brands	Details
ISOXML	CLAAS, Kuhn, Kverneland Group, Müller-Elektronik, Teknomika, Topcon	`/TASKDATA/` with `.XML` and `.bin`

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

For detailed file structure requirements, preparation guidelines, and shapefile column mappings, see Supported File Formats.

Request examples

cURL
Python
JavaScript

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:

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`` 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:

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.

Request examples

cURL
Python
JavaScript

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

Request examples

cURL
Python
JavaScript

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

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

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

About#

requires Leaf User

Upload a file#

File size limit of 3 GB

JohnDeere#

Climate FieldView#

CNHI#

AgLeader#

Trimble#

Precision Planting#

Raven Slingshot#

ISOXML#

Farmobile#

Other#

Request examples#

Response#

Batch status#

Get Batch upload#

Request examples#

Response#

Get all Batches#

Request examples#

Response#

Retry a batch#

Request examples#

Response#

Batch Files Status#

Request examples#

Response#

Please note

About

Upload a file

JohnDeere

Climate FieldView

CNHI

AgLeader

Trimble

Precision Planting

Raven Slingshot

ISOXML

Farmobile

Other

Request examples

Response

Batch status

Get Batch upload

Request examples

Response

Get all Batches

Request examples

Response

Retry a batch

Request examples

Response

Batch Files Status

Request examples

Response