Machine File Conversion 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
Get a file statusGET /files/{id}/status
Get a file's outsideFieldGeoJSONGET /files/{id}/outsideFieldGeojson
Get all outsideFieldGeoJSON filesGET /files/outsideFieldGeojson
Get uncovered filesGET /files/uncoveredFiles
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 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
leafUserIduuid of one of your users
providerCNHI, JohnDeere, Trimble, ClimateFieldView, AgLeader, RavenSlingshot, Stara 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
startTimeISO 8601 date. Returns operations from the startTime onward
updatedTimeISO 8601 date. Returns operations from the updatedTime onward
endTimeISO 8601 date. Returns operations until the endTime
operationTypeapplied, planted, harvested or tillage
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 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)
  • sort, the sorting order of the results; can be multi-value, where the first value to be passed will take priority over the next values; you can also specify the order as asc or desc with asc being the default. Example: id, desc
    • Valid values for sorting are: id, fileName, createdTime, updatedTime, origin, leafUserId, sizeInBytes, provider, organizationId, fileFormat.
the default value for page size is 20

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

Request examples

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", "harvested" and "tillage" operation files.

Get a file

 GET /files/{id}

Gets a single file by its id.

Request examples

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", "harvested" and "tillage" operation files.

Get a file summary

 GET /files/{id}/summary

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

Request examples

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

Request examples

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

Response

[
{
"property": "elevation",
"ramp": {
"0%": [200, 0, 0],
"35%": [255, 40, 0],
"45%": [255, 150, 0],
"55%": [255, 240, 0],
"65%": [ 0, 230, 0],
"75%": [ 0, 190, 0],
"100%": [ 0, 130, 0],
"nv": [ 0, 0, 0, 0]
},
"url": "URL",
"downloadUrl": "URL"
},
....
]

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.

Request examples

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

Response

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

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.

Get a file status

 GET /files/{id}/status

Get status by file processing step by id.

Request examples

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

Response

{
"rawGeojson": {
"status": "processed",
"message": "ok"
},
"normalizedGeojson": {
"status": "processed",
"message": "ok"
},
"standardGeojson": {
"status": "processed",
"message": "ok"
},
"propertiesPNGs": {
"status": "processed",
"message": "ok"
},
"areaAndYield": {
"status": "processed",
"message": "ok"
},
"summary": {
"status": "processed",
"message": "ok"
},
"units": {
"status": "processed",
"message": "ok"
},
"originalFile": {
"status": "processed",
"message": "ok"
},
"cleanupGeojson": {
"status": "processed",
"message": "ok"
}
}

Get a file's outsideFieldGeoJSON

 GET /files/{id}/outsideFieldGeojson

Gets a GeoJSON file with all points not considered in any Field Operation for that Leaf user. This file depends on the splitOperationsByField and enableOutsideFieldGeojson configurations previously enabled.

Request examples

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

Response

{
"fields": [
"uuid"
],
"featureCount": 21,
"outsideFieldGeojson": "url",
"downloadOutsideFieldGeojson": "url"
}

The response will show the number of points/features from the file in the property featureCount. The URL to get access to the file is available in the downloadOutsideFieldGeojson property.

This response also shows, in the fields property, all the fields the entire file (from where the outside points were extracted) intersects.

Get all outsideFieldGeoJSON files

 GET /files/outsideFieldGeojson

Gets a list off all outside GeoJSON files with points not considered in any Field Operation for that Leaf user. This information depends on the splitOperationsByField and enableOutsideFieldGeojson configurations previously enabled.

Request examples

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

Response

[
{
"id": "uuid",
"fields": [
"uuid"
],
"featureCount": 21,
"outsideFieldGeojson": "url",
"downloadOutsideFieldGeojson": "url"
}
]

The response will show a list of files that has outside points. For each one, the property featureCount will show the number of points/features from the file. The URL to get access to the file is available in the downloadOutsideFieldGeojson property.

This response also shows, in the fields property, all the fields the entire file (from where the outside points were extracted) intersects.

Get uncovered files

 GET /files/uncoveredFiles?leafUserId={leafUserId}

Get a list of files that did not generate Field Operations, as they do not intersect with any field. The returned IDs can be consulted in the Get a file endpoint.

This endpoint requires the leafUserId filter.

Request examples

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

Response

{
"files": [
"c3ad6c7b-19b8-4cd7-580a-dfab82043465",
"c3ad6c7b-c472-49e9-aab2-7ad222843465",
"9aa68735-5a04-42ef-0983-dbdd2bcdfa16"
]
}

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.

Request body

{
"ids": [ "id1", "id2", "so on" ]
}

Request examples

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

Response

{
"id": "id",
"status": "SENT_TO_MERGE"
}

After a few minutes, you can consult the result of Leaf processing over this file by performing GET consults in this.

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

Troubleshooting

If a file fails to process, more information about the cause of the failure can be obtained from the status endpoint, as in the example below.

{
"zippedPNGs": {
"status": "failed",
"message": "skipped"
},
"originalFile": {
"status": "processed",
"message": "ok"
},
"filteredGeojson": {
"status": "failed",
"message": "skipped"
},
"propertiesPNGs": {
"status": "failed",
"message": "skipped"
},
"summary": {
"status": "failed",
"message": "skipped"
},
"rawGeojson": {
"status": "processed",
"message": "ok"
},
"standardGeojson": {
"status": "failed",
"message": "no points passed the filter"
},
"units": {
"status": "processed",
"message": "ok"
}
}

The outermost key indicates the conversion step at which the file passed. The possible status are:

  • processed: the step worked well.
  • failed: the process failed at the current step.
  • skipped: the step was skipped because a failure occurred before or a configuration prevents it from being executed.

More information is available in the message property and here are the most common messages:

MessageDetails
no points passed the filterNo points remained after the cleaning process of points that did not meet the criteria of valid points. This process can be enabled/disabled in the cleanupStandardGeojson configuration.
unsupported operation type: {type}The operation type extracted from the file does not fit into any of the types supported by Leaf: tillage, planted, applied, or harvested. Examples of not supported types: datacollection, guidance, unknown.
missing required properties: {properties}Indicates that one or more required properties from the Leaf standard format were not identified in the file. The message lists the missing properties.
No operation files found after conversionNo valid operation files found in the file
unsupported crop: {crop name}The crop name is not mapped on the Leaf side yet