Upload Field Boundary Endpoints

About

This file upload service allows the creation of field boundaries from uploaded field files. It currently supports creating field boundaries using polygon and multi-polygon geometries from zip files that contain shapefiles, GeoJSON, or KML files. To call them easily, we recommend using Leaf's Postman collection.

All HTTP methods should be prepended by this service's endpoint:

https://api.withleaf.io/services/uploadservice/api

There is a REST resources section if you want to check it out.

This service has the following endpoints available:

DescriptionEndpoints
Upload a field filePOST /upload
Get all uploadsGET /upload
Get an uploadGET /upload/{uploadId}
Get the upload entriesGET /upload/{uploadId}/entries

Upload endpoints

Upload a field file

 POST /upload

Creates field boundaries in Leaf from files. The file must be sent as a zip.

It supports polygons and multi-polygons from the following spatial formats:

  • Shapefile (minimum *.shp, *.dbf, and *.shx must be present)
  • GeoJSON
  • KML/KMZ

This endpoint accepts a .zip of multilevel files, detects the valid files from the .zip, and returns the ID of the upload, which can be used to retrieve the ID's of the fields created/processed in the entries endpoint.

Limitations

Currently, our upload endpoints accepts files with the maximum size limited to 3 gigabytes and with up to 100 registers/fields.

This endpoint requires the leafUserId parameter and it also accepts the optional farmId parameter, which supports any existent Leaf farm ID and if present, all valid fields will be created under the informed farm.

Leaf will project all the geometries to WGS 84 (EPSG:4326). If there is a property/column called name available in the file, Leaf API will use it as the field name property.

Request examples

curl -X POST \
-H 'Authorization: Bearer YOUR_TOKEN' \
-F 'file=shapefile.zip' \
'https://api.withleaf.io/services/uploadservice/api/upload?' \
'leafUserId={leafUserId}'

Response

{
"id": "uuid",
"leafUserId": "uuid",
"originalFileUrl": "url",
"fileName": "shapefile.zip",
"status": "RECEIVED",
"createdTime": "yyyy-MM-dd'T'HH:mm:ss.SSSSSS'Z'"
}

The upload ID returned as id can be used to retrieve on Get an upload the updated status and individual processed fields IDs.

Upload status

The possible status are:

StatusDescription
RECEIVEDIs the default state for every upload created
PROCESSEDWhen all the files included in the upload were processed, and at least one file have status SUCCESS
FAILEDThe upload did not generated any field boundary with status SUCCESS

Get all uploads

 GET /upload

Gets all uploads.

Request examples

curl -X GET \
-H 'Authorization: Bearer YOUR_TOKEN' \
'https://api.withleaf.io/services/uploadservice/api/upload'

Response

[
{
"id": "uuid",
"leafUserId": "uuid",
"originalFileUrl": "url",
"fileName": "file.zip",
"status": "PROCESSED",
"createdTime": "yyyy-MM-dd'T'HH:mm:ss.SSSSSS'Z'"
},
{
"id": "uuid",
"leafUserId": "uuid",
"originalFileUrl": "url",
"fileName": "shapefile.zip",
"status": "RECEIVED",
"createdTime": "yyyy-MM-dd'T'HH:mm:ss.SSSSSS'Z'"
}
]

The possible status are listed here.

Get an upload

 GET /upload/{uploadId}

Gets an upload by the upload id.

Request examples

curl -X GET \
-H 'Authorization: Bearer YOUR_TOKEN' \
'https://api.withleaf.io/services/uploadservice/api/upload/{uploadId}'

Response

{
"id": "uuid",
"leafUserId": "uuid",
"originalFileUrl": "url",
"fileName": "shapefile.zip",
"status": "PROCESSED",
"createdTime": "yyyy-MM-dd'T'HH:mm:ss.SSSSSS'Z'"
}

The possible status are listed here.

Get the upload entries

 GET /upload/{uploadId}/entries

Returns the result of each file identified as compatible in the processing.

Request examples

curl -X GET \
-H 'Authorization: Bearer YOUR_TOKEN' \
'https://api.withleaf.io/services/uploadservice/api/upload/{uploadId}/entries'

Response

[
{
"id": "uuid",
"fieldId": [
"uuid",
"uuid"
],
"converterFormat": "GEOJSON",
"originalFileUrl": "url",
"leafUserId": "uuid",
"uploadId": "uuid",
"status": "FINISHED",
"createFieldErrorDetails": [],
"createdTime": "yyyy-MM-dd'T'HH:mm:ss.SSSSSS'Z'",
"processedTime": "yyyy-MM-dd'T'HH:mm:ss.SSSSSS'Z'"
},
{
"id": "uuid",
"fieldId": [
"uuid",
"uuid",
"uuid"
],
"converterFormat": "SHAPEFILE",
"originalFileUrl": "url",
"leafUserId": "uuid",
"uploadId": "uuid",
"status": "FINISHED",
"createFieldErrorDetails": [],
"createdTime": "yyyy-MM-dd'T'HH:mm:ss.SSSSSS'Z'",
"processedTime": "yyyy-MM-dd'T'HH:mm:ss.SSSSSS'Z'"
},
{
"id": "uuid",
"fieldId": [
"uuid"
],
"converterFormat": "KML",
"originalFileUrl": "url",
"leafUserId": "uuid",
"uploadId": "uuid",
"status": "FINISHED",
"createFieldErrorDetails": [],
"createdTime": "yyyy-MM-dd'T'HH:mm:ss.SSSSSS'Z'",
"processedTime": "yyyy-MM-dd'T'HH:mm:ss.SSSSSS'Z'"
}
]

The entries response has the list of the fields created for each recognized file, it can be fetched in the fieldId property. More information about the created fields can be fetched using the ID in the Get a field endpoint.

The converterFormat will show the identified format: SHAPEFILE, GEOJSON, or KML.

If an error occurs for any entry in the file it will be showed in the createFieldErrorDetails array.

[
{
"id": "uuid",
"fieldId": [
"uuid",
"uuid"
],
"converterFormat": "GEOJSON",
"originalFileUrl": "url",
"leafUserId": "uuid",
"uploadId": "uuid",
"status": "PARTIALLY_FINISHED",
"createFieldErrorDetails": [
"{\"type\":\"https://www.jhipster.tech/problem/problem-with-message\",\"title\":\"Invalid geometry: Self-intersection at POINT (-39.86283923292457 -18.46470271875014)\",\"status\":400,\"path\":\"/api/system/users/bfa69ef7-7577-4902-9e93-890e2878e1fc/createField\",\"message\":\"Invalid geometry: Self-intersection at POINT (-39.86283923292457 -18.46470271875014)\",\"errorKey\":\"invalidGeometry\"}"
],
"createdTime": "yyyy-MM-dd'T'HH:mm:ss.SSSSSS'Z'",
"processedTime": "yyyy-MM-dd'T'HH:mm:ss.SSSSSS'Z'"
}
]

The possible status for each file is described below:

StatusDescription
PROCESSINGThe file is processing, it is the initial status
CONVERTEDThe file was converted but the process hasn't finished yet
FINISHEDThe file process is finished and the fields were created
FAILEDA failure occurred during the file processing
PARTIALLY_FINISHEDSome of the fields were not created due to a processing error or invalid registers