The POST /field-searches endpoint enables client applications to “lookup” IDs for fields using either a point anywhere within the field or a boundary.
The API accepts as input one of:
The expectation is that clients will lookup the ID(s) of ‘their’ fields by sending either a polygon they already hold, or a coordinate somewhere within it.
The API will return identifiers of matching fields, i.e. fields that overlap with the input location. Included for each match are:
If the search was performed using a boundary, the API also provides metrics to indicate the nature of the match between the submitted boundary and the boundary defining the field:
The match metrics provide an objective way to indicate the likely relationship between the input boundary and the field as defined by the registry. In field data management scenarios, this will commonly be one of:
These relationships can be inferred by considering what the scores mean:
The IoU score is a solid indicator of whether the two areas are the same. A perfect match yields an IoU of 1.0, and high IoU means that the other two scores are also high.
Rarely will two polygons be a perfect match. Differences around the edges of the field are common and the method of deriving the polygon is not always accurate. An 80% agreement (IoU 0.8) indicates that it’s reasonable to infer that the input polygon represents the same field.
A high ‘input’ intersection indicates that the input is within the field, and hence it’s probably safe to infer that it’s the same field, albeit representing only a part of it. The reverse intersection score tells you how large a part. Boundaries wholly within the field have a perfect 1.0 score.
A high ‘output’ intersection indicates that the input contains the field, and likely represents multiple fields.
Whilst the metrics above give an indication of the likely relationship between the input boundary and the ‘canonical’ field, it is important to consider where the boundary you are trying to match came from.
For example, boundaries that are derived from GPS data reported by a machine carrying out a harvest or input application operation will rarely produce perfect 1:1 alignment. The match will depend on sensor calibration, whether the field boundary includes or excludes field margins/obstacles, whether the data recording began and ended within the field etc. Thus a healthy tolerance should always be applied. It is also common for operations spanning only part of a field (e.g. multiple machines in the same field), as well as operations that may span multiple fields (e.g. adjacent fields with the same crop).
On the other hand, if the boundary you have is supposed to represent a grower’s view of a whole field, a reasonably high IoU might be expected and so large deviations indicating one is only a small part of the other suggest a possible data discrepancy.
To give another example, Land Parcel Identification Systems used in the administration of the EU’s CAP subsidies can use different types of land parcel. Some use a similar concept of a ‘field’ typically used by growers in how they manage the land (semi-permanent, single crop), meaning a reasonably high IoU should be expected. Yet some (e.g. the UK Rural Payments Agency) require land to be separated by a physical boundary, meaning a match to multiple Field IDs would be uncommon, but ‘normal’.