Merging fields

Merging fields means replacing them with one field that has a boundary encompassing these fields which, in turn, implies registering a new field that replaces the ones to be merged. For this reason, in GFID system, the merge operation is not supported via an “ad hoc” endpoint but rather via the well-known POST /fields endpoint used to register new fields in the system.

So, if a client application wants to merge fields, it will call the POST /fields endpoint with the “merged geometry” in input and “autoreplace“ set to true, thus forcing the existing fields to be set to expire and replacing them with just one field having the geometry provided in input. For a review of how field creation works, please refer to this page.

It is the clients responsibility to ensure that the input boundary is a good representation of the fields to merge, indeed GFID system will not apply any validation on if and how the input boundary is overlapping with the fields in the system.

Prerequisites

Please note: write access to the API is available on request. Creating and updating fields is intended only for client applications with end users, who are able to confirm the validity and suitability of input data as a canonical field boundary. Before granting access we will discuss with you how to ensure your users understand the implications of updating the Global FieldID map of fields. We will also assign you a unique source name to be used in input to the write endpoints.

How to merge fields

Below is the list of optional and mandatory steps to accomplish the merge of fields.

Optional step: Call the GET /merged-geometry endpoint to generate the “merged geometry“

Let’s say that you want to merge some fields but you do not have the geometry for the “merged field”. To assist you, we have created a utilities endpoint GET /merged-geometry that accepts in input a list of boundary IDs (up to a maximum of 10) and returns the geometry resulting from the merge of the boundary geometries in input.

Behind the scene this endpoint uses PostGIS’s ST_ConcaveHull algorithm to merge the polygons. Please see below some images showing the “merged geometry“ for different input polygons.

This is just one of the many algorithms to merge polygons and the geometry in output may be different from what you expect. In this case please edit the geometry before using it in input to the POST /fields endpoint, you are ultimately responsible for the registration of the expected field.

Steps to obtain the “merged geometry“ via GET /merged-geometry endpoint:

1. Look up the fields IDs you want to merge;

2. Obtain the IDs of the representative boundaries of each one of the fields to merge by calling GET /boundaries?field_relationships.field_id=123A.BCDE,2C456F.GHIL,...;

3. Call the GET/ merged-geometry?boundary_ids=<UUID_1>,<UUID_2>,... to obtain the “merged geometry“;

4. Double check that the “merged geometry“ is the expected one or amend it as needed, remember you are ultimately responsible to register the right field.

Mandatory step: Call the POST /fields endpoint to merge the fields

Call the POST /fields endpoint specifying the “merged geometry“ as geometry for the field boundary and setting “autoreplace” to true.

The API will try to invalidate all the fields overlapping with the geometry in input and this operation is atomic, meaning that if any of the fields fail to be invalidated (for whatever reason), then no further steps will be undertaken and an error will be returned.

If invalidating all the overlapped fields is achieved successfully, the input field needs to pass all the validations required for a valid field i.e. the area of the field needs to be within the range.

In case of any error during the process, the execution is stopped and the error is returned. Otherwise the new field is successfully created and assigned a brand new FieldID (none of the IDs of the merged field is re-used).