The Global FieldID API enables applications to integrate with the Global FieldID System.
The Global FieldID API provides a number of functions:
| Function | Description |
|---|---|
| FieldID Lookup | The POST /field-searches endpoint is used to obtain the Global FieldID for a given point or boundary shape, enabling third party applications to annotate their fields with the global ID. See the FieldID Lookups page for further information. |
| Resolve a Field | The GET /fields/{FieldID} endpoint is used to fetch a field object by its global ID. The object includes the ID of the boundary that defines the field’s spatial extent. |
| Resolve a Boundary | The GET /boundaries/{BoundaryID} endpoint is used to fetch a boundary object by its ID. The returned GeoJSON object includes the boundary’s geometry and spatial properties. |
| Field boundary history | The GET /fields/{FieldID}/boundaries endpoint is used to filter and fetch the boundaries associated with a given field over time (namely those used to define its spatial extent). |
| Boundary download | The GET /boundaries endpoint is used to fetch a collection of one or more boundaries. The collection can be filtered using a combination of spatial intersection (e.g. bounding box or point) or metadata properties (e.g. a list of IDs and types). |
| Resolve a boundary reference | The GET /boundary-references/{ref-id} endpoint is used to fetch metadata about a boundary according to a specific system, using Varda’s unique ID. |
| Lookup boundary references | The GET /boundary-references endpoint is used to query for external IDs of boundaries registered in the system. This enables FieldID to be used as a cross-referencing system for spatial data. |
| Create a FieldID | The POST /fields endpoint is used to create a new field within the ‘shared’ map of fields using a boundary geometry. It can also be used to replace an existing field with a new ID when significant changes are made. See the Creating fields page. |
| Update a FieldID | The PATCH /fields/{FieldID} endpoint is used to update a field with a ‘better’ boundary whilst retaining the same Global FieldID. See Boundary replacement for details. |
| Retire a FieldID | The DELETE /fields/{FieldID} endpoint is used to retire a field, removing it from the map whilst retaining its history. See the Retiring a field page for details. |
| Create a BoundaryID | The POST /boundaries endpoint is used to register a boundary geometry and obtain a canonical ID. It can be used for any boundary, not only a canonical field boundary. See the Custom shapes page. |
| Modify boundary permissions | The /boundary-references/{id}/permissions endpoint is used to control a private boundary’s discoverability and access by other users. See updating permissions for details. |
The API is designed to be integrated into applications with a wide range of scenarios including machine-to-machine scenarios where an end user is not necessarily present. The API uses the OAuth 2.0 client credentials flow to authenticate requests.
To access the API you can create a set of client credentials in our account hub. You will be asked to sign in, or create a user account. See the Requesting Access Tokens page for more details of how to use the credentials to obtain an access token for the API.
Note that initially the account hub only supports individual developer accounts; we intend to enable organisation management in a future update. For quality-control reasons new accounts are also initially limited to standard read only access with default rate limits - please contact us if you would like to register your own boundaries or enable your users to update and create fields.
We are continuously improving the system; here are some recently introduced enhancements:
We have now made it possible for individual developers to register and create application credentials directly through the web interface, enabling them to start using the API immediately.
We have now made available monthy exports of current field boundaries (i.e. the primary active boundary of each field in the system). These are broken down by country and published in our download hub.
The first phase of the FieldID system exposed IDs for fields managed by Varda from, using a combination of public data (where available) and earth observation to delineate fields in specific countries. This enabled agri-tech applications to ‘lookup’ a canonical ID for fields they already hold, as well as enable growers to import fields.
However, the FieldID system also allows third-party applications to create and update fields on behalf of their users, transforming the FieldID system into a read-write open ledger so that growers can obtain a FieldID for all of their fields no matter where they are, and participate in ensuring their fields are accurately represented in the system.
The system allows fields to be:
Some of this functionality is demonstrated in our standalone free user interface.
Note that write access to the API is made available on request; in particular creating fields should only be done in specific scenarios to ensure data quality is maintained. Please contact us if you believe your application can help growers and advisors to claim their fields and actively participate in updating the map.
In addition to updating and creating field boundaries, we also expose the capability to register alternative boundaries representing any arbitrary area of land related to the field, without changing the definition of the field itself. This is useful when it is necessary to obtain a common Global BoundaryID for a specific area of land that should not change.
Examples include:
Whereas a FieldIDs is intended to uniquely identify a field consistently for all users and therefore requires a public boundary that does not overlap with another field, a boundary: 1. Can be any shape, size and location - the only restriction is that it must be syntactically valid. 2. Can be kept private, with access to the geometry and metadata by other users managed via permissions.
A major aim of the Global FieldID system is to deduplicate fields and boundaries across multiple systems and users by providing a globally unique common identifier, along with a geometry. A BoundaryID deduplicates references from multiple systems/users to the same area of land. However, sometimes a use case requires to work with one specific instance of a boundary, according to the application that registered it. Each time the ‘same’ boundary is registered, we identify each instance separately as a boundary reference.
We now expose these objects in the API, including the source-specific metadata and any ‘local’ identifier. This allows the service to be used as a cross-referencing system, to map back and forth between existing global and local identifiers, such as those issued by national governments or software platforms.
In addition to the currently implemented API functions, a number of improvements are planned, including:
We know that a RESTful API is not always ideal for accessing and submitting data, especially those where larger volumes of data are involved such as during initial setup of an integration with Global FieldID, or automating the process of registering whole datasets of boundaries. We use a semi-manual process to manage this at present (please contact us for details).
We therefore plan to expose the facility we use internally to manage bulk operations to developers in a self-service API.
Many of our users are large organisations who have multiple applications and developers; organisations (or ‘tenants’) are also a core part of how access to private boundaries is managed.
We therefore plan to extend the self-service account management to support managing organisations and their shared credentials.
We plan to expand the range of data that can be downloaded in bulk, firstly to cover other types of boundary (not only the primary active boundary of each field) but also potentially custom downloads including private boundaries a user may have access to.
The REST API’s facility for downloading boundaries in GeoJSON format is intended for lookups of individual fields or small areas, and therefore applies an area limit.
Our user interface on the other hand shows boundaries in much wider areas, for which we index the boundary data as Mapbox vector tiles. Other users who may also wish to implement similar user interfaces could benefit from access to a similar functionality.
We plan to expose origin and taxonomy metadata, providing information about how boundaries were sourced and the method used to generate them.
Internally we use an event-driven architecture to power the data ingestion and data preparation pipelines, as well as maintain an audit log. Exposing this functionality as an Async API would enable developers to create applications that are notified when fields are changed, maintain up-to-date copies of the FieldID data, and even implement their own read replica.