Field creation and update

The POST /fields endpoint enables client applications to create fields in the GFID system.

Field creation and update

The POST /fields endpoint enables client applications to create fields in the GFID system.

Using this endpoint, client applications can enable users to create a FieldID for their own fields by providing a geometry, even if the system does not yet already have IDs for other fields in that country. By doing so, users receive a canonical ID, in exchange for specifying its geometry. The new/updated geometry is made available to all FieldID users.

Currently, the system works in areas where no existing ID exists, either to fill in gaps or generate IDs for fields in countries where we have not yet pre-loaded data. As such, fields must not overlap with existing fields: the API enforces this constraint.

For convenience, an ‘autoedit’ option, which can make minor edits to the boundary to make sure it ‘fits’ has been introduced along with an ‘autoreplace’ option to enable replacing fields with new IDs, overwriting existing fields on the map.

Other endpoints also support changing the boundary of the field or removing fields from the map, enabling a full range of editing capabilities.

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.

Input

The API accepts an input payload in JSON format.

The JSON should contain the following data:

  • A GeoJSON feature under the “active boundary” key, which represents the “boundary according to the source”. This object matches the input payload to POST /boundaries endpoint. It contains:

    • The unique identifier or ID that has been assigned to the boundary by the source. Please note that Varda do not use this ID when creating either a Boundary ID or Field ID;

    • Source-defined properties. Only number, string, boolean and null are supported. They will be stored along with the other provided data;

    • The geometry of the boundary. Two types are supported, Polygon and MultiPolygon;

    • Varda-defined optional metadata;

    • Varda-defined mandatory metadata:

      • Source name: it is a unique name used to indicate the source of the data. Creation of a source for your boundaries can be done upon request;
  • Optional field metadata:

    • Name and description of the field;

    • “effective_from”: this is the date from which the field is active. If empty, the default value is now. Creation of fields is supported even when setting an “effective_from” date in the past, or in the future. By default the field will be considered active indefinitely;

    • “autoedit“: boolean parameter that allows you to specify whether the system, in case of overlaps with existing field boundaries, can modify your input geometry to make it fitting into the “Varda default layer of field boundaries.” For further details, please refer to the section below. The default value is false.

    • “autoreplace“: boolean parameter that enables you to specify whether the system should set to expire the existing field boundaries that would otherwise overlap with the field boundary about to be created, thus causing the creation process to fail. The default value is false.

Output

The API will return:

  • “global_field_ID“: the Global Field ID assigned to the newly created field;

  • “active_boundary_ID“: the Global Boundary ID of the active boundary of the field. It may be empty if the field is not currently active;

  • “created_at“: the date when the field got created in the system;

  • “effective_from”: the date from which the field is active;

  • “effective_to“: the date until which the field is active;

  • “boundaries“: the list of boundaries of the field. The list contains at least one boundary or even multiple if the field is represented by different boundaries along its time range of validity.

How the logic for field creation works

The API will carry out a number of checks, before creating both a boundary (if one doesn’t exist already for the input geometry) and a field.

Basic checks and corrections are performed to ensure that the input geometry is a valid.

After this, the geometry of the input boundary i.e., the “boundary according to the source”, is checked against surrounding field boundaries to identify and quantify possible overlaps and ensure that the creation of the new field does not violate the “zero-overlaps” constraint of the “Varda default layer of field boundaries”:

  • If the input boundary geometry does not overlap with any of the surrounding fields, the creation of the field will be successful;

  • If the input boundary geometry overlaps with any of the surrounding fields, the outcome (success or failure) of the field creation depends on the extent of overlap(s) - if they are above or below threshold -and on the input values of the “autoreplace” and “autoedit” parameters. The below table describes all the possible scenarios:

Input values Outcome
Autoreplace value Autoedit value Overlap extent Result of the field creation Endpoint logic
false false above threshold Failure Overlap cannot be corrected.
below threshold
true above threshold
below threshold Success Overlap can be corrected by cutting out, from the input geometry, the parts causing the overlap.
true false above threshold Success - If the overlapped fields are up to 20, they will be set to expire (regardless of the overlap size); - If the overlapped fields are more than 20, an error is returned “Can’t invalidate more than 20 fields at once. To proceed with your change please contact our support team“
below threshold
true above threshold
below threshold Success - If the overlapped fields are more than 20, an error is returned “Can’t invalidate more than 20 fields at once. To proceed with your change please contact our support team“ - If the overlapped fields are up to 20, the input geometry will be cut around the small-overlap fields, and the fields that are overlapped above threshold will be set to expire i.e. autoedit takes precedence to invalidate the lower possible number of fields.

In case of success:

  • A “boundary according to Varda” is created and assigned a Global Boundary ID. The geometry of this boundary is either exactly what the client provided in input or the modified version of it to make it overlap-free;

  • The “boundary according to the source”, as provided in input with its untouched geometry, is stored as a boundary reference and linked to the “boundary according to Varda”. This linkage allows to keep track of the fact that the “boundary according to Varda” exists also in the source premises. Except for the Varda-defined mandatory metadata, all the input data representing the “boundary according to the source” will be stored in GFID system as part of the “boundary according to Varda“;

  • A field is created and assigned a Global Field ID;

  • Field and “boundary according to Varda” are linked and their relationship is set to start from the “effective_to“ date defined in input and to last until infinity;

In case of failure:

  • The endpoint returns an error that explains why the creation of the field was unsuccessful.

Additional considerations for a successful creation of a field

As mentioned, the creation of fields is supported even when setting an “effective_from” date in the past or in the future. Indeed, the above-described logic to check overlaps is applied considering the overlaps that the input boundary has with the fields existing from the time when the new field would start to be active. Timeline rules for a successful creation of a field are the following:

  • “Past can’t be updated but can be created from scratch“

    • if the effective_from date of the input field is in the past (before now) and ahead of the effective_from date of another field existing in the same area, then the creation of the field will fail even when “autoreplace” is set to true;

      global_field_id_creation_1

      While, if there is nothing ahead of field about to be created, the creation will be successful.

      global_field_id_creation_2

  • “Present/future can be updated“

    • if the effective_from date of the input field is now or in the future and the existing field has an active boundary, then the active field will be trimmed and set to expire by the effective_from date while the new field will have validity starting from the effective_from till infinity. global_field_id_creation_3

      This also implies that any existing field that would start to get active after the effective_from date will be set to expire i.e. field C in the picture is deleted.

      global_field_id_creation_4

Contextual considerations

  • The boundary provided as input to this endpoint becomes part of the “default layer of field boundaries”, updating the primary record of the field for all users. The geometry of boundaries used in this way are always made available, and cannot be removed - it is not possible to update or create a field and keep it hidden from other users at the same time. It is therefore important that applications ensure end users are aware of these implications and have the legal right to make the boundary geometry available. Otherwise, we suggest you submit an alternative boundary. In the future; the API will have the functionality to register a standalone boundary, which can be kept “private”, and shared only with specified recipients. This feature will provide an alternative to creating a new field, or updating an existing one;

  • As described in the above section, the input geometry may be subject to automated corrections if it overlaps with surrounding active fields below a certain threshold (while for overlaps above threshold the creation of the field will fail). The corrections are applied to ensure that the “parts“ of the input field causing the overlaps are cut out;

  • As described above; the “autoreplace” feature is considerably powerful, since it can result in the deletion of existing fields. For this reason it is your responsibility to activate it only if you are sure that your “view“ is more accurate than what already existing in the system.