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:
There is a REST resources section if you want to check it out.
This service has the following endpoints available:
| Description | Endpoints |
|---|---|
| Upload a field file | POST /upload |
| Get all uploads | GET /upload |
| Get an upload | GET /upload/{uploadId} |
| Get the upload entries | GET /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*.shxmust 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 fields per upload.
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
- Python
- JavaScript
Response
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:
| Status | Description |
|---|---|
| RECEIVED | Is the default state for every upload created |
| PROCESSED | When all the files included in the upload were processed, and at least one file have status SUCCESS |
| FAILED | The upload did not generated any field boundary with status SUCCESS |
Get all uploads
 GET /upload
Gets all uploads.
Request examples
- cURL
- Python
- JavaScript
Response
The possible status are listed here.
Get an upload
 GET /upload/{uploadId}
Gets an upload by the upload id.
Request examples
- cURL
- Python
- JavaScript
Response
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
- Python
- JavaScript
Response
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.
The possible status for each file is described below:
| Status | Description |
|---|---|
| PROCESSING | The file is processing, it is the initial status |
| CONVERTED | The file was converted but the process hasn't finished yet |
| FINISHED | The file process is finished and the fields were created |
| FAILED | A failure occurred during the file processing |
| PARTIALLY_FINISHED | Some of the fields were not created due to a processing error or invalid registers |