The field upload service creates field boundaries from spatial files. Instead of creating fields one at a time via the API, you can upload a zip file containing shapefiles, GeoJSON, or KML and Leaf creates all the fields at once.
Upload a .zip file containing one or more of:
- Shapefile — Must include at least
.shp, .dbf, and .shx files.
- GeoJSON — Standard GeoJSON with Polygon or MultiPolygon geometries.
- KML/KMZ — Google Earth format.
The zip can contain multiple files in different formats. Leaf detects and processes each valid file independently. Nested directory structures inside the zip are fine.
If a file includes a property or column called name, Leaf uses it as the field name.
All geometries are projected to WGS 84 (EPSG:4326).
Limits
- Maximum file size: 3 GB
- Maximum fields per upload: 100
Uploading a file
POST /services/uploadservice/api/upload?leafUserId={leafUserId}
Send the file as multipart/form-data. The leafUserId parameter is required. You can optionally pass farmId to assign all created fields to a specific farm.
The response includes an upload id you use to track progress.
Tracking upload status
GET /services/uploadservice/api/upload/{uploadId}
Getting created fields
GET /services/uploadservice/api/upload/{uploadId}/entries
Returns the processing result for each file in the zip. Each entry includes:
fieldId — Array of field IDs created from that file.
converterFormat — Detected format: SHAPEFILE, GEOJSON, or KML.
status — Per-file status: PROCESSING, CONVERTED, FINISHED, FAILED, or PARTIALLY_FINISHED.
createFieldErrorDetails — Error messages for any fields that failed to create (e.g., self-intersecting geometry).
Use the field IDs from the entries response to fetch full field details via GET /services/fields/api/users/{leafUserId}/fields/{fieldId}.
What to do next
Last modified on March 24, 2026