How to use GFID and SICAR together

The Global FieldID API enables developers to implement three main scenarios. 

If you already have a copy of the SICAR database within your organisation and use it in your business processes, you may already have access to the farm boundary. You can use this boundary to execute a simple search on the FieldID database, to obtain a list of Global FieldIDs within the property, importing into your system all the fields within a property in a single step. To do this, send the coordinates of the boundary to the API as a GeoJSON polygon, as described in our developer guide. 

You will receive a list of matches, as well as metrics indicating the quality of the match and the ID of the field’s primary boundary. This boundary will never overlap with another field at the same time, so you can use them to place fields on the map. 

Note that boundaries can, to a limited extent, change over time and can even be replaced with new FieldIDs – the system enables you to track these changes, but that is beyond the scope of this article.

If you do not have a copy of the SICAR farm boundary but know the ID (e.g. the farmer supplies it), you can use it as a ‘key’ to find related field boundaries that overlap with the SICAR boundary. This works because we have pre-loaded the SICAR boundaries, and the system calculates the relationships between all other boundaries. The system can also be used to find spatial overlaps with any other boundary in the system, including other SICAR boundaries, but for now we focus on finding canonical field boundaries. 

There are two steps: 

• Call GET /boundary-references?source_name=SICAR&user_provided_key=<COD_IMOVEL> to fetch the Global BoundaryID of the SICAR boundary e.g. GET /boundary-references?source_name=SICAR&user_provided_key=DF-5300108-9C5F2B5FF1E44CF4AFAA3FA9735C29F4 to obtain the Global BoundaryID of the SICAR boundary with COD_IMOVEL=DF-5300108-9C5F2B5FF1E44CF4AFAA3FA9735C29F4
• Call GET /boundaries? boundary_relationships.boundary_id=<boundaryID>& field_relationships.type=delineates

The result is a GeoJSON FeatureCollection containing all boundary features that overlap with the SICAR boundary, filtered for those that are currently the active boundary of a field (in other words, field boundaries). Field boundaries contain a property indicating the Global FieldID, as well as the boundary geometry and other spatial information such as area and perimeter. 

Although the SICAR database is available to the public, it is not possible to directly interrogate it using structured queries. It is necessary for anyone using the SICAR to download a series of files, and load them into a database they maintain. In order to make it easier to work with the SICAR and FieldID together, we have pre-registered SICAR boundaries within the FieldID system, and therefore you can use the FieldID API to query for and download SICAR boundaries and metadata. 

If you want to know within which SICAR farm boundary a given FieldID is falling, two steps are needed: 

• Call GET /fields/{id} to fetch the Global BoundaryID of the field with the known FieldID (assuming you do not know the Global BoundaryID already) 

• Call GET /boundaries?boundary_relationships.boundary_id=<boundaryID> to obtain the boundaries overlapping with the given field boundary 

The result is a GeoJSON FeatureCollection containing all boundary features that overlap with the field boundary. Among all the boundary features, you can select the one for which source_name=SICAR to obtain the SICAR farm boundary with which the field boundary overlaps. Please note that there may be cases in which the collection contains multiple SICAR boundaries i.e., the field boundary falls within multiple SICAR farm boundaries, and this is due to the fact that SICAR farm boundaries can overlap among themselves.  

If you want to obtain all the SICAR farm boundaries within a given bbox: 

• Call GET /boundaries?bbox=<bbox> to obtain the boundaries overlapping the bbox. 

Given that the output GeoJSON FeatureCollection contain all boundary features that overlap with the bbox, you can select the one for which source_name=SICAR to obtain just the SICAR farm boundaries within the given bbox.