Leaf’s mission is to empower Food and Agriculture Developers by making agriculture data easy to access and use. Querying data by Field is a frequent necessity in AgTech products, but field names, boundaries, and registries are often inconsistent across applications and providers. This is an important problem in AgTech since without a consistent field entity it’s impossible to know if data from different sources relate to the same field.
Leaf solves this problem by matching field geometry across applications and mapping Field names, geometry, and season to a consistent, Merged Field ID. This allows Food and Agriculture Developers to easily and automatically query data from any source with a single, consistent Field ID.
To illustrate this problem and Leaf’s solution, the below image shows the same field in the Operations Center of John Deere, Climate FieldView, and Trimble entered with different methods and merged into a unified Field ID.
Terms and Actors
The following actors are present in the Leaf’s machine data integration API:
- Data provider: a machine or machine monitor manufacturer that generates the machine data. In most cases, the Data provider also has an FMIS specialized in their data.
- Data provider API: the source (normally an API) that serves as a gateway to the Data provider data.
- AgTech developer: the developer or the team of developers that are using Leaf’s API to access data from Data Providers.
- End user: In most cases a farmer or a consultant who will be using AgTech applications.
- FMIS: Farm Management Information System. An ERP-like application that farmers and consultants use to organize farm data.
- LeafUser: Leaf’s API uses an abstraction called Leaf User to store credentials and organize data for each individual data owner. In most cases, the Leaf User will be the farmer or consultant that has access to the source data inside the machinery company’s FMIS (e.g. John Deere Operations Center or Climate Field View platform). To create a Leaf User, we can use this guide.
Working with Users and Fields in Leaf:
The data organization for each Leaf User in the Leaf’s API is structured in:
- Grower
- Farm
- Field
- Season
After we create a Leaf User, there are multiple ways we can add and manage Grower/Farm/Field/Season data for each Leaf User:
- Programmatic entry: you can create and add these entities programmatically from an existing user list or new registration.
- Import: you can import these entities from any source connected to Leaf with your user’s authorization.
- Merge: you can merge entities into a consistent, single entity across data sources for simplified management and reference.
We will go into detail and show examples of each method below.
Programmatic entry
To insert a Field into Leaf’s API, we use a MultiPolygon, as described in the GeoJSON standard. This field can be named with the key externalId, where the user can add any unique string to label the field to match their internal field name or reference.
The field structure uses Grower, Farm, Field, and Season entities.
Import
Leaf’s API can easily import fields from any source. To do so, we must first have the User authenticate access with the import source or data provider. For example, Leaf’s API can be initiated with Climate FieldView credentials in order to import field boundaries from Climate FieldView. The following information needs to be included in the initialization request:
To add this data:
- Add the credentials to Leaf API.
- Create the Leaf User
- The documentation explaining how to add the other credentials can be found here
Merging
For every new field received in Leaf’s API via programmatic entry or import, Leaf will detect if any already registered fields are in the same area of the new field. If so, we create or add this field to a new field type: MERGED.
A Merged Field is a single field that references the same field across multiple providers regardless of name, syntax, or polygon inconsistencies. To represent the Merged Field, Leaf uses a new ID and polygon that is the sum of all the polygons of the fields. The Merged Field also includes a list of the individual field IDs and sources included in the Merged Field.
Querying fields
The fields can be queried using the following parameters:
- ExternalId
- Get all fields
- Filtering by Provider
- Geographically
Querying the externalId is the simplest way to get information about only one field. For instance, if we issue the GET request:
The response will be: