OpenSPP · anthonymarkQA · Oct 24, 2025 · Oct 22, 2025 · Oct 22, 2025 · Oct 24, 2025
diff --git a/docs/user_guide/administration/farmer_geolocation.md b/docs/user_guide/administration/farmer_geolocation.md
@@ -0,0 +1,73 @@
+# Integrate geolocation
+
+This guide provides step-by-step instructions for integrating geolocation platforms such as MapTiler with the OpenSPP Farmer Registry module to enhance area-based functionality.
+
+## Prerequisites
+To enable geolocation integration in OpenSPP, ensure the following:
+- Your user account has the System Admin role. Learn more in this guide: {doc}`user_access`.
+- Your OpenSPP instance has the Farmer Registry base module installed. Learn more in this guide: {doc}`../../getting_started/farmer_installation`.
+- You have an API key for MapTiler to enable GIS functionality. You can retrieve this by checking their documentation [here](https://docs.maptiler.com/cloud/api/).
+- Developer mode in OpenSPP is enabled to allow configuration of the MapTiler key. For details, refer to the {doc}`../../developer_guide/developer_mode`.
+
+## Objective
+By the end of this guide, you will have configured MapTiler integration to enable area-based features in the Farmer Registry and will learn how to add, edit, and remove farm geolocation data using the map tools.
+
+## Process
+
+### Setting Up the API Key for MapTiler
+As a System Admin, log in to your OpenSPP Farmer Registry instance. Go to **Settings**, then select **Technical**, and click **System Parameters**.
+
+![Settings menu with Technical and System Parameters options](farmer_geolocation/farmer_geolocation_system_parameters.png)
+
+Click the **New** button. Set the Key field to **spp_base_gis.map_tiler_api_key** and enter your MapTiler API key in the **value** field.
+
+![Setup farmer registry maptiler key](farmer_geolocation/farmer_geolocation_maptiler_key.png)
+
+```{note}
+Keep your API key secure. Avoid sharing it publicly or storing it in version control systems.
+```
+
+Click the **Save** button to apply the configuration. Refresh your browser to see the changes.
+
+### Add Geolocation Data
+
+After setting up the API key for the geolocation platform, navigate to the Registry and click an existing farm group, then open the **Farm Details** tab.
+
+![Farm details tab](farmer_geolocation/farmer_geolocation_farm_details.png)
+
+#### Add Address Coordinates
+
+Under the **Farm Details** tab, click **Address Coordinates**.
+
+Click the Marker tool once, then select a location on the map to add a pin for the farm.
+
+![Marker button](farmer_geolocation/farmer_geolocation_marker_button.png)
+
+You can also click the **Find My Location** button to center the map on your current location.
+
+![Find my location button](farmer_geolocation/farmer_geolocation_find_my_location.png)
+
+#### Add Farm Land
+
+Under the **Farm Details** tab, click **Farm Land**.
+
+Click the polygon tool once, then click the map to add vertices until the area is outlined; double-click the final point to close the polygon.
+
+![polygon tool](farmer_geolocation/farmer_geolocation_polygon_tool.png)
+
+You can also click the **Find My Location** button to center the map on your current location.
+
+![Find my location button](farmer_geolocation/farmer_geolocation_find_my_location.png)
+
+### Remove Geolocation Data
+
+To remove geolocation data, navigate to the **Farm Details** tab, then open the tab for either **Address Coordinates** or **Farm Land**.
+
+Click the trash icon to remove the geolocation data.
+
+![Delete button](farmer_geolocation/farmer_geolocation_delete_button.png)
+
+```{note}
+- The trash icon appears only when there is existing map data.
+- Deletion cannot be undone.
+```
diff --git a/...er_guide/administration/farmer_geolocation/farmer_geolocation_delete_button.png b/...er_guide/administration/farmer_geolocation/farmer_geolocation_delete_button.png
diff --git a/...ser_guide/administration/farmer_geolocation/farmer_geolocation_farm_details.png b/...ser_guide/administration/farmer_geolocation/farmer_geolocation_farm_details.png
diff --git a/...guide/administration/farmer_geolocation/farmer_geolocation_find_my_location.png b/...guide/administration/farmer_geolocation/farmer_geolocation_find_my_location.png
diff --git a/...ry/setup_farmer_registry_maptiler_key.png → ...ation/farmer_geolocation_maptiler_key.png b/...ry/setup_farmer_registry_maptiler_key.png → ...ation/farmer_geolocation_maptiler_key.png
diff --git a/...er_guide/administration/farmer_geolocation/farmer_geolocation_marker_button.png b/...er_guide/administration/farmer_geolocation/farmer_geolocation_marker_button.png
diff --git a/...ser_guide/administration/farmer_geolocation/farmer_geolocation_polygon_tool.png b/...ser_guide/administration/farmer_geolocation/farmer_geolocation_polygon_tool.png
diff --git a/...nagement/setting_up_farmer_registry/5.png → .../farmer_geolocation_system_parameters.png b/...nagement/setting_up_farmer_registry/5.png → .../farmer_geolocation_system_parameters.png
diff --git a/docs/user_guide/administration/index.md b/docs/user_guide/administration/index.md
@@ -15,6 +15,8 @@ This section provides guides for a variety of administrative tasks and system ma
 
 - {doc}`inventory_configuration`: Learn how to configure the necessary inventory settings to support in-kind and basket entitlements.
 
+- {doc}`farmer_geolocation`: Guide to enabling geolocation integration in the OpenSPP Farmer Registry to improve area-based operations.
+
 - {doc}`incoming_email_configuration`: A guide to setting up automatic email retrieval and processing from a designated incoming mailbox.
 
 - {doc}`outgoing_email_configuration`: A guide to setting up outgoing email servers for automated messaging and data integration.
@@ -41,6 +43,7 @@ User access <user_access>
 Custom fields <custom_fields>
 Indicator fields <indicator_fields>
 Import areas <import_areas>
+Integrate geolocation <farmer_geolocation>
 Service points <service_points>
 Inventory setup <inventory_configuration>
 Incoming email setup <incoming_email_configuration>

diff --git a/docs/user_guide/index.md b/docs/user_guide/index.md
@@ -9,7 +9,6 @@ Guides for managing registrant data and registry operations:
 
 - {doc}`registry_management/register_individual`
 - {doc}`registry_management/import_export_registrant_data`
-- {doc}`registry_management/setting_up_farmer_registry`
 - {doc}`registry_management/identity_management`
 - {doc}`registry_management/using_change_requests`
 - {doc}`registry_management/using_event_data`
@@ -37,6 +36,7 @@ Administrative tasks and system management:
 - {doc}`administration/indicator_fields`
 - {doc}`administration/import_areas`
 - {doc}`administration/inventory_configuration`
+- {doc}`administration/farmer_geolocation`
 - {doc}`administration/incoming_email_configuration`
 - {doc}`administration/outgoing_email_configuration`
 - {doc}`administration/hardware_integration`

diff --git a/docs/user_guide/registry_management/index.md b/docs/user_guide/registry_management/index.md
@@ -11,8 +11,6 @@ This section provides essential guides for managing the core of OpenSPP: the reg
 
 - {doc}`register_individual`: Details the process of manually creating individual and group records and associating individuals as members of a group.
 
-- {doc}`setting_up_farmer_registry`: Instructions for installing and configuring the Farmer Registry module, including the generation of sample farmer data.
-
 - {doc}`using_change_requests`: Explains how to use the Change Request module to update registrant information, including the workflow for initiating, validating, and approving changes.
 
 - {doc}`using_event_data`: This guide explains how to use the Event Data feature to record and track significant occurrences related to registrants over time.
@@ -24,7 +22,6 @@ This section provides essential guides for managing the core of OpenSPP: the reg
 
 Register individuals <register_individual>
 Import/Export data <import_export_registrant_data>
-Farmer Registry setup <setting_up_farmer_registry>
 Identity management <identity_management>
 Change requests <using_change_requests>
 Event data <using_event_data>

diff --git a/docs/user_guide/registry_management/setting_up_farmer_registry.md b/docs/user_guide/registry_management/setting_up_farmer_registry.md
diff --git a/docs/user_guide/registry_management/setting_up_farmer_registry/1.png b/docs/user_guide/registry_management/setting_up_farmer_registry/1.png
diff --git a/docs/user_guide/registry_management/setting_up_farmer_registry/2.1.png b/docs/user_guide/registry_management/setting_up_farmer_registry/2.1.png
diff --git a/docs/user_guide/registry_management/setting_up_farmer_registry/2.2.png b/docs/user_guide/registry_management/setting_up_farmer_registry/2.2.png
diff --git a/docs/user_guide/registry_management/setting_up_farmer_registry/3.png b/docs/user_guide/registry_management/setting_up_farmer_registry/3.png
diff --git a/docs/user_guide/registry_management/setting_up_farmer_registry/4.png b/docs/user_guide/registry_management/setting_up_farmer_registry/4.png
diff --git a/docs/user_guide/registry_management/setting_up_farmer_registry/6.png b/docs/user_guide/registry_management/setting_up_farmer_registry/6.png
diff --git a/...istry_management/setting_up_farmer_registry/setup_farmer_registry_apps_icon.png b/...istry_management/setting_up_farmer_registry/setup_farmer_registry_apps_icon.png
diff --git a/...agement/setting_up_farmer_registry/setup_farmer_registry_define_sample_data.png b/...agement/setting_up_farmer_registry/setup_farmer_registry_define_sample_data.png
diff --git a/...management/setting_up_farmer_registry/setup_farmer_registry_generate_button.png b/...management/setting_up_farmer_registry/setup_farmer_registry_generate_button.png