Global FieldID Lookups

Input

The API accepts as input one of:

• A GeoJSON Point (latitude/longitude)
• A GeoJSON Polygon or MultiPolygon
• A GeoJSON Feature containing either of the above

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.

Output

The API will return identifiers of matching fields, i.e. fields that overlap with the input location. Included for each match are:

1. The Global FieldID
2. The Global BoundaryID of the currently active boundary used to define the field's spatial extent

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:

1. The proportion of the input geometry area that intersects with the output
2. The proportion of the output geometry area that intersects with the input
3. The intersection-over-union (IoU), which is the intersection area divided by the union area of the two polygons.

How to interpret match metrics

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:

1. The input geometry represents a single field
2. The input geometry represents a part of a field (e.g. multiple combines operating in the same field will each produce a smaller polygon)
3. The input geometry represents multiple fields (e.g. a single operation covering adjacent fields with the same crop)
4. Some combination of 2 and 3 (e.g. half of one field and a third of the adjacent field)

These relationships can be inferred by considering what the scores mean:

• Any part of the input polygon that is outside the field will lower the input intersection (the input extends outside the field)
• Any part of the field not included in the input will lower the output intersection (the input doesn't cover the whole field)
• Either of these will lower the IoU

High IoU

The IoU score is a solid indicator of whether the two areas are the same. A perfect match gives an IoU of 1.0, and high IoU means that the other two scores are also high.

Two polygons will rarely 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 say that the input polygon represents the same field.

High input intersection

A high 'input' intersection indicates that the input is within the field, and hence it's probably safe to conclude that it's the same field, but representing only a part of it. The reverse intersection score tells you how large a part. Boundaries completely within the field have a perfect 1.0 IoU score.

High target intersection

A high 'output' intersection indicates that the input contains the field, and likely represents multiple fields.

Contextual considerations

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 flexible margin of error 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 the IoU will probably be high and so large deviations indicating one is only a small part of the other, might mean that there is a 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'.