Configurations
Overview
Leaf's system can be heavily customized to pull and process data differently across APIs and Leaf Users. This customization is achieved using Configurations โ settings that control data ingestion, processing, and output formats.
Configurations can be applied to multiple APIs, including field and field boundaries, machine files, and field operations. Some configurations, like organizationDataSync
and customDataSync
, affect all APIs.
info
Configuration changes are not applied retroactively. If you update a configuration and need to reprocess data, you can use the Reprocess Operation endpoint.
Configuration Levels
Configurations can be set at two levels:
- API Owner Level: Every API Owner account starts with a default set of configurations (detailed below). These defaults can be changed, but they cannot be deleted or set to
null
. - Leaf User Level: You can set specific configurations for individual Leaf Users (representing growers, regions, etc.). This allows granular control over how a specific user's data is synchronized or processed.
Inheritance: If a configuration is not explicitly set for a Leaf User, that user automatically inherits the configuration from the API Owner. However, once a configuration is set at the Leaf User level, it will not change even if the API Owner's configuration is subsequently modified.
Available Configurations
Data Synchronization
fieldsAutoSync
Default: true
Enable this setting to have Leaf automatically synchronize field boundary data from your connected providers. If disabled (false
), you must manually trigger synchronization via the Manual Sync endpoint.
operationsAutoSync
Default: true
Enable this setting to have Leaf automatically synchronize operation data from your connected providers.
customDataSync
Default: true
Enable this setting to initially fetch field boundaries in PREVIEW
mode. This avoids fetching full data for all provider fields, allowing you to selectively choose which fields to fetch completely later. For some providers, this also affects fetching associated operation files. When changing this from true
to false
, previously previewed fields can be fully processed using the Manual Sync endpoint.
organizationDataSync
Default: ALL
Control how Leaf syncs data across organizations within a provider account. Set to ALL
to sync data from all organizations. Set to SELECTED_ONLY
to sync only from organizations explicitly marked as SELECTED
via the Organization Sync endpoints.
syncPartnerData
Default: false
Enable (true
) this setting to fetch shared or partner data (e.g., from John Deere Operations Center partnerships or AgLeader shared accounts), provided the necessary permissions are granted. If disabled (false
), Leaf only fetches data from the directly connected account, ignoring shared data even if permissions allow it.
implementsAutoSync
Default: false
Enable this setting to have Leaf automatically synchronize implement data from your connected providers.
machinesAutoSync
Default: false
Enable this setting to have Leaf automatically synchronize machine data from your connected providers.
operatorsAutoSync
Default: false
Enable this setting to have Leaf automatically synchronize operator data from your connected providers.
productsAutoSync
Default: false
Enable this setting to have Leaf automatically fetch input/product data (currently applies to John Deere).
zonesAutoSync
Default: false
Enable this setting to have Leaf automatically synchronize zone data from your connected providers.
Field Boundary Management
automaticFixBoundary
Default: true
Enable this setting to have Leaf automatically attempt to correct invalid field boundary geometries received from providers. See Automatic Geometry Fix for more details.
fieldsAttachIntersection
Default: 0.01
Set the minimum intersection percentage required to link an operation to a field. Leaf links the operation if the intersection area is greater than this value. Enter a value between 0 and 100 (e.g., 1
for 1%, 0.01
for 0.01%). 0.01
represents the smallest possible overlap.
fieldsAutoMerge
Default: false
Enable this setting to have Leaf automatically merge fields that meet the intersection threshold defined by the fieldsMergeIntersection
configuration.
fieldsAutoSync
Default: true
Enable this setting to have Leaf automatically synchronize field boundaries from your connected providers. If set to false
, you must manually trigger synchronization using the sync fields endpoint.
fieldsMergeIntersection
Default: 0.01
Define the minimum intersection percentage required to merge two fields. When fields meet this threshold and fieldsAutoMerge
is enabled, Leaf creates a new field of type MERGED
representing the intersection. The original fields remain inactive for historical reference. Enter a value between 0 and 100 (0.01
is the minimum).
Machine File Conversion
cleanupStandardGeojson
Default: true
Enable this setting to have Leaf automatically remove points marked as invalid (see Valid Points) from the standardGeoJSON
file output.
originalOperationData
Default: true
Enable this setting to include non-standard properties (like original farm name, field name, grower, and operation type provided by the source) in the File summary output. This does not affect the standardGeoJSON
or Field Operation summary outputs.
unitMeasurement
Default: [Your Preferred System]
Choose the unit system (Metric, Imperial, or Default) for summary, standardGeoJSON
, and filteredGeoJSON
outputs in Machine Files and Field Operations. METRIC
and IMPERIAL
convert measurements accordingly. DEFAULT
uses the units provided by the original data source. Using METRIC
or IMPERIAL
ensures consistency across your data. See the Units of Measurement page for specific unit conversions.
enableOutsideFieldGeojson
Default: false
Enable this setting to capture machine file points that fall outside defined field boundaries when splitOperationsByField
is active. Normally, these points are discarded. When enabled, you can retrieve these points using the outsideFieldGeoJSON endpoint. This applies to both Machine File Conversion and Field Operations.
enableGeoparquetOutput
Default: false
Enable this setting to generate vector point file outputs (like standardGeoJSON
) in GeoParquet format in addition to GeoJSON. GeoParquet offers faster processing and reduced storage. This setting applies to data processed after it's enabled (no historical conversion). This applies to both Machine File Conversion and Field Operations.
Field Operations
These configurations can be enabled with the use of Leaf Field Operations. Field Operations require an active boundary to be present so Leaf can merge the machine files with the field boundaries to create Field Operations.
cleanupStandardGeojson
Default: true
Enable this setting to have Leaf automatically remove points marked as invalid from the standardGeoJSON
file output during Field Operation processing. See this section for more information
summarizeByProductEntry
Default: true
Enable this setting to aggregate product application data in the Field Operation summary. Leaf groups entries with the same product name, summing area
and totalApplied
and averaging the rate
. This applies only to application-type operations.
fieldOperationCreation
Default: true
Enable this setting to allow Leaf to automatically create Field Operations by merging relevant machine files associated with an active field boundary.
operationsAutoSync
Default: true
Enable this setting to have Leaf automatically synchronize operation data from your connected providers.
operationsFilteredGeojson
Default: true
Enable this setting to allow filtering of Field Operations data based on various criteria (see Filtered GeoJSON).
operationsRemoveOutliers
Default: true
Enable this setting to remove outlier points from the filteredGeojson
output for harvest operations. Leaf identifies outliers based on harvest volume values falling outside the standard deviation threshold set by operationsOutliersLimit
. Requires operationsFilteredGeojson
to be enabled. See Outliers for more details.
operationsOutliersLimit
Default: 3
Set the standard deviation threshold for identifying outliers when operationsRemoveOutliers
is enabled. For example, the default value 3
removes points where the harvest volume is more than 3 standard deviations from the mean. See Outliers for more details.
operationsMergeRange
Default: 5
days
Define the time window (in days) used to group machine files into a single non-harvest Field Operation. Files within this range for the same field, crop, and operation type are merged.
operationsMergeRangeHarvested
Default: 21
days
Define the time window (in days) used to group machine files into a single harvest Field Operation. Files within this range for the same field and crop are merged.
operationsProcessingRange
Default: [Set as needed]
(Typically 12 months)
Specify the lookback period (in months) for fetching and processing operations data from providers. Leaf will only process operations created or updated within this timeframe.
splitOperationsByField
Default: true
Enable this setting to create separate Field Operations for each distinct Leaf Field Boundary that intersects with the machine data. If disabled, data intersecting multiple boundaries might be combined into a single operation.
splitOperationsByProvider
Default: true
Enable this setting to group machine files by provider in addition to field, operation type, crop, and date when creating Field Operations. If disabled (false
), Leaf merges data from different providers into the same Field Operation if other criteria match.
splitOperationsByTillType
Default: false
Enable this setting to create separate Field Operations for each unique tillType
found within tillage machine data. If disabled, different tillage types might be combined into a single operation.
unitMeasurement
Default: [Your Preferred System]
See this section for more information
enableOutsideFieldGeojson
Default: false
See this section for more information
enableOperationsSession
Default: false
Enables a new view of the field operation data, compiled by operator, implement and machines used in the operation. The information can be accessed in the field operation session endpoint.
Field Operations Image Generation
operationsImageCreation
Default: false
Enable this setting for Leaf to generate Operations Images.
operationsImageAsGeoTiff
Default: false
Enable this setting to allow Leaf to generate the images of operations in GeoTIFF format. The data can be accessed in this endpoint.
operationsImageAttributeCreation
Customize which Operations Images are generated by setting the corresponding attribute flags to true
.
Irrigation
irrigationProcessingRange
Default: 12
months
Specify the lookback period (in months) for fetching and processing irrigation activities from providers. Leaf will only process irrigation data that occurred within this timeframe.