The Field ID API enables applications to integrate with the Global FieldID System.
The Global FieldID® REST API provides a number of functions:
| Function | Description |
|---|---|
| Field ID 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 Field ID 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). |
| Create a Field ID | The POST /fields endpoint is used to create a new field using a boundary geometry, where none already exists. It can also be used to replace an existing field with a new ID when significant changes are made. |
| 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. |
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 our team will need to create credentials for you. The Requesting Access Tokens page has more details of how to use the credentials to obtain an access token for the API.
We are continuously improving the system; here are some recently introduced enhancements:
We have recently released the first version of our user interface, a free web application for growers to lookup IDs for their fields. Currently it works in the UK, France, Netherlands and Brazil.
Over time we intend to extend the UI to include the ability to update the map, as well as explore other data held by the system (e.g. other boundaries, historical data).
The API has been enhanced to allow authorized client applications can create their own IDs where the system does not already have one. As well as fill in any gaps, this means the Global Field ID system can be used to create field IDs even in countries where Varda has not yet pre-generated them.
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.
A major aim of the Global Field ID system is to deduplicate fields and boundaries across multiple systems and users by providing a globally unique common identifier, along with a geometry. A Boundary ID 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:
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. However an important part of the FieldID system will be the ability for 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 participate in ensuring their fields are accurately represented in the system.
When complete, the system will allow fields to be:
In addition to updating and creating field boundaries, we plan to 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 ID for a specific area of land that should not change
Examples include:
The API can then be used to discover all the boundaries associated with a field, as well as to connect back and forth between different boundaries overlapping the same locations. For example, “what is the FieldID matching the property label from the Brazilian SICAR?”
We plan to expose origin and taxonomy metadata, providing information about how boundaries were sourced and the method used to generate them.