# Global FieldID Documentation

> Developer documentation for integrating with the Global FieldID system

Append .md to any documentation page URL to get its markdown version.

## Guides
- [Introduction to Global FieldID™ API](https://developer.varda.ag/docs/fid.md): The Global FieldID API enables applications to integrate with the Global FieldID System
- [Getting Started](https://developer.varda.ag/docs/getting-started.md)
- [Global FieldID Lookups](https://developer.varda.ag/docs/field-id-lookups.md): The `POST /field-searches` endpoint enables client applications to "lookup" IDs for fields using either a point anywhere within the field or a boundary.
- [Global FieldID Identifiers](https://developer.varda.ag/docs/gfid-identifiers.md): This guide explains the different types of identifier used in the Global FieldID system, and how to represent them in your applications.
- [Requesting Access Tokens](https://developer.varda.ag/docs/request-access-token.md)
- [How to use GFID and SICAR together](https://developer.varda.ag/docs/how-to-use-gfid-and-sicar-together.md): How the Global FieldID system interacts with and enhances other existing farm and field reference datasets, and in particular the Sistema Nacional de Cadastro Ambiental Rural (SICAR).
- [Field creation and replacement](https://developer.varda.ag/docs/global-field-id-creation.md): The `POST /fields` endpoint enables client applications to create one or more fields in the GFID system.
- [Creation of public or private custom shapes in GFID](https://developer.varda.ag/docs/creation-of-custom-shapes.md): The `POST /boundaries` endpoint enables client applications to create boundaries with custom shapes in the GFID system.
- [Field boundary replacement](https://developer.varda.ag/docs/field-boundary-replacement.md): The `PATCH /fields/{id}` endpoint enables client applications to update the boundary of a field.
- [Updating permissions of a boundary](https://developer.varda.ag/docs/updating-permissions-of-a-boundary.md): The `PATCH /boundary-references/{id}/permissions` endpoint enables client applications to update permissions on a boundary reference and, in cascade, to the linked boundary.
- [Merging fields](https://developer.varda.ag/docs/merging-fields.md): GFID system allows merging multiple fields into one.
- [Splitting a field](https://developer.varda.ag/docs/splitting-a-field.md): GFID system allows splitting a field into multiple fields.
- [Deleting a field](https://developer.varda.ag/docs/deleting-a-field.md): GFID system allows deletion of fields.
- [Varda Service Hub](https://developer.varda.ag/docs/varda-service-hub.md): Create M2M applications, organisations and invite members to it
- [How to create a M2M app](https://developer.varda.ag/docs/how-to-create-a-m2m-app.md): A step by step guide to create your machine to machine applications
- [Release notes](https://developer.varda.ag/docs/release-notes.md)
- [Roadmap](https://developer.varda.ag/docs/roadmap.md): GFID roadmap

## API Reference
- [Obtain OAuth Token](https://developer.varda.ag/reference/post_oauth-token.md): This endpoint allows clients to obtain an OAuth token using client credentials.
- [Look up FieldIDs for a given Point, Polygon or MultiPolygon.](https://developer.varda.ag/reference/field_searches-1.md): This endpoint returns the fields intersecting input geometry, along with active BoundaryIDs.  It supports two types of inputs:  1. <b>Point</b>  2. <b>Polygon</b> (or <b>MultiPolygon</b>)  For #2 the ratio of overlap and the IoU score are added to the output.<br><b>Spatial search area limit is 25 km<sup>2</sup></b>.  GeoJSON input can be provided directly or encapsulated within the geometry of a GeoJSON Feature. Input must comply with [**ISO 19125**](https://www.iso.org/standard/40114.html).
- [Look up a field by its Global FieldID.](https://developer.varda.ag/reference/get_field_by_field_id-1.md): This endpoint returns the data for the provided FieldID. Data includes the current active BoundaryID.
- [Modify existing field](https://developer.varda.ag/reference/patch_field-1.md): This endpoint is used to modify a given field.  The input is a JSON object containing the following keys:  - boundary (optional, default=null): it defines the boundary of the field. It is a GeoJSON Feature, same as the input payload for <b>POST /boundaries endpoint</b>.   - Note: permissions will be applied to the boundary reference while <b>the field boundary will always be visible by any tenant</b>.  - effective_from: The date from which the boundary of the field is active (optional, default=now()).   - Formats: YYYY-MM-DD, YYYY-MM-DDThh:mm:ss   - Value: inclusive - autoedit: It dictates if the input geometry can be modified or not, if necessary, to make it fit into Varda default layer (optional, default=false)  The output is a JSON object containing the following data: - active_boundary_id (UUID or null): The ID of the "active boundary according to Varda" created out of the "boundary according to the source". - effective_from, effective_to: Current lifetime range of the field.  Note: GeoJSON numeric precision will be limited to 15 decimal places.  <i>Note: Please reach out to our support team if you want to get access to this endpoint.</i>
- [Deactivate a field by its Global FieldID.](https://developer.varda.ag/reference/delete_field-1.md): This endpoint is used to deactivate a field, restricting its existence to the current time. Past fields cannot be deleted.  <i>Note: Please reach out to our support team if you want to get access to this endpoint.</i>
- [Look up boundaries using a Global FieldID.](https://developer.varda.ag/reference/get_field_boundaries_by_field_id-1.md): This endpoint returns a collection of boundaries for the provided FieldID.<br>Each boundary contains <b>effective_from/effective_to</b> date-time properties in ISO-8601 format to describe the validity interval.<br><br>Optional parameters define a time range:<br>- [from, to]: if an interval is specified, output collection will contain boundaries active in that time range<br>- [from, ]: the time interval is open ended and will include current date-time<br>- [, to]: only boundaries active until specified value are returned<br>- [, ]: if no parameters are provided, the only boundary returned in the collection is the current active boundary of the field.<br><br>Boundaries are returned in reverse chronological order.
- [Create a field in the system.](https://developer.varda.ag/reference/post_field-1.md): This endpoint is used to create a field in the system.  Payload is a JSON object (or array of objects) containing the following keys:  - boundary: it defines the boundary of the field. It is a GeoJSON Feature, same as the input payload for <b>POST /boundaries endpoint</b>.   - Note: permissions will be applied to the boundary reference while <b>the field boundary will always be visible by any tenant</b>.  - boundary_id: alternatively, you can pass the ID of an existing boundary instead of geometry payload (<b>id</b> from response of POST /boundaries endpoint).   - Note:  you need to provide either boundary or boundary_id.   - Note:  provided boundary will be made public.    - effective_from: The date from which the boundary of the field is active (optional).   - Default: now()   - Formats: YYYY-MM-DD, YYYY-MM-DDThh:mm:ss   - Value: inclusive - autoedit: It dictates if the input geometry can be modified or not, if necessary, to make it fit into Varda default layer of field boundaries (optional, default=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 pocess to fail (optional, default=false).   - name: The name of the field (optional, default=''). - description: The description of the field (optional, default='').  The output is a JSON object (or array of objects) containing following data: - field_id: The ID that the system assigned to the field. - active_boundary_id: The ID of the "active boundary according to Varda" created out of the "boundary according to the source". - created_at: The time when the field got created in the system. - effective_from, effective_to: Current lifetime range of the field.  When payload contains an array the request will succeed only if all items will be registered as fields.  Query parameter "<b>dry_run</b>" (optional, default=false) allows to simulate request outcome without applying changes to the data. Responses when <b>dry_run=true</b> are HTTP204 on success or error (including details) on failure  Note: GeoJSON numeric precision will be limited to 15 decimal places.  <i>Note: Please reach out to our support team if you want to get access to this endpoint.</i>
- [Create a boundary in the system.](https://developer.varda.ag/reference/post_boundaries-1.md): This endpoint is used to create a boundary in the system.  The input is a GeoJSON feature:   - <pre>"type": "Feature"</pre>   - <pre>"id" (optional, string/number)</pre>The value used by the source to identify the boundary. If provided, it can be used as a filter.   - <pre>"geometry"</pre>The GeoJSON geometry data. Endpoint supports two geometry types: Polygon and MultiPolygon.    - <pre>"properties"</pre>     - <pre>"varda:source_name" (mandatory)</pre> Value must be one of the source_name you are assigned by Varda.      - <pre>"varda:permissions" (optional)</pre> <b>"{tenant_id}":"{permission_value}"</b> string pairs encoded in a JSON object to define boundary permissions for other tenants:       - <b>tenant_id</b>: tenant ID to which the specific permission will be granted. Reserved keyword <b>"all"</b> meaning all tenants;       - <b>permission_value</b>: one of the following:         - <b>discover</b>: the specified tenant can discover the boundary in search results but no geometry information will be returned         - <b>view</b>: same as <b>discover</b> plus geometry will be returned         - <b>manage</b>: same as <b>view</b> plus the <b>varda:permissions</b> object will be returned in endpoint responses (where available) and permissions editing will be enabled        Default value: <b>{"{tenant_id}": "manage", "all": "view"}</b>. Boundary will belong to the "public registry" with the tenant that ingested the boundary as a manager. Geometry data will be available to all tenants. By default <b>manage</b> role will be assigned to the caller tenant.     - <pre>"{custom-property}" (optional)</pre>User-defined properties can be recorded, representing any metadata the client wishes to associate with the boundary. Only <b>number, string, boolean, null</b> are supported.  The output is a GeoJSON Feature.  Query parameter "<b>dry_run</b>" (optional, default=false) allows to simulate request outcome without applying changes to the data. Responses when <b>dry_run=true</b> are HTTP204 on success or error (including details) on failure  <i>Note: GeoJSON numeric precision will be limited to 15 decimal places.</i>  <i>Note: Please reach out to our support team if you want to get access to this endpoint.</i>
- [Look up boundaries by spatial and/or field relationship search.](https://developer.varda.ag/reference/get_boundaries_by_spatial_field_relationship_search-1.md): This endpoint supports the following types of searches:  - <b>boundaries overlapping a point, polygon, multipolygon, feature, a bbox or a boundary/list of boundaries</b>:   - The point can be expressed as lon/lat, point, geohash, with <b>buffer</b> parameter defining the maximum allowed distance. <b>Spatial search area limit is 25 km<sup>2</sup></b> (also in case of bbox and geometry in input).   - The boundary/list of boundaries must be specified in the format <pre>boundary_relationships.boundary_id=<UUID_1>,<UUID_2></pre> with <pre>boundary_relationships.type=overlaps</pre>   - The response can be restricted to just field boundaries by setting <pre>field_relationships.type=delineates</pre> - <b>boundaries delineating fields</b>:   - The list of fields must be specified in the format <pre>field_relationships.field_id=123A.BCDE,456F.GHIL,...</pre> field_relationships.type is defaulted to 'delineates'.<br>Optionally, the search can be restricted to field boundaries active during a specific period of time by specifying <pre>field_relationships.effective_from=YYYY-MM-DD</pre><pre>field_relationships.effective_to=YYYY-MM-DD</pre>Parameters define a time range:<br>- [from, to]: if an interval is specified, output collection will contain boundaries active in that time range<br>- [from, ]: the time interval is open ended and will include current date-time<br>- [, to]: only boundaries active until specified value are returned<br>- [, ]: if no parameters are provided, the only boundary returned in the collection is the current active boundary of the field.  Boundaries are returned as a GeoJSON FeatureCollection. Metadata is always included in response for each boundary, while geometry is provided only if policy allows (i.e., if the geometry is 'shared' or accessible to the tenant performing the search).
- [Look up a boundary by its Global BoundaryID.](https://developer.varda.ag/reference/get_boundary_by_id-1.md): This endpoint returns boundary data and metadata for the provided BoundaryID.
- [Look up boundary references](https://developer.varda.ag/reference/get_boundary_references-1.md): This endpoint performs a search of boundary references, filtering them by provided input parameters.  Response will contain a FeatureCollection. GeoJSON geometries will be returned only for:  - boundary references with a "shared" view policy  - boundary references owned by the tenant making the request  Otherwise "geometry" key will be null.
- [Look up boundary references by ID.](https://developer.varda.ag/reference/get_boundary_references_by_id-1.md): This endpoint returns a GeoJSON Feature for the provided boundary reference ID.
- [Update boundary reference permissions](https://developer.varda.ag/reference/patch_boundary_references_permissions-1.md): This endpoint is used to modify permissions for a given boundary reference.  The input is a key/value JSON object where:    - each key corresponds to a "<b>tenant id</b>" or reserved keyword "<b>all</b>" to define every tenant    - values are one of: <b>discover, view, manage</b>  Input permissions will override existing permissions. If no <b>manage</b> permission is specified, the current managers will remain unchanged.  For more information on permissions please refer to the corresponding guideline pages.  <i>Note: Please reach out to our support team if you want to get access to this endpoint.</i>
- [Returns the tenant, client and user information](https://developer.varda.ag/reference/get_info-1.md): This endpoint returns information about the API tenant, client, user. Such information can be used in permissions objects
- [Returns the merged geometry of the provided boundaries.](https://developer.varda.ag/reference/get_merged_geometry-1.md): This endpoint returns the merged geometry of the provided boundaries. The list of boundaries must be specified in the format: <pre>boundary_ids=<UUID_1>,<UUID_2> .</pre> <b>Note: Upto a max of 10 boundaries can be provided as an input.</b>
- [Look up FieldIDs for a given Point, Polygon or MultiPolygon.](https://developer.varda.ag/reference/field_searches.md): This endpoint returns the fields intersecting input geometry, along with active BoundaryIDs.  It supports two types of inputs:  1. <b>Point</b>  2. <b>Polygon</b> (or <b>MultiPolygon</b>)  For #2 the ratio of overlap and the IoU score are added to the output.<br><b>Spatial search area limit is 25 km<sup>2</sup></b>.  GeoJSON input can be provided directly or encapsulated within the geometry of a GeoJSON Feature. Input must comply with [**ISO 19125**](https://www.iso.org/standard/40114.html).
- [Look up a field by its Global FieldID.](https://developer.varda.ag/reference/get_field_by_field_id.md): This endpoint returns the data for the provided FieldID. Data includes the current active BoundaryID.
- [Modify existing field](https://developer.varda.ag/reference/patch_field.md): This endpoint is used to modify a given field.  The input is a JSON object containing the following keys:  - boundary (optional, default=null): it defines the boundary of the field. It is a GeoJSON Feature, same as the input payload for <b>POST /boundaries endpoint</b>.   - Note: permissions will be applied to the boundary reference while <b>the field boundary will always be visible by any tenant</b>.  - effective_from: The date from which the boundary of the field is active (optional, default=now()).   - Formats: YYYY-MM-DD, YYYY-MM-DDThh:mm:ss   - Value: inclusive - autoedit: It dictates if the input geometry can be modified or not, if necessary, to make it fit into Varda default layer (optional, default=false)  The output is a JSON object containing the following data: - active_boundary_id (UUID or null): The ID of the "active boundary according to Varda" created out of the "boundary according to the source". - effective_from, effective_to: Current lifetime range of the field.  Note: GeoJSON numeric precision will be limited to 15 decimal places.  <i>Note: Please reach out to our support team if you want to get access to this endpoint.</i>
- [Deactivate a field by its Global FieldID.](https://developer.varda.ag/reference/delete_field.md): This endpoint is used to deactivate a field, restricting its existence to the current time. Past fields cannot be deleted.  <i>Note: Please reach out to our support team if you want to get access to this endpoint.</i>
- [Look up boundaries using a Global FieldID.](https://developer.varda.ag/reference/get_field_boundaries_by_field_id.md): This endpoint returns a collection of boundaries for the provided FieldID.<br>Each boundary contains <b>effective_from/effective_to</b> date-time properties in ISO-8601 format to describe the validity interval.<br><br>Optional parameters define a time range:<br>- [from, to]: if an interval is specified, output collection will contain boundaries active in that time range<br>- [from, ]: the time interval is open ended and will include current date-time<br>- [, to]: only boundaries active until specified value are returned<br>- [, ]: if no parameters are provided, the only boundary returned in the collection is the current active boundary of the field.<br><br>Boundaries are returned in reverse chronological order.
- [Create a field in the system.](https://developer.varda.ag/reference/post_field.md): This endpoint is used to create a field in the system.  Payload is a JSON object (or array of objects) containing the following keys:  - boundary: it defines the boundary of the field. It is a GeoJSON Feature, same as the input payload for <b>POST /boundaries endpoint</b>.   - Note: permissions will be applied to the boundary reference while <b>the field boundary will always be visible by any tenant</b>.  - boundary_id: alternatively, you can pass the ID of an existing boundary instead of geometry payload (<b>id</b> from response of POST /boundaries endpoint).   - Note:  you need to provide either boundary or boundary_id.   - Note:  provided boundary will be made public.    - effective_from: The date from which the boundary of the field is active (optional).   - Default: now()   - Formats: YYYY-MM-DD, YYYY-MM-DDThh:mm:ss   - Value: inclusive - autoedit: It dictates if the input geometry can be modified or not, if necessary, to make it fit into Varda default layer of field boundaries (optional, default=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 pocess to fail (optional, default=false).   - name: The name of the field (optional, default=''). - description: The description of the field (optional, default='').  The output is a JSON object (or array of objects) containing following data: - field_id: The ID that the system assigned to the field. - active_boundary_id: The ID of the "active boundary according to Varda" created out of the "boundary according to the source". - created_at: The time when the field got created in the system. - effective_from, effective_to: Current lifetime range of the field.  When payload contains an array the request will succeed only if all items will be registered as fields.  Query parameter "<b>dry_run</b>" (optional, default=false) allows to simulate request outcome without applying changes to the data. Responses when <b>dry_run=true</b> are HTTP204 on success or error (including details) on failure  Note: GeoJSON numeric precision will be limited to 15 decimal places.  <i>Note: Please reach out to our support team if you want to get access to this endpoint.</i>
- [Create a boundary in the system.](https://developer.varda.ag/reference/post_boundaries.md): This endpoint is used to create a boundary in the system.  The input is a GeoJSON feature:   - <pre>"type": "Feature"</pre>   - <pre>"id" (optional, string/number)</pre>The value used by the source to identify the boundary. If provided, it can be used as a filter.   - <pre>"geometry"</pre>The GeoJSON geometry data. Endpoint supports two geometry types: Polygon and MultiPolygon.    - <pre>"properties"</pre>     - <pre>"varda:source_name" (mandatory)</pre> Value must be one of the source_name you are assigned by Varda.      - <pre>"varda:permissions" (optional)</pre> <b>"{tenant_id}":"{permission_value}"</b> string pairs encoded in a JSON object to define boundary permissions for other tenants:       - <b>tenant_id</b>: tenant ID to which the specific permission will be granted. Reserved keyword <b>"all"</b> meaning all tenants;       - <b>permission_value</b>: one of the following:         - <b>discover</b>: the specified tenant can discover the boundary in search results but no geometry information will be returned         - <b>view</b>: same as <b>discover</b> plus geometry will be returned         - <b>manage</b>: same as <b>view</b> plus the <b>varda:permissions</b> object will be returned in endpoint responses (where available) and permissions editing will be enabled        Default value: <b>{"{tenant_id}": "manage", "all": "view"}</b>. Boundary will belong to the "public registry" with the tenant that ingested the boundary as a manager. Geometry data will be available to all tenants. By default <b>manage</b> role will be assigned to the caller tenant.     - <pre>"{custom-property}" (optional)</pre>User-defined properties can be recorded, representing any metadata the client wishes to associate with the boundary. Only <b>number, string, boolean, null</b> are supported.  The output is a GeoJSON Feature.  Query parameter "<b>dry_run</b>" (optional, default=false) allows to simulate request outcome without applying changes to the data. Responses when <b>dry_run=true</b> are HTTP204 on success or error (including details) on failure  <i>Note: GeoJSON numeric precision will be limited to 15 decimal places.</i>  <i>Note: Please reach out to our support team if you want to get access to this endpoint.</i>
- [Look up boundaries by spatial and/or field relationship search.](https://developer.varda.ag/reference/get_boundaries_by_spatial_field_relationship_search.md): This endpoint supports the following types of searches:  - <b>boundaries overlapping a point, polygon, multipolygon, feature, a bbox or a boundary/list of boundaries</b>:   - The point can be expressed as lon/lat, point, geohash, with <b>buffer</b> parameter defining the maximum allowed distance. <b>Spatial search area limit is 25 km<sup>2</sup></b> (also in case of bbox and geometry in input).   - The boundary/list of boundaries must be specified in the format <pre>boundary_relationships.boundary_id=<UUID_1>,<UUID_2></pre> with <pre>boundary_relationships.type=overlaps</pre>   - The response can be restricted to just field boundaries by setting <pre>field_relationships.type=delineates</pre> - <b>boundaries delineating fields</b>:   - The list of fields must be specified in the format <pre>field_relationships.field_id=123A.BCDE,456F.GHIL,...</pre> field_relationships.type is defaulted to 'delineates'.<br>Optionally, the search can be restricted to field boundaries active during a specific period of time by specifying <pre>field_relationships.effective_from=YYYY-MM-DD</pre><pre>field_relationships.effective_to=YYYY-MM-DD</pre>Parameters define a time range:<br>- [from, to]: if an interval is specified, output collection will contain boundaries active in that time range<br>- [from, ]: the time interval is open ended and will include current date-time<br>- [, to]: only boundaries active until specified value are returned<br>- [, ]: if no parameters are provided, the only boundary returned in the collection is the current active boundary of the field.  Boundaries are returned as a GeoJSON FeatureCollection. Metadata is always included in response for each boundary, while geometry is provided only if policy allows (i.e., if the geometry is 'shared' or accessible to the tenant performing the search).
- [Look up a boundary by its Global BoundaryID.](https://developer.varda.ag/reference/get_boundary_by_id.md): This endpoint returns boundary data and metadata for the provided BoundaryID.
- [Look up boundary references](https://developer.varda.ag/reference/get_boundary_references.md): This endpoint performs a search of boundary references, filtering them by provided input parameters.  Response will contain a FeatureCollection. GeoJSON geometries will be returned only for:  - boundary references with a "shared" view policy  - boundary references owned by the tenant making the request  Otherwise "geometry" key will be null.
- [Look up boundary references by ID.](https://developer.varda.ag/reference/get_boundary_references_by_id.md): This endpoint returns a GeoJSON Feature for the provided boundary reference ID.
- [Update boundary reference permissions](https://developer.varda.ag/reference/patch_boundary_references_permissions.md): This endpoint is used to modify permissions for a given boundary reference.  The input is a key/value JSON object where:    - each key corresponds to a "<b>tenant id</b>" or reserved keyword "<b>all</b>" to define every tenant    - values are one of: <b>discover, view, manage</b>  Input permissions will override existing permissions. If no <b>manage</b> permission is specified, the current managers will remain unchanged.  For more information on permissions please refer to the corresponding guideline pages.  <i>Note: Please reach out to our support team if you want to get access to this endpoint.</i>
- [Returns the tenant, client and user information](https://developer.varda.ag/reference/get_info.md): This endpoint returns information about the API tenant, client, user. Such information can be used in permissions objects
- [Returns the merged geometry of the provided boundaries.](https://developer.varda.ag/reference/get_merged_geometry.md): This endpoint returns the merged geometry of the provided boundaries. The list of boundaries must be specified in the format: <pre>boundary_ids=<UUID_1>,<UUID_2> .</pre> <b>Note: Upto a max of 10 boundaries can be provided as an input.</b>

## Changelog
- [Welcome to Global FieldID](https://developer.varda.ag/changelog/welcome-to-global-fieldid.md)