The data pipeline
Data moves through Leaf in a fixed sequence: Providers → Machine files → Conversion → Field operations- Data enters Leaf. Either through a provider connection (John Deere, Climate FieldView, CNHi, Trimble, AgLeader) or through direct file upload. Provider connections sync automatically; uploads are processed on receipt.
-
Machine file conversion. Leaf takes proprietary machine file formats (ISOXML, GEN4, .DAT, etc.) and converts them into a standard canonical format. The converted data is available as either GeoJSON or GeoParquet — same structure, your choice of format. Conversion happens in stages:
- Standard GeoJSON: Cleaned and standardized into Leaf’s common schema. Property names, units, and structure are consistent regardless of source.
- Filtered GeoJSON (optional): Invalid data points removed based on configurable rules. Enabled via configuration.
- Field operation creation. Leaf takes the converted machine files and merges them with field boundaries to produce field operations. A single planting or harvest event might be spread across dozens of machine files from different swath passes. Leaf identifies which files belong together, merges them, and clips them to field boundaries. This produces field operations for planting, harvest, application, and tillage activities.
- Summaries and images. For each machine file and field operation, Leaf generates a summary (averages, min/max, standard deviations for key properties) and optionally produces property map images.
Field operations require field boundaries. Without a boundary, Leaf still converts machine files and produces file summaries, but cannot create field operations. Boundaries can come from a provider or be created manually through the API.
Key terminology
| Term | Definition |
|---|---|
| API owner | Your Leaf account, identified by an email address. Owns all Leaf users beneath it. Use separate API owners for test vs. production. |
| Leaf user | Represents a grower (or region, sub-customer, etc.) under your API owner. Holds provider credentials, fields, machine files, and field operations. Data is isolated per Leaf user. |
| Provider credentials | OAuth2 tokens or API keys attached to a Leaf user that authorize Leaf to pull data from a specific provider (e.g., John Deere, Climate FieldView). |
| Machine file | A raw data file from a provider or direct upload. Contains GPS-tagged point data from field equipment. Leaf converts these into a standard canonical format, accessible as GeoJSON or GeoParquet. |
| Field operation | The merged, boundary-clipped output from one or more machine files. Represents a single activity (planting, harvest, application, tillage) on a specific field. |
| Field boundary | The geographic polygon defining a field. One active boundary per field. Required for creating field operations. |
| Configurations | Settings that control data ingestion, processing, and output. Applied at the API owner level (inherited by all Leaf users) or overridden per Leaf user. |
| Alerts | Webhook notifications triggered by events like new field operations, credential expiration, or boundary changes. |
| Custom data sync | A configuration (customDataSync) that limits Leaf to fetching field metadata only. You then select which fields to fully process. Useful for controlling costs and scope. |
| Magic Link | A hosted web widget you can send to growers. They click it and connect their provider account or upload files, without needing to interact with the API directly. |
Account structure
The hierarchy is: API owner → Leaf users → Fields, Machine files, Field operations. Most implementations use one API owner per environment, with one Leaf user per grower. A Leaf user can be connected to multiple providers but only one credential set per provider. Configurations cascade: settings on the API owner apply to all Leaf users unless a Leaf user has its own override. Configuration changes are not retroactive.What to do next
- Quickstart: Walk through the setup end to end.
- Authentication: Token lifecycle and request examples.
- Configuration: Control how Leaf processes data.