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
Upload specific filePOST /files
Merge filesPOST /files/merge

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 or Leaf
statusprocessed, failed or processing
originprovider, automerged, merged or uploaded
organizationIdthe provider organizationId (only available for John Deere)
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

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

  • page, an integer specifying the page being fetched
  • size, an integer specifying the size of the page
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.

Leaf has two "file upload" enpoints. 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. It almost every case, this endpoint is the correct one to use for file conversions. If you know that which provider a zip file came from and also know that it contains only operations files from the same operation, please use our specific file upload endpoint.

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

If provider is not set or 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/return one file id for each file that is detected. These individual files can then be accessed individually by their ID, or via their associated field boundary.

curl -X POST \
-H 'Authorization: Bearer YOUR_TOKEN' \
-F 'file=shapefile.zip' \
'https://api.withleaf.io/services/operations/api/batch?' \
'provider=JohnDeere&leafUserId=id'

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


Get Batch upload object

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.

Move through the tabs below to see requests and response samples.

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)

Get Batch upload object files

After uploading a file, you can see a summary of each individual file by querying the batch upload ID.

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

Which will result in a response containing each file's summary and processing status.


Upload specific file

 POST /files

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

Leaf has two "file upload" enpoints. If you know that what provider a zip file came from and also know that it contains only operations files from the same operation, this is the right endpoint. For every other case, please refer to our batch endpoint.

This endpoint receives three URL parameters, one of them is optional.

A leafUserId, provider and fileFormat (optional).

When you are sure which provider a file came from and that if there are multiple files they belong to the same operations, you can add the fileFormat, that must be one of the following:

ADAPTADM
CN1
DATCLIMATE
GEOJSON
ISO11783
SHAPEFILE
TRIMBLE

Along with the fileFormat, a provider must be set and be one of the following:

Leaf
ClimateFieldView
CNHI
JohnDeere
Trimble

When unsure about the format or when there can be more than one format in the same zip, you can use our generic uploader and Leaf will detect the files present. For that, set provider to Leaf and don't include fileFormat. Leaf will detect files present in a number of different ways and hierarchies and create/return one file id for each detection. This is very important because it's slightly different than when uploading a zip file you are sure refers to the same operation and same provider, creating only one file even if the zip contains multiple files for the same operation.

curl -X POST \
-H 'Authorization: Bearer YOUR_TOKEN' \
-F 'file=shapefile.zip' \
'https://api.withleaf.io/services/operations/api/files?' \
'fileFormat=SHAPEFILE&provider=JohnDeere&leafUserId=id'

After a few minutes, you can query each of the files individually on Get a File or all of them, filtering by createdDate, on Get all Files.


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'