Leaf’s mission is to empower Food and Agriculture Developers by providing easy access to agriculture data and services. Leaf’s Machine Data API allows developers to access aggregated and standardized Machinery data from any Machine brand.
Leaf can translate proprietary operation files to a standardized, consistent geojson format and here in our blog we have already described how to authenticate a user with John Deere and ClimateField View to retrieve these files and other useful information like standardized growers, farms, and fields from those accounts.
This post will explain operation file merging — an important feature related to both boundaries and machinery data. A single operation is often separated into many different files during data collection and for many use cases developers and users only care about summary data and from single, full operations.
This problem is even more challenging when an operation is executed by multiple machines, from potentially different brands. In this case, the data is locked in different and incompatible file formats (e.g., .YLD for AgLeader vs. .cn1 for CNHi). Each format has different schemas (e.g., one provider may call a measurement “speed”, while the other will call it vehicleSpeed or vrSpeed ), different units, and they will be available in different dashboards.
Leaf currently supports two options for merging operation files. One is an endpoint where you can specify the ids of files that you want to merge, and the second is an auto-merge feature where Leaf will group and merge files based on a series of filters.
Merge endpoint
A merge operation is performed asynchronously. This call will return immediately with the newly created file entry, but at this point, the resulting merged file is still processing and not yet available. You will have to make a new GET /files request for the new id and check the status. A status value of “processed” means the file is done merging.
The merge process has some rules: the files processed must belong to the same leafUserId, the files must be of the same operation type, and the files must have a “processed” status. If any of those filters fail, the endpoint will result in HTTP 400 error.
Automerge
The automerge feature automatically identifies files that belongs to the same operation and merges them into a new file. The automerge will run once a day. The following rules are necessary for the files to be merged:
- The files must to be related to the same field
- The files must have the same operation type (harvested, applied or planted)
- The files must be of the same crop(s)
- The files must contain operations within a given time frame
Merge and automerge can be used on files from 3rd party API’s or files that have been uploaded. Please note that for uploaded files to automerge, they must intersect with a field boundary (boundary can be uploaded or imported via API). Files can be manually merged without a boundary.
Learn more about file upload here.
How to query for merged or automerged files
The easiest way to get the files registered in our API is the endpoint /files. It will return a paged list of files that belong to leafUsers associated with the Leaf API account being used. It is possible to filter the results by passing query parameters, such as provider and origin. In order to differentiate between the other files in our platform, for merge and automerged files the parameter origin will be merged and automerged, respectively. The complete list of filters and accepted values can be found in our documentation.
Both merged and automerged files will result in merged standardGeoJSON, summary, and images. These results will contain the points of all the source files included in the merge operation.
Moreover, the response of a merged or an automerged, will contain the id of the source files used to create the new file, for instance:
Conclusions
Leaf’s mission is to empower Food and Agriculture Developers by providing easy access to agriculture data and services. Leaf provides a unified farm data API to help developers import, export, aggregate, analyze, display, and organize data from any source. With features like automerge, we help developers focus all of their energy and time on creating value for their users, not managing and maintaining integrations, incompatible file formats, competing standards, inconsistent field boundaries, syntax, units, and other complications.
This Postman collection was created to help you understand and get started with our API.
We are constantly developing our models and facilitating the access. For further details, or if you have any questions, contact us via help@withleaf.io.
